Network.AWS.Auth

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.

Authentication

Retrieving authentication

getAuth :: (Applicative m, MonadIO m, MonadCatch m) => Manager -> Credentials -> m Auth

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

Determines how AuthN/AuthZ information is retrieved.

Constructors

FromKeys AccessKey SecretKey

Explicit access and secret keys. See fromKeys.

FromSession AccessKey SecretKey SessionToken

Explicit access key, secret key and a session token. See fromSession.

FromEnv Text Text (Maybe Text)

Lookup specific environment variables for access key, secret key, and an optional session token 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 to credentials discovery via the following steps:

• Read the envAccessKey and envSecretKey from the environment if they are set.
• Read the credentials file if credFile exists.
• Retrieve the first available IAM profile if running on EC2.

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

Eq Credentials

Show Credentials

ToLog Credentials

data Auth :: *

An authorisation environment containing AWS credentials, and potentially a reference which can be refreshed out-of-band as temporary credentials expire.

Instances

ToLog Auth

Defaults

Environment

envAccessKey

Arguments

:: Text

AWS_ACCESS_KEY_ID

Default access key environment variable.

envSecretKey

Arguments

:: Text

AWS_SECRET_ACCESS_KEY

Default secret key environment variable.

envSessionToken

Arguments

:: Text

AWS_SESSION_TOKEN

Default session token environment variable.

Credentials File

credAccessKey

Arguments

:: Text

aws_access_key_id

Credentials INI file access key variable.

credSecretKey

Arguments

:: Text

aws_secret_access_key

Credentials INI file secret key variable.

credSessionToken

Arguments

:: Text

aws_session_token

Credentials INI file session token variable.

credProfile

Arguments

:: Text

default

Credentials INI default profile section variable.

credFile :: (MonadCatch m, MonadIO m) => m FilePath

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.)

getAuth is implemented using the following from*-styled functions below. Both fromKeys and fromSession can be used directly to avoid the MonadIO constraint.

fromKeys :: AccessKey -> SecretKey -> Auth

Explicit access and secret keys.

fromSession :: AccessKey -> SecretKey -> SessionToken -> Auth

A session containing the access key, secret key, and a session token.

fromEnv :: (Applicative m, MonadIO m, MonadThrow m) => m Auth

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.

See: envAccessKey, envSecretKey, envSessionToken

fromEnvKeys

Arguments

:: (Applicative m, MonadIO m, MonadThrow m)

=> Text

Access key environment variable.

-> Text

Secret key environment variable.

-> Maybe Text

Session token environment variable.

-> m Auth

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

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 and credFile

fromFilePath :: (Applicative m, MonadIO m, MonadCatch m) => Text -> FilePath -> m Auth

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

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

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

newtype AccessKey :: *

Access key credential.

Constructors

AccessKey ByteString

Instances

Eq AccessKey

Show AccessKey

IsString AccessKey

ToLog AccessKey

ToByteString AccessKey

ToText AccessKey

newtype SecretKey :: *

Secret key credential.

Constructors

SecretKey ByteString

Instances

Eq SecretKey

IsString SecretKey

ToByteString SecretKey

ToText SecretKey

newtype SessionToken :: *

A session token used by STS to temporarily authorise access to an AWS resource.

Constructors

SessionToken ByteString

Instances

Eq SessionToken

IsString SessionToken

ToByteString SessionToken

ToText SessionToken

Handling Errors

class AsAuthError a where

Minimal complete definition

_AuthError

Methods

_AuthError :: Prism' a AuthError

A general authentication error.

_RetrievalError :: Prism' a HttpException

An error occured while communicating over HTTP with the local metadata endpoint.

_MissingEnvError :: Prism' a Text

An error occured looking up a named environment variable.

_MissingFileError :: Prism' a FilePath

The specified credentials file could not be found.

_InvalidFileError :: Prism' a Text

An error occured parsing the credentials file.

_InvalidIAMError :: Prism' a Text

The specified IAM profile could not be found or deserialised.

Instances

AsAuthError SomeException

AsAuthError AuthError

data AuthError

An error thrown when attempting to read AuthN/AuthZ information.

Constructors

RetrievalError HttpException

MissingEnvError Text

MissingFileError FilePath

InvalidFileError Text

InvalidIAMError Text

Instances

Show AuthError

ToLog AuthError

Exception AuthError

AsAuthError AuthError

Typeable * AuthError