amazonka-1.4.5: Comprehensive Amazon Web Services SDK.

Copyright(c) 2013-2016 Brendan Hay
LicenseMozilla Public License, v. 2.0.
MaintainerBrendan Hay <brendan.g.hay@gmail.com>
Stabilityprovisional
Portabilitynon-portable (GHC extensions)
Safe HaskellNone
LanguageHaskell2010

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.

Synopsis

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

FromSession AccessKey SecretKey SessionToken

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

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:

  • Read the envAccessKey, envSecretKey, and envRegion from the environment if they are set.
  • Read the credentials file if credFile exists.
  • Retrieve the first available IAM profile and read the Region from the instance identity document, 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.

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 

Methods

build :: Auth -> Builder #

Defaults

Environment

envAccessKey Source #

Arguments

:: Text

AWS_ACCESS_KEY_ID

Default access key environment variable.

envSecretKey Source #

Arguments

:: Text

AWS_SECRET_ACCESS_KEY

Default secret key environment variable.

envSessionToken Source #

Arguments

:: Text

AWS_SESSION_TOKEN

Default session token environment variable.

Credentials File

credAccessKey Source #

Arguments

:: Text

aws_access_key_id

Credentials INI file access key variable.

credSecretKey Source #

Arguments

:: Text

aws_secret_access_key

Credentials INI file secret key variable.

credSessionToken Source #

Arguments

:: Text

aws_session_token

Credentials INI file session token variable.

credProfile Source #

Arguments

:: Text

default

Credentials INI default profile section 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.

fromKeys :: AccessKey -> SecretKey -> Auth Source #

Explicit access and secret keys.

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.

See: envAccessKey, envSecretKey, envSessionToken

fromEnvKeys Source #

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

newtype SecretKey :: * #

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

_AuthError

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.