the-sett / elm-auth-aws / AWS.Auth

Manages the state of the authentication process, and provides an API to request authentication operations.


type alias Config =
{ clientId : String
, region : AWS.Config.Region
, userIdentityMapping : Maybe UserIdentityMappingConfig
, authHeaderName : String
, authHeaderPrefix : Maybe String 
}

The configuration needed to interact with Cognito.

The userIdentityMapping field is optional. Fill it in and a request to obtain AWS credentials will be automatically made once logged in. That is to say that the user will be mapped to an AWS IAM identity, which can be used to access AWS services directly through request signing.

The authHeaderName field provides the name of the field into which the AuthAPI.addAuthHeaders function will set the authentication token. Almost always the Authorization header field is used.

The 'authHeaderPrefix' may provide a string with which the access token value is prefixed in the header field. Patterns like 'Bearer XXX' or 'Token XXX' are common. Note that the space will be automatically inserted between then prefix and the token, if a prefix is provided - so authHeaderPrefix = "Bearer" will yield Bearer XXX. If no prefix is provided just the token on its own will be set in the header field.


type alias Model =
{ clientId : AWS.CognitoIdentityProvider.ClientIdType
, region : AWS.Config.Region
, userIdentityMapping : Maybe UserIdentityMapping
, authHeaderName : String
, authHeaderPrefix : Maybe String
, innerModel : Private 
}

The authentication model consisting of the evaluated config and the private state.


type Msg

The internal authentication events.

api : AuthAPI Config Model Msg AuthExtensions Challenge CognitoAPI FailReason

An extended API for working with Cognito.

This provides the functions needed to response to Cognito challenges.

Note that this API, extends the base API defined in the the-sett/elm-auth package.

The addAuthHeaders function, adds an Authorization : Bearer XXXX header into any set of HTTP headers given to it. Alternatively the extended CognitoAPI can be used to obtain the raw access directly, if it needs to be used in a different way.


type alias AuthExtensions =
{ accessToken : String
, decodedAccessToken : AWS.Tokens.AccessToken
, idToken : String
, decodedIdToken : AWS.Tokens.IdToken
, saveState : Json.Encode.Value 
}

Defines the extensions to the AuthAPI.AuthInfo fields that this authenticator supports.

saveState provides a JSON serialized snapshot of the authenticated state. This can be used with the CognitoAPI.restore function to attempt to re-create the authenticated state without logging in again. Be aware that the save state will contain sensitive information such as access tokens - so think carefully about the security implications of where you put it. For example, local storage can be compromised by XSS attacks, are you really sure your site is invulnerable to this?


type Challenge
    = NewPasswordRequired

The types of challenges that Cognito can issue.

Challenge types not yet covered:


type alias CognitoAPI =
{ requiredNewPassword : String -> Platform.Cmd.Cmd Msg
, getAWSCredentials : Model -> Maybe AWS.Credentials.Credentials
, restore : Json.Encode.Value -> Platform.Cmd.Cmd Msg 
}

AWS Cognito specific API for:


type FailReason
    = ResourceNotFound
    | NotAuthorized
    | TooManyRequests
    | UnexpectedLambda
    | InvalidUserPoolConfiguration
    | UserLambdaValidation
    | InvalidLambdaResponse
    | PasswordResetRequired
    | UserNotFound
    | UserNotConfirmed
    | AWSServerError
    | UnexpectedError String

Gives a reason why the Failed state has been reached.


type alias UserIdentityMappingConfig =
{ userPoolId : String
, identityPoolId : String
, accountId : String 
}

Optional configuration needed to request temporary AWS credentials.


type alias UserIdentityMapping =
{ identityPoolId : AWS.CognitoIdentity.IdentityPoolId
, identityProviderName : AWS.CognitoIdentity.IdentityProviderName
, accountId : AWS.CognitoIdentity.AccountId 
}

Holds the UserIdentityMappingConfig parameters if they pass parsing into the valid format accepeted by Cognito.