| Copyright | (c) 2013-2017 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay+amazonka@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
- fromTemporarySession :: AccessKey -> SecretKey -> SessionToken -> UTCTime -> 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)
- fromContainer :: (MonadIO m, MonadThrow m) => Manager -> 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. |
| FromContainer | Obtain credentials by attempting to contact the ECS container agent
at http://169.254.170.2 using the path in |
| 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 #
Temporary credentials from a STS session consisting of the access key, secret key, and session token.
See: fromTemporarySession
fromTemporarySession :: AccessKey -> SecretKey -> SessionToken -> UTCTime -> Auth Source #
Temporary credentials from a STS session consisting of the access key, secret key, session token, and expiration time.
See: fromSession
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.
Additionally starts a refresh thread for the given authentication environment.
The resulting IORef 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 before expiration.
A weak reference is used to ensure that the forked thread will eventually
terminate when Auth is no longer referenced.
If no session token or expiration time is present the credentials will be returned verbatim.
fromContainer :: (MonadIO m, MonadThrow m) => Manager -> m (Auth, Maybe Region) Source #
Obtain credentials exposed to a task via the ECS container agent, as
described in the IAM Roles for Tasks
section of the AWS ECS documentation. The credentials are obtained by making
a request to http://169.254.170.2 at the path contained by the
envContainerCredentialsURI environment variable.
The ECS container agent provides an access key, secret key, session token,
and expiration time, but it does not include a region, so the region will
attempt to be determined from the envRegion environment variable if it is
set.
Like fromProfileName, additionally starts a refresh thread that will
periodically fetch fresh credentials before the current ones expire.
Throws MissingEnvError if the envContainerCredentialsURI environment
variable is not set or InvalidIAMError if the payload returned by the ECS
container agent is not of the expected format.
Keys
An access key ID.
For example: AKIAIOSFODNN7EXAMPLE
Constructors
| AccessKey ByteString |
Secret access key credential.
For example: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKE
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.