| Copyright | (c) 2013-2016 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay@gmail.com> |
| Stability | provisional |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | None |
| Language | Haskell2010 |
Network.AWS.Auth
Contents
Description
Explicitly specify your Amazon AWS security credentials, or retrieve them from the underlying OS.
The format of environment variables and the credentials file follows the official AWS SDK guidelines.
- getAuth :: (Applicative m, MonadIO m, MonadCatch m) => Manager -> Credentials -> m (Auth, Maybe Region)
- data Credentials
- data Auth :: *
- envAccessKey :: Text
- envSecretKey :: Text
- envSessionToken :: Text
- credAccessKey :: Text
- credSecretKey :: Text
- credSessionToken :: Text
- credProfile :: Text
- credFile :: (MonadCatch m, MonadIO m) => m FilePath
- fromKeys :: AccessKey -> SecretKey -> Auth
- fromSession :: AccessKey -> SecretKey -> SessionToken -> Auth
- fromEnv :: (Applicative m, MonadIO m, MonadThrow m) => m (Auth, Maybe Region)
- fromEnvKeys :: (Applicative m, MonadIO m, MonadThrow m) => Text -> Text -> Maybe Text -> Maybe Text -> m (Auth, Maybe Region)
- fromFile :: (Applicative m, MonadIO m, MonadCatch m) => m (Auth, Maybe Region)
- fromFilePath :: (Applicative m, MonadIO m, MonadCatch m) => Text -> FilePath -> m (Auth, Maybe Region)
- fromProfile :: (MonadIO m, MonadCatch m) => Manager -> m (Auth, Maybe Region)
- fromProfileName :: (MonadIO m, MonadCatch m) => Manager -> Text -> m (Auth, Maybe Region)
- newtype AccessKey :: * = AccessKey ByteString
- newtype SecretKey :: * = SecretKey ByteString
- newtype SessionToken :: * = SessionToken ByteString
- class AsAuthError a where
- data AuthError
Authentication
Retrieving Authentication
getAuth :: (Applicative m, MonadIO m, MonadCatch m) => Manager -> Credentials -> m (Auth, Maybe Region) Source #
Retrieve authentication information via the specified Credentials mechanism.
Throws AuthError when environment variables or IAM profiles cannot be read,
and credentials files are invalid or cannot be found.
data Credentials Source #
Determines how AuthN/AuthZ information is retrieved.
Constructors
| FromKeys AccessKey SecretKey | Explicit access and secret keys. See |
| FromSession AccessKey SecretKey SessionToken | Explicit access key, secret key and a session token. See |
| FromEnv Text Text (Maybe Text) (Maybe Text) | Lookup specific environment variables for access key, secret key, an optional session token, and an optional region, respectively. |
| FromProfile Text | An IAM Profile name to lookup from the local EC2 instance-data. Environment variables to lookup for the access key, secret key and optional session token. |
| FromFile Text FilePath | A credentials profile name (the INI section) and the path to the AWS credentials file. |
| Discover | Attempt credentials discovery via the following steps:
An attempt is made to resolve http://instance-data rather than directly retrieving http://169.254.169.254 for IAM profile information. This assists in ensuring the DNS lookup terminates promptly if not running on EC2. |
Instances
An authorisation environment containing AWS credentials, and potentially a reference which can be refreshed out-of-band as temporary credentials expire.
Defaults
Environment
Arguments
| :: Text | AWS_SESSION_TOKEN |
Default session token environment variable.
Credentials File
Arguments
| :: Text | aws_secret_access_key |
Credentials INI file secret key variable.
Arguments
| :: Text | aws_session_token |
Credentials INI file session token variable.
credFile :: (MonadCatch m, MonadIO m) => m FilePath Source #
Default path for the credentials file. This looks in in the HOME directory
as determined by the directory
library.
- UNIXOSX: @$HOME.aws/credentials@
- Windows:
C:/Users//<user>.awscredentials
Note: This does not match the default AWS SDK location of
%USERPROFILE%.awscredentials on Windows. (Sorry.)
Credentials
getAuth is implemented using the following from*-styled functions below.
Both fromKeys and fromSession can be used directly to avoid the MonadIO
constraint.
fromSession :: AccessKey -> SecretKey -> SessionToken -> Auth Source #
A session containing the access key, secret key, and a session token.
fromEnv :: (Applicative m, MonadIO m, MonadThrow m) => m (Auth, Maybe Region) Source #
Retrieve access key, secret key, and a session token from the default environment variables.
Throws MissingEnvError if either of the default environment variables
cannot be read, but not if the session token is absent.
Arguments
| :: (Applicative m, MonadIO m, MonadThrow m) | |
| => Text | Access key environment variable. |
| -> Text | Secret key environment variable. |
| -> Maybe Text | Session token environment variable. |
| -> Maybe Text | Region environment variable. |
| -> m (Auth, Maybe Region) |
Retrieve access key, secret key and a session token from specific environment variables.
Throws MissingEnvError if either of the specified key environment variables
cannot be read, but not if the session token is absent.
fromFile :: (Applicative m, MonadIO m, MonadCatch m) => m (Auth, Maybe Region) Source #
Loads the default credentials INI file using the default profile name.
Throws MissingFileError if credFile is missing, or InvalidFileError
if an error occurs during parsing.
See: credProfile, credFile, and envProfile
fromFilePath :: (Applicative m, MonadIO m, MonadCatch m) => Text -> FilePath -> m (Auth, Maybe Region) Source #
Retrieve the access, secret and session token from the specified section
(profile) in a valid INI credentials file.
Throws MissingFileError if the specified file is missing, or InvalidFileError
if an error occurs during parsing.
fromProfile :: (MonadIO m, MonadCatch m) => Manager -> m (Auth, Maybe Region) Source #
Retrieve the default IAM Profile from the local EC2 instance-data.
The default IAM profile is determined by Amazon as the first profile found
in the response from:
http://169.254.169.254/latest/meta-data/iam/security-credentials/
Throws RetrievalError if the HTTP call fails, or InvalidIAMError if
the default IAM profile cannot be read.
fromProfileName :: (MonadIO m, MonadCatch m) => Manager -> Text -> m (Auth, Maybe Region) Source #
Lookup a specific IAM Profile by name from the local EC2 instance-data.
The resulting IONewRef wrapper + timer is designed so that multiple concurrent
accesses of AuthEnv from the AWS environment are not required to calculate
expiry and sequentially queue to update it.
The forked timer ensures a singular owner and pre-emptive refresh of the temporary session credentials.
A weak reference is used to ensure that the forked thread will eventually
terminate when Auth is no longer referenced.
Throws RetrievalError if the HTTP call fails, or InvalidIAMError if
the specified IAM profile cannot be read.
Keys
Access key credential.
Constructors
| AccessKey ByteString |
Secret key credential.
Constructors
| SecretKey ByteString |
newtype SessionToken :: * #
A session token used by STS to temporarily authorise access to an AWS resource.
Constructors
| SessionToken ByteString |
Handling Errors
class AsAuthError a where Source #
Minimal complete definition
Methods
_AuthError :: Prism' a AuthError Source #
A general authentication error.
_RetrievalError :: Prism' a HttpException Source #
An error occured while communicating over HTTP with the local metadata endpoint.
_MissingEnvError :: Prism' a Text Source #
The named environment variable was not found.
_InvalidEnvError :: Prism' a Text Source #
An error occured parsing named environment variable's value.
_MissingFileError :: Prism' a FilePath Source #
The specified credentials file could not be found.
_InvalidFileError :: Prism' a Text Source #
An error occured parsing the credentials file.
_InvalidIAMError :: Prism' a Text Source #
The specified IAM profile could not be found or deserialised.
Instances
An error thrown when attempting to read AuthN/AuthZ information.