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#

new Auth(scope: Construct, id: string, props: AuthProps)

Parameters

scope Construct
id string
props AuthProps

Examples#

Allowing users to sign in with their email using User Pool#

new Auth(this, "Auth", {
  cognito: {
    signInAliases: { email: true },
  },
});

Allowing users to sign in with their email or phone number#

new Auth(this, "Auth", {
  cognito: {
    signInAliases: { email: true, phone: true },
  },
});

Allowing Twitter auth and a User Pool#

new Auth(this, "Auth", {
  cognito: { signInAliases: { email: true } },
  twitter: {
    consumerKey: "gyMbPOiwefr6x63SjIW8NN2d9",
    consumerSecret: "qxld1zic5c2eyahqK3gjGLGQaOTogGfAgGh17MYOIcOUR9l2Nz",
  },
});

Adding all the supported social logins#

new Auth(this, "Auth", {
  facebook: { appId: "419718329085014" },
  apple: { servicesId: "com.myapp.client" },
  amazon: { appId: "amzn1.application.24ebe4ee4aef41e5acff038aee2ee65f" },
  google: {
    clientId:
      "38017095028-abcdjaaaidbgt3kfhuoh3n5ts08vodt3.apps.googleusercontent.com",
  },
});

Allowing users to login using Auth0#

new Auth(this, "Auth", {
  auth0: {
    domain: "https://myorg.us.auth0.com",
    clientId: "UsGRQJJz5sDfPQDs6bhQ9Oc3hNISuVif",
  },
});

Manually creating a User Pool and User Pool Client#

const userPool =
  new cdk.aws() -
  cognito.UserPool(this, "UserPool", {
    // Prefixing the user pool name so it doesn't thrash if deployed
    // to other environments in the same account
    userPoolName: this.node.root.logicalPrefixedName("myuserpool"),
  });
const userPoolClient =
  new cdk.aws() -
  cognito.UserPoolClient(this, "UserPoolClient", {
    userPool,
  });

new Auth(this, "Auth", {
  cognitoUserPool: userPool,
  cognitoUserPoolClient: userPoolClient,
});

Attaching permissions for authenticated users#

const auth = new Auth(this, "Auth", {
  cognito: { signInAliases: { email: true } },
});

auth.attachPermissionsForAuthUsers([
  new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    actions: ["s3:*"],
    resources: ["*"],
  }),
]);

Attaching permissions for unauthenticated users#

const auth = new Auth(this, "Auth", {
  cognito: { signInAliases: { email: true } },
});

auth.attachPermissionsForUnauthUsers([
  new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    actions: ["s3:*"],
    resources: ["*"],
  }),
]);

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#

attachPermissionsForAuthUsers(permissions: Permissions)

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#

attachPermissionsForUnauthUsers(permissions: Permissions)

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.

cognitoUserPool?#

Type : cdk.aws-cognito.UserPool

Optionally, pass in an instance of the CDK UserPool. This will override the internally created one.

cognitoUserPoolClient?#

Type : cdk.aws-cognito.UserPoolClient

Optionally, pass in an instance of the CDK UserPoolClient. This will override the internally created one.

AuthCognitoProps#

signInAliases#

Type : cdk.aws-cognito.SignInAliases, defaults to { username: true }

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.

caution

You cannot change this prop once the User Pool has been created.

Internally sets the CDK User Pool signInAliases prop.

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 signInAliases prop to:
{
username: true,
email: true,
phone: true,
preferredUsername: true,
}
Read more on this over on the AWS docs.
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 signInAliases prop to:
{
email: true,
phone: true,
}
Read more on this over on the AWS docs.

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.