Auth
The Auth construct is a higher level CDK construct that makes it easy to configure a Cognito User Pool and Cognito Identity Pool. Also, allows setting up Auth0, Facebook, Google, Twitter, Apple, and Amazon as authentication providers.
Initializer#
Parameters
Examples#
Allowing users to sign in using User Pool#
Allowing users to sign in with their email or phone number#
Configuring User Pool triggers#
The Cognito User Pool can take invoke a Lambda function for specific triggers.
Specifying function props for all the triggers#
Using the full config for a trigger#
If you wanted to configure each Lambda function separately, you can pass in the FunctionProps.
Note that, you can set the defaultFunctionProps while using the FunctionProps per trigger. The function will just override the defaultFunctionProps. Except for the environment, the layers, and the permissions properties, it will be merged.
So in the above example, the preAuthentication function doesn't use the timeout that is set in the defaultFunctionProps. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the tableName and the bucketName environment variables set; as well as permissions to both the table and the bucket.
Allowing Twitter auth and a User Pool#
Adding all the supported social logins#
Allowing users to login using Auth0#
Attaching permissions for authenticated users#
Attaching permissions for unauthenticated users#
Upgrading to v0.12.0#
The v0.12.0 release of the Auth construct includes a small breaking change. You might be impacted by this change if:
- You are currently using any version
< v0.12.0 - And using Cognito as the authentication provider
Using signInAliases#
If you are configuring the signInAliases like so:
Change it to:
Note the userPool prop is expected as a part of the cognito prop.
Using cognitoUserPool and cognitoUserPoolClient#
If you are creating the UserPool and the UserPoolClient manually like this:
Change it to:
Read more about the AuthCognitoProps below.
Properties#
An instance of Auth contains the following properties.
cognitoCfnIdentityPool#
Type : cdk.aws-cognito.CfnIdentityPool
The internally created CDK CfnIdentityPool instance.
cognitoUserPool?#
Type : cdk.aws-cognito.UserPool
The internally created CDK UserPool instance. Not available if only social logins are used.
cognitoUserPoolClient?#
Type : cdk.aws-cognito.UserPoolClient
The internally created CDK UserPoolClient instance. Not available if only social logins are used.
iamAuthRole#
Type : cdk.aws-iam.Role
The internally created CDK IAM Role instance for the authenticated users of the Identity Pool.
iamUnauthRole#
Type : cdk.aws-iam.Role
The internally created CDK IAM Role instance for the unauthenticated users of the Identity Pool.
Methods#
An instance of Auth contains the following methods.
attachPermissionsForAuthUsers#
Parameters
- permissions
Permissions
Attaches the given list of permissions to IAM role used for authenticated users. This dictates which resources an authenticated user has access to.
Follows the same format as Function.attachPermissions.
attachPermissionsForUnauthUsers#
Parameters
- permissions
Permissions
Attaches the given list of permissions to IAM role used for unauthenticated users. This dictates which resources an unauthenticated user has access to.
Follows the same format as Function.attachPermissions.
AuthProps#
cognito?#
Type : AuthCognitoProps
The props that'll be used to configure a Cognito User Pool.
apple?#
Type : AuthAppleProps
The props necessary to configure Apple as an authentication provider for the Identity Pool.
auth0?#
Type : AuthAuth0Props
The props necessary to configure Auth0 as an authentication provider for the Identity Pool.
google?#
Type : AuthGoogleProps
The props necessary to configure Google as an authentication provider for the Identity Pool.
facebook?#
Type : AuthFacebookProps
The props necessary to configure Facebook as an authentication provider for the Identity Pool.
twitter?#
Type : AuthTwitterProps
The props necessary to configure Twitter as an authentication provider for the Identity Pool.
amazon?#
Type : AuthAmazonProps
The props necessary to configure Amazon as an authentication provider for the Identity Pool.
identityPool?#
Type : AuthCdkCfnIdentityPoolProps
The props that'll be used to configure the Cognito Identity Pool.
AuthCognitoProps#
userPool?#
Type : cdk.aws-cognito.UserPoolProps | cdk.aws-cognito.UserPool
Optionally, pass in an instance of the CDK cdk.aws-cognito.UserPoolProps or cdk.aws-cognito.UserPool. This will override the default settings this construct uses to create the CDK UserPool internally.
caution
You cannot change some of the User Pool properties once the it has been created.
For example, SignInAliases cannot be changed after the User Pool has been created.
The different aliases a user can use to sign in to our application for our User Pool. For example, you might want a user to be able to sign in with their email or username. Or with their phone number.
There are two ways of setting this up.
User signs up with username and signs in with username or alias
A user signs up with a username. In addition to the username, you can optionally allow users to sign in with one or more of the following aliases:
Note that, the username that Cognito refers to, is an internally used user id. So in practice, you'll ask a user to create a new username, this is called the preferred username by Cognito.
- A verified email address
- A verified phone number
- A preferred username
These aliases can be changed after the user signs up.
To use this option, set the
userPoolprop to:User signs up and signs in with email or phone number instead of username
A user signs up with an email address or phone number as their username. You can choose whether to allow sign-up with only email addresses, only phone numbers, or either one.
Note that, the email or phone number that gets set as a username needs to be unique. This is because when Cognito refers to the username, it really refers to an internally used user id.
In addition, if a user signs up with an email address, they can only change it to another email address and not a phone number. The same applies if they sign up with a phone number. It cannot be changed to an email.
To use this option, set the
userPoolprop to:
userPoolClient?#
Type : cdk.aws-cognito.UserPoolClientOptions | cdk.aws-cognito.UserPoolClient
Optionally, pass in an instance of the CDK cdk.aws-cognito.UserPoolClientOptions or cdk.aws-cognito.UserPoolClient. This will override the default settings this construct uses to create the CDK UserPoolClient internally.
triggers?#
Type : AuthUserPoolTriggers, defaults to undefined
The triggers for the User Pool. Takes an associative array, where the key is the trigger type and the value is a FunctionDefinition.
defaultFunctionProps?#
Type : FunctionProps, defaults to {}
The default function props to be applied to all the Lambda functions for the triggers. These default values are overridden by the function props for each trigger. Except for the environment, the layers, and the permissions properties, it will be merged.
AuthAuth0Props#
domain#
Type : string
The Domain for your Auth0 app.
clientId#
Type : string
The Client ID for your Auth0 app.
AuthAppleProps#
servicesId#
Type : string
The Services id of your Apple app.
AuthGoogleProps#
clientId#
Type : string
The client id of your Google app.
AuthFacebookProps#
appId#
Type : string
The id of your Facebook app.
AuthTwitterProps#
consumerKey#
Type : string
The Consumer key for your Twitter app.
consumerSecret#
Type : string
The Consumer secret key for your Twitter app.
AuthAmazonProps#
appId#
Type : string
The id of your Amazon app.
AuthUserPoolTriggers#
The following User Pool triggers can be connected to Lambda functions in your app. Read more about this over on the AWS docs.
createAuthChallenge?#
Type: FunctionDefinition
Creates a challenge in a custom auth flow.
customMessage?#
Type: FunctionDefinition
Customize the message that is sent to a user.
defineAuthChallenge?#
Type: FunctionDefinition
Determine the next challenge in a custom auth flow.
postAuthentication?#
Type: FunctionDefinition
Triggered after a user is authenticated.
postConfirmation?#
Type: FunctionDefinition
Triggered after a user has been confirmed.
preAuthentication?#
Type: FunctionDefinition
Custom validation to accept or deny the sign-in request.
preSignUp?#
Type: FunctionDefinition
Custom validation to accept or deny the sign-up request.
preTokenGeneration?#
Type: FunctionDefinition
Add or remove attributes in Id tokens.
userMigration?#
Type: FunctionDefinition
Migrate a user from an existing user directory to User Pools.
verifyAuthChallengeResponse?#
Type: FunctionDefinition
Determines if a response is correct in a custom auth flow.
AuthCdkCfnIdentityPoolProps#
AuthCdkCfnIdentityPoolProps extends cdk.aws-cognito.CfnIdentityPoolProps with the exception that the allowUnauthenticatedIdentities fields is optional, and defaults to true.
You can use AuthCdkCfnIdentityPoolProps to configure the other Identity Pool properties.