Amazon Cognito

(1)

Amazon Cognito

Developer Guide

(2)

Amazon Cognito: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is Amazon Cognito?

Amazon Cognito provides authentication, authorization, and user management for your web and mobile apps. Your users can sign in directly with a user name and password, or through a third party such as Facebook, Amazon, Google or Apple.

The two main components of Amazon Cognito are user pools and identity pools. User pools are user directories that provide sign-up and sign-in options for your app users. Identity pools enable you to grant your users access to other AWS services. You can use identity pools and user pools separately or together.

An Amazon Cognito user pool and identity pool used together

See the diagram for a common Amazon Cognito scenario. Here the goal is to authenticate your user, and then grant your user access to another AWS service.

1. In the ﬁrst step your app user signs in through a user pool and receives user pool tokens after a successful authentication.

2. Next, your app exchanges the user pool tokens for AWS credentials through an identity pool.

3. Finally, your app user can then use those AWS credentials to access other AWS services such as Amazon S3 or DynamoDB.

For more examples using identity pools and user pools, see Common Amazon Cognito scenarios (p. 10).

Amazon Cognito is compliant with SOC 1-3, PCI DSS, ISO 27001, and is HIPAA-BAA eligible. For more information, see AWS services in scope. See also Regional data considerations (p. 360).

Topics

• Features of Amazon Cognito (p. 2)

• Getting started with Amazon Cognito (p. 2)

(9)

• Regional availability (p. 3)

• Pricing for Amazon Cognito (p. 3)

• Using the Amazon Cognito console (p. 3)

Features of Amazon Cognito

User pools

A user pool is a user directory in Amazon Cognito. With a user pool, your users can sign in to your web or mobile app through Amazon Cognito, or federate through a third-party identity provider (IdP). Whether your users sign in directly or through a third party, all members of the user pool have a directory proﬁle that you can access through an SDK.

User pools provide:

• Sign-up and sign-in services.

• A built-in, customizable web UI to sign in users.

• Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple, and through SAML and OIDC identity providers from your user pool.

• User directory management and user proﬁles.

• Security features such as multi-factor authentication (MFA), checks for compromised credentials, account takeover protection, and phone and email veriﬁcation.

• Customized workﬂows and user migration through AWS Lambda triggers.

For more information about user pools, see Getting started with user pools (p. 22) and the Amazon Cognito user pools API reference.

Identity pools

With an identity pool, your users can obtain temporary AWS credentials to access AWS services, such as Amazon S3 and DynamoDB. Identity pools support anonymous guest users, as well as the following identity providers that you can use to authenticate users for identity pools:

• Amazon Cognito user pools

• Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple

• OpenID Connect (OIDC) providers

• SAML identity providers

• Developer authenticated identities

To save user proﬁle information, your identity pool needs to be integrated with a user pool.

For more information about identity pools, see Getting started with Amazon Cognito identity pools (federated identities) (p. 223) and the Amazon Cognito identity pools API reference.

Getting started with Amazon Cognito

For a guide to top tasks and where to start, see Getting started with Amazon Cognito (p. 6).

For videos, articles, documentation, and sample apps, see Amazon Cognito developer resources.

To use Amazon Cognito, you need an AWS account. For more information, see Using the Amazon Cognito console (p. 3).

(10)

Regional availability

Amazon Cognito is available in multiple AWS Regions worldwide. In each Region, Amazon Cognito is distributed across multiple Availability Zones. These Availability Zones are physically isolated from each other, but are united by private, low-latency, high-throughput, and highly redundant network connections. These Availability Zones enable AWS to provide services, including Amazon Cognito, with very high levels of availability and redundancy, while also minimizing latency.

For a list of all the Regions where Amazon Cognito is currently available, see AWS regions and endpoints in the Amazon Web Services General Reference. To learn more about the number of Availability Zones that are available in each Region, see AWS global infrastructure.

Pricing for Amazon Cognito

For information about Amazon Cognito pricing, see Amazon Cognito pricing.

Using the Amazon Cognito console

You can use the Amazon Cognito console to create and manage user pools and identity pools.

This guide provides step-by-step walkthroughs for common Amazon Cognito user pool tasks in both the original Amazon Cognito console (referred to as the original console), and the November 2021 console update (the new console). The new console update revises workﬂows for most actions in the Amazon Cognito user pools console. It does not change the Amazon Cognito API that underpins AWS SDKs and the AWS Command Line Interface.

New console experience highlights

• Logical grouping of features

• A user pool creation wizard

• Informative instructions that emphasize the user experience in your app

• Dynamic assistance with user pool conﬁguration

• Pop-out help text

• Filtered views

• App category settings and suggested presets

• Warnings about irreversible conﬁguration choices

• Updated information on resource limits and the limitations of user pool conﬁguration

To get started with the new Amazon Cognito user pools console, select the link in the invitation banner displayed in your console. You can revert to the original console after previewing the new console experience.

Features retained in the original console

The following Amazon Cognito console workﬂows are not currently implemented in the new console.

You will be redirected to the original console when you access these features in the new Amazon Cognito console.

• Amazon Cognito identity pools (federated identities)

• Amazon Cognito Sync

• Importing Users into User Pools From a CSV File

(11)

• User Pool Analytics

To use the Amazon Cognito console

In the remainder of this guide, you will ﬁnd Original console and New console tabs where console- speciﬁc instructions are provided. Select the tab that corresponds to the console experience you have chosen.

Original console

1. To use Amazon Cognito, you need to sign up for an AWS account.

2. Go to the Amazon Cognito console. You might be prompted for your AWS credentials.

3. To create or edit a user pool, choose Manage your User Pools.

For more information, see Getting started with user pools (p. 22).

4. To create or edit an identity pool, choose Manage Federated Identities.

For more information, see Getting started with Amazon Cognito identity pools (federated identities) (p. 223).

The Amazon Cognito console is a part of the AWS Management Console, which provides information about your account and billing. For more information, see Working with the AWS Management Console.

New console

1. To use Amazon Cognito, you need to sign up for an AWS account.

(12)

Using the Amazon Cognito console

2. Go to the Amazon Cognito console. You might be prompted for your AWS credentials.

3. To create or edit a user pool, choose User Pools from the left navigation pane.

For more information, see Getting started with user pools (p. 22).

4. To create or edit an identity pool, choose Federated identities. You will be directed to the original console for Amazon Cognito identity pools.

For more information, see Getting started with Amazon Cognito identity pools (federated identities) (p. 223).

The Amazon Cognito console is a part of the AWS Management Console, which provides information about your account and billing. For more information, see Working with the AWS Management Console.

(13)

Getting started with Amazon Cognito

This section describes the top Amazon Cognito tasks and where to start. For an overview of Amazon Cognito, see What is Amazon Cognito? (p. 1).

The two main components of Amazon Cognito are user pools and identity pools. User pools are user directories that provide sign-up and sign-in options for your web and mobile app users. Identity pools provide AWS credentials to grant your users access to other AWS services. You can use user pools and identity pools separately or together.

Top tasks and where to start

Add sign-up and sign-in with a user pool 1. Create a user directory with a user pool.

2. Add an app to enable the hosted UI.

3. Add social sign-in to a user pool.

4. Add sign-in through SAML-based identity providers (IdPs) to a user pool.

5. Add sign-in through OpenID Connect (OIDC) IdPs to a user pool.

6. Install a user pool SDK.

7. Customize the built-in hosted web UI sign-in and sign-up pages.

8. Conﬁgure user pool security features.

9. Customize user pool workﬂows with Lambda triggers.

10. Gather data and target campaigns with Amazon Pinpoint analytics.

Manage users in a user pool

• Sign up and conﬁrm user accounts.

• Create user accounts as administrator.

• Manage and search user accounts.

• Add groups to a user pool.

• Import users into a user pool.

Access resources

Common Amazon Cognito scenarios:

• Authenticate with a user pool.

• Access backend resources through a user pool.

• Access API Gateway and Lambda through a user pool.

• Access AWS services with a user pool and an identity pool.

• Access AWS services through a third party and an identity pool.

• Access AWS AppSync resources through a user pool or an identity pool.

Get an AWS account and your root user credentials

To access AWS, you must sign up for an AWS account.

(14)

Creating an IAM user

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

AWS sends you a conﬁrmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to https://aws.amazon.com/ and choosing My Account.

Creating an IAM user

If your account already includes an IAM user with full AWS administrative permissions, you can skip this section.

When you ﬁrst create an Amazon Web Services (AWS) account, you begin with a single sign-in identity.

That identity has complete access to all AWS services and resources in the account. This identity is called the AWS account root user. When you sign in, enter the email address and password that you used to create the account.

Important

We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your ﬁrst IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks. To view the tasks that require you to sign in as the root user, see Tasks that require root user credentials.

To create an administrator user for yourself and add the user to an administrators group (console)

1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

Note

We strongly recommend that you adhere to the best practice of using the Administrator IAM user that follows and securely lock away the root user credentials. Sign in as the root user only to perform a few account and service management tasks.

2. In the navigation pane, choose Users and then choose Add user.

3. For User name, enter Administrator.

4. Select the check box next to AWS Management Console access. Then select Custom password, and then enter your new password in the text box.

5. (Optional) By default, AWS requires the new user to create a new password when ﬁrst signing in. You can clear the check box next to User must create a new password at next sign-in to allow the new user to reset their password after they sign in.

6. Choose Next: Permissions.

7. Under Set permissions, choose Add user to group.

8. Choose Create group.

9. In the Create group dialog box, for Group name enter Administrators.

10. Choose Filter policies, and then select AWS managed - job function to ﬁlter the table contents.

11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.

(15)

Note

You must activate IAM user and role access to Billing before you can use the

AdministratorAccess permissions to access the AWS Billing and Cost Management console. To do this, follow the instructions in step 1 of the tutorial about delegating access to the billing console.

12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to see the group in the list.

13. Choose Next: Tags.

14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM entities in the IAM User Guide.

15. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.

You can use this same process to create more groups and users and to give your users access to your AWS account resources. To learn about using policies that restrict user permissions to speciﬁc AWS resources, see Access management and Example policies.

Signing in as an IAM user

Sign in to the IAM console by choosing IAM user and entering your AWS account ID or account alias. On the next page, enter your IAM user name and your password.

Note

For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM user name and account information. If you previously signed in as a diﬀerent user, choose the sign-in link beneath the button to return to the main sign-in page. From there, you can enter your AWS account ID or account alias to be redirected to the IAM user sign-in page for your account.

Creating IAM user access keys

Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don't have access keys, you can create them from the AWS Management Console. As a best practice, do not use the AWS account root user access keys for any task where it's not required. Instead, create a new administrator IAM user with access keys for yourself.

The only time that you can view or download the secret access key is when you create the keys. You cannot recover them later. However, you can create new access keys at any time. You must also have permissions to perform the required IAM actions. For more information, see Permissions required to access IAM resources in the IAM User Guide.

To create access keys for an IAM user

1. Sign in to the AWS Management Console and open the IAM console at https://

console.aws.amazon.com/iam/.

2. In the navigation pane, choose Users.

3. Choose the name of the user whose access keys you want to create, and then choose the Security credentials tab.

4. In the Access keys section, choose Create access key.

5. To view the new access key pair, choose Show. You will not have access to the secret access key again after this dialog box closes. Your credentials will look something like this:

(16)

Creating IAM user access keys

• Access key ID: AKIAIOSFODNN7EXAMPLE

• Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRﬁCYEXAMPLEKEY

6. To download the key pair, choose Download .csv ﬁle. Store the keys in a secure location. You will not have access to the secret access key again after this dialog box closes.

Keep the keys conﬁdential in order to protect your AWS account and never email them. Do not share them outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your secret key.

7. After you download the .csv ﬁle, choose Close. When you create an access key, the key pair is active by default, and you can use the pair right away.

Related topics

• What is IAM? in the IAM User Guide

• AWS security credentials in AWS General Reference

(17)

Common Amazon Cognito scenarios

This topic describes six common scenarios for using Amazon Cognito.

The two main components of Amazon Cognito are user pools and identity pools. User pools are user directories that provide sign-up and sign-in options for your web and mobile app users. Identity pools provide AWS credentials to grant your users access to other AWS services.

A user pool is a user directory in Amazon Cognito. Your app users can sign in either directly through a user pool, or federate through a third-party identity provider (IdP). The user pool manages the overhead of handling the tokens that are returned from social sign-in through Facebook, Google, Amazon, and Apple, and from OpenID Connect (OIDC) and SAML IdPs. Whether your users sign in directly or through a third party, all members of the user pool have a directory proﬁle that you can access through an SDK.

With an identity pool, your users can obtain temporary AWS credentials to access AWS services, such as Amazon S3 and DynamoDB. Identity pools support anonymous guest users, as well as federation through third-party IdPs.

Topics

• Authenticate with a user pool (p. 10)

• Access your server-side resources with a user pool (p. 10)

• Access resources with API Gateway and Lambda with a user pool (p. 11)

• Access AWS services with a user pool and an identity pool (p. 12)

• Authenticate with a third party and access AWS services with an identity pool (p. 12)

• Access AWS AppSync resources with Amazon Cognito (p. 13)

Authenticate with a user pool

You can enable your users to authenticate with a user pool. Your app users can sign in either directly through a user pool, or federate through a third-party identity provider (IdP). The user pool manages the overhead of handling the tokens that are returned from social sign-in through Facebook, Google, Amazon, and Apple, and from OpenID Connect (OIDC) and SAML IdPs.

After a successful authentication, your web or mobile app will receive user pool tokens from Amazon Cognito. You can use those tokens to retrieve AWS credentials that allow your app to access other AWS services, or you might choose to use them to control access to your server-side resources, or to the Amazon API Gateway.

For more information, see User pool authentication ﬂow (p. 344) and Using tokens with user pools (p. 174).

Access your server-side resources with a user pool

After a successful user pool sign-in, your web or mobile app will receive user pool tokens from Amazon Cognito. You can use those tokens to control access to your server-side resources. You can also create

(18)

Access resources with API Gateway and Lambda

user pool groups to manage permissions, and to represent diﬀerent types of users. For more information on using groups to control access your resources see Adding groups to a user pool (p. 148).

Once you conﬁgure a domain for your user pool, Amazon Cognito provisions a hosted web UI that allows you to add sign-up and sign-in pages to your app. Using this OAuth 2.0 foundation you can create your own resource server to enable your users to access protected resources. For more information see Deﬁning resource servers for your user pool (p. 54).

For more information about user pool authentication see User pool authentication ﬂow (p. 344) and Using tokens with user pools (p. 174).

Access resources with API Gateway and Lambda with a user pool

You can enable your users to access your API through API Gateway. API Gateway validates the tokens from a successful user pool authentication, and uses them to grant your users access to resources including Lambda functions, or your own API.

You can use groups in a user pool to control permissions with API Gateway by mapping group

membership to IAM roles. The groups that a user is a member of are included in the ID token provided by a user pool when your app user signs in. For more information on user pool groups See Adding groups to a user pool (p. 148).

You can submit your user pool tokens with a request to API Gateway for veriﬁcation by an Amazon Cognito authorizer Lambda function. For more information on API Gateway, see Using API Gateway with Amazon Cognito user pools.

(19)

Access AWS services with a user pool and an identity pool

After a successful user pool authentication, your app will receive user pool tokens from Amazon Cognito.

You can exchange them for temporary access to other AWS services with an identity pool. For more information, see Accessing AWS services using an identity pool after sign-in (p. 186) and Getting started with Amazon Cognito identity pools (federated identities) (p. 223).

Authenticate with a third party and access AWS services with an identity pool

You can enable your users access to AWS services through an identity pool. An identity pool requires an IdP token from a user that's authenticated by a third-party identity provider (or nothing if it's an anonymous guest). In exchange, the identity pool grants temporary AWS credentials that you can use to access other AWS services. For more information, see Getting started with Amazon Cognito identity pools (federated identities) (p. 223).

(20)

Access AWS AppSync resources with Amazon Cognito

You can grant your users access to AWS AppSync resources with tokens from a successful Amazon Cognito authentication (from a user pool or an identity pool). For more information, see Access AWS AppSync and data sources with user pools or federated identities.

(21)

Amazon Cognito tutorials

The two main components of Amazon Cognito are user pools and identity pools. User pools are user directories that provide sign-up and sign-in options for your web and mobile app users. Identity pools provide AWS credentials to grant your users access to other AWS services.

Topics

• Tutorial: Creating a user pool (p. 14)

• Tutorial: Creating an identity pool (p. 15)

• Tutorial: Cleaning up your AWS resources (p. 15)

Tutorial: Creating a user pool

With a user pool, your users can sign in to your web or mobile app through Amazon Cognito.

Original console

To create a user pool

1. Go to the Amazon Cognito console. If prompted, enter your AWS credentials.

2. Choose Manage User Pools.

3. Choose Create a user pool.

4. Enter a name for your user pool and choose Review defaults to save the name.

5. On the Review page, choose Create pool.

New console

To create a user pool

2. Choose User Pools.

3. In the top-right corner of the page, choose Create a user pool to start the user pool creation wizard.

4. In Conﬁgure sign-in experience, choose the federated providers that you will use with this user pool. For more information, see Adding User Pool Sign-in Through a Third Party.

5. In Conﬁgure security requirements, choose your password policy, multi-factor authentication (MFA) requirements, and user account recovery options. For more information, see Security in Amazon Cognito.

6. In Conﬁgure sign-up experience,determine how new users will verify their identities when signing up, and which attributes should be required or optional during the user sign-up ﬂow. For more information, see Managing users in user pools.

7. In Configure message delivery, configure integration with Amazon Simple Email Service and Amazon Simple Notification Service to send email and SMS messages to your users for sign-up, account confirmation, MFA, and account recovery. For more information, see Email Settings for Amazon Cognito User Pools and SMS message settings for Amazon Cognito user pools.

8. In Integrate your app, name your user pool, conﬁgure the hosted UI, and create an app client.

For more information, see Add an App to Enable the Hosted Web UI

(22)

Related Resources

9. Review your choices in the Review and create screen and modify any selections you wish to.

When you are satisﬁed with your user pool conﬁguration, select Create user pool to proceed.

Related Resources

For more information on user pools, see Amazon Cognito user pools (p. 21).

See also User pool authentication ﬂow (p. 344) and Using tokens with user pools (p. 174).

Tutorial: Creating an identity pool

With an identity pool, your users can obtain temporary AWS credentials to access AWS services, such as Amazon S3 and DynamoDB.

To create an identity pool

2. Choose Manage Identity Pools 3. Choose Create new identity pool.

4. Enter a name for your identity pool.

5. To enable unauthenticated identities, select Enable access to unauthenticated identities from the Unauthenticated identities collapsible section.

6. Choose Create Pool.

7. You will be prompted for access to your AWS resources.

Choose Allow to create the two default roles associated with your identity pool: one for

unauthenticated users and one for authenticated users. These default roles provide your identity pool access to Amazon Cognito Sync. You can modify the roles associated with your identity pool in the IAM console.

8. Make a note of your identity pool Id number. You will use it to set up policies that will allow your app users to access other AWS services, such as Amazon Simple Storage Service or DynamoDB

Related resources

For more information on identity pools, see Amazon Cognito identity pools (federated identities) (p. 223).

For an example of using an identity pool with Amazon S3, see Uploading Photos to Amazon S3 from a Browser.

Tutorial: Cleaning up your AWS resources

To delete an identity pool

2. Choose Manage Identity Pools.

3. Choose the name of the identity pool that you want to delete. The Dashboard page for your identity pool appears.

(23)

4. In the top-right corner of the Dashboard page, choose Edit identity pool. The Edit identity pool page appears.

5. Scroll down and choose Delete identity pool to expand it.

6. Choose Delete identity pool.

7. Choose Delete pool.

Original console

To delete a user pool

3. Choose the user pool you created in the previous step.

4. On the Domain name page under App integration, select Delete domain.

5. Choose Delete domain when prompted to conﬁrm.

6. Go to the General Settings page.

7. Select Delete pool in the upper right corner of the page.

8. Enter delete and choose Delete pool when prompted to conﬁrm.

New console

To delete a user pool

2. From the navigation pane, choose User Pools.

3. If you have not created a domain for your user pool, select the radio button next to a user pool and select Delete. Enter the name of the user pool to conﬁrm, and stop here.

4. If you have created a domain for your user pool, select the user pool.

5. Navigate to the App integration tab for your user pool.

6. Next to Domain, choose Actions and select Delete Cognito domain or Delete custom domain.

7. Enter the domain name to conﬁrm deletion.

8. Return to the User pools list and select the radio button next to your user pool. Select Delete and enter the name of the user pool to conﬁrm.

(24)

Amazon Cognito authentication with the AWS Amplify framework

Integrating Amazon Cognito with web and mobile apps

When new users discover your app, or when existing users return to it, their ﬁrst tasks are to sign up or sign in. By integrating Amazon Cognito with your client code, you connect your app to backend AWS functionality that aids authentication and authorization workﬂows. Your app will use the Amazon Cognito API to, for example, create new users in your user pool, retrieve user pool tokens, and obtain temporary credentials from your identity pool. To integrate Amazon Cognito with your web or mobile app, use the SDKs and libraries that the AWS Amplify framework provides.

Amazon Cognito authentication with the AWS Amplify framework

AWS Amplify provides services and libraries for web and mobile developers. With AWS Amplify, you can build apps that integrate with backend environments that are composed of AWS services. To provision your backend environment, and to integrate AWS services with your client code, you use the AWS Amplify framework. The framework provides an interactive command line interface (CLI) that helps you conﬁgure AWS resources for features that are organized into categories, including analytics, storage, and authentication, among many others. The framework also provides high-level SDKs and libraries for web and mobile platforms, including iOS, Android, and JavaScript. Supported JavaScript frameworks include React, React Native, Angular, Ionic, and Vue. Each of the SDKs and libraries include authentication operations that you can use to implement the authentication workﬂows that Amazon Cognito drives.

To use the AWS Amplify framework to add authentication to your app, see the AWS Amplify authorization documentation for your platform:

• AWS Amplify authentication for JavaScript

• AWS Amplify authentication for iOS

• AWS Amplify authentication for Android

(25)

Multi-tenant application best practices

Amazon Cognito user pools can be used to secure small multi-tenant applications where the number of tenants and expected volume align with the related Amazon Cognito service quota. A common use case of multi-tenant design is running workloads to support testing multiple versions of an application. Multi- tenant design is also useful for testing a single application with diﬀerent datasets, which allows full use of your cluster resources.

Note

Amazon Cognito Quotas are applied per AWS account and Region. These quotas are shared across all tenants in your application. Review the Amazon Cognito service quotas and make sure that the quota meets the expected volume and the expected number of tenants in your application.

You have four ways to secure multi-tenant applications: user pools, application clients, groups, or custom attributes.

Topics

• User pool-based multi-tenancy (p. 18)

• Application client-based multi-tenancy (p. 19)

• Group-based multi-tenancy (p. 19)

• Custom attribute-based multi-tenancy (p. 19)

• Multi-tenancy security recommendations (p. 19)

User pool-based multi-tenancy

With this design, you can create a user pool for each tenant in your application. This approach provides maximum isolation for each tenant and allows you to implement different configurations for each tenant. Tenant isolation by user pool allows you flexibility in user-to-tenant mapping. It also allows multiple profiles for the same user. However, each user has to sign up individually for each tenant they have access to. Using this approach allows you to set up hosted UI for each tenant independently and redirect users to their tenant-specific instance of your application. This approach also allows easier integration with backend services like API Gateway. We recommend this approach in the following scenarios.

• Your application has different configurations for each tenant. For example, data residency requirements, password policy, and MFA configurations can be different for each tenant.

• Your application has complex user-to-tenant role mapping. For example, a single user could be a

“Student” in tenant A and the same user could also be a “Teacher” in tenant B.

• Your application uses the default Amazon Cognito hosted UI as the primary authentication method for native users. (Native users are those that have been created in the user pool with user name and password).

• Your application has a silo multi-tenant application where each tenant gets a full instance of your application infrastructure for their usage.

Eﬀort level

(26)

Application client-based multi-tenancy

The development and operation eﬀort to use this approach is high. You need to build tenant onboarding and administration components into your application that uses Amazon Cognito API operations and automation tools. These components are necessary to create the required resources for each tenant.

You also need to implement a tenant-matching user interface. In addition, you must add logic to your application that allows users to sign up and sign in to their corresponding tenant’s user pool.

Application client-based multi-tenancy

With application client-based multi-tenancy, you can map the same user to multiple tenants without the need to recreate a user’s proﬁle. You can create an application client for each tenant and enable the tenant external IdP as the only allowed identity provider for this application client. For more information see, Conﬁguring a user pool app client.

Application client-based multi-tenancy requires additional considerations for user name, password, and more when you use hosted UI to authenticate users with native accounts. When the hosted UI is in use, a session cookie is created to maintain the session for the authenticated user. The session cookie also provides SSO between application clients in the same user pool. This approach can be used in the following scenarios:

• Your application has the same conﬁgurations across all tenants. For example, data residency and password policy are the same across all tenants.

• Your application has a one-to-many mapping between user and tenants. For example, a single user could have access to multiple tenants using the same proﬁle.

• You have a federation-only multi-tenant application where tenants will always use an external IdP to sign in to your application.

• You have a B2B multi-tenant application and tenants backend services will use client-credentials grant to access your services. In this case, you can create application client for each tenant and share the client-id and secret with tenant backend service for machine-to-machine authentication.

Eﬀort level

The development eﬀort to use this approach is high. You need to implement tenant-matching logic and a user interface to match a user to the application client for their tenant.

Group-based multi-tenancy

With group-based multi-tenancy, you can associate an Amazon Cognito user pool group with a tenant.

That way you can use additional functionality through role-based access control (RBAC). For more information see, Role-based access control.

Custom attribute-based multi-tenancy

With custom attribute-based multi-tenancy, you can store tenant identification data like tenant_id as a custom attribute in a user’s profile. You then handle all multi-tenancy logic in your application and backend services. This approach allows you to use a unified sign-up and sign-in experience for all users.

You can also identify the user’s tenant in your application by checking this custom attribute.

Multi-tenancy security recommendations

The following recommendations can help make your application more secure.

(27)

• Avoid using an unveriﬁed email address to authorize user access to a tenant based on domain match.

Email addresses and phone numbers shouldn’t be trusted unless they are veriﬁed by your application or a proof of veriﬁcation is given by the external IdP. For more details on setting these permissions, see Attribute Permissions and Scopes.

• Make sure that user proﬁle attributes used to identify tenants are immutable or mutable attributes that can be changed by administrators. Application clients should have read-only access to these attributes.

• Ensure you have 1:1 mapping between external IdP and application client to prevent unauthorized cross-tenant access. A user that has been authenticated by an external IdP, and that has a valid Amazon Cognito session cookie, can access other tenant apps that trust the same IdP.

• When implementing tenant-matching and authorization logic in your application, ensure that the criteria used to authorize user access to the tenants can't be modiﬁed by users themselves. You should also ensure that user access can't be modiﬁed by the tenant identity provider administrators (if an external IdP is being used for federation).

(28)

Amazon Cognito user pools

A user pool is a user directory in Amazon Cognito. With a user pool, your users can sign in to your web or mobile app through Amazon Cognito. Your users can also sign in through social identity providers like Google, Facebook, Amazon, or Apple, and through SAML identity providers. Whether your users sign in directly or through a third party, all members of the user pool have a directory proﬁle that you can access through a Software Development Kit (SDK).

User pools provide:

• Sign-up and sign-in services.

• A built-in, customizable web UI to sign in users.

• Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple, as well as sign-in with SAML identity providers from your user pool.

• User directory management and user proﬁles.

• Security features such as multi-factor authentication (MFA), checks for compromised credentials, account takeover protection, and phone and email veriﬁcation.

• Customized workﬂows and user migration through AWS Lambda triggers.

After successfully authenticating a user, Amazon Cognito issues JSON web tokens (JWT) that you can use to secure and authorize access to your own APIs, or exchange for AWS credentials.

Amazon Cognito provides token handling through the Amazon Cognito user pools Identity SDKs for JavaScript, Android, and iOS. See Getting started with user pools (p. 22) and Using tokens with user pools (p. 174).

The two main components of Amazon Cognito are user pools and identity pools. Identity pools provide AWS credentials to grant your users access to other AWS services. To enable users in your user pool to access AWS resources, you can conﬁgure an identity pool to exchange user pool tokens for AWS credentials. For more information see Accessing AWS services using an identity pool after sign- in (p. 186) and Getting started with Amazon Cognito identity pools (federated identities) (p. 223).

Topics

• Getting started with user pools (p. 22)

• Using the Amazon Cognito hosted UI for sign-up and sign-in (p. 35)

• Adding user pool sign-in through a third party (p. 57)

• Customizing user pool workﬂows with Lambda triggers (p. 83)

• Using Amazon Pinpoint analytics with Amazon Cognito user pools (p. 132)

• Managing users in your user pool (p. 134)

• Email settings for Amazon Cognito user pools (p. 166)

• SMS message settings for Amazon Cognito user pools (p. 171)

• Using tokens with user pools (p. 174)

(29)

• Accessing resources after a successful user pool authentication (p. 184)

• User pools reference (AWS Management Console) (p. 188)

• Managing error responses (p. 221)

Getting started with user pools

These steps describe setting up and conﬁguring a user pool with the Amazon Cognito console. For more information about getting started with Amazon Cognito, see Getting started with Amazon Cognito (p. 6).

Topics

• Prerequisite: Sign up for an AWS account (p. 22)

• Step 1. Create a user pool (p. 22)

• Step 2. Add an app to enable the hosted web UI (p. 23)

• Step 3. Add social sign-in to a user pool (optional) (p. 26)

• Step 4. Add sign-in with a SAML identity provider to a user pool (optional) (p. 32)

• Next steps (p. 35)

Prerequisite: Sign up for an AWS account

To use Amazon Cognito, you need an AWS account. If you don't already have one, use the following procedure to sign up:

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Next step

Step 1. Create a user pool (p. 22)

Step 1. Create a user pool

Using an Amazon Cognito user pool, you can create and maintain a user directory, and add sign-up and sign-in to your mobile app or web application.

Original console

To create a user pool

3. In the top-right corner of the page, choose Create a user pool.

4. Enter a name for your user pool, and choose Review defaults to save the name.

5. In the top-left corner of the page, choose Attributes, choose Email address or phone number and Allow email addresses, and then choose Next step to save.

(30)

Step 2. Add an app to enable the hosted web UI

Note

We recommend that you enable case insensitivity on the username attribute before you create your user pool. For example, when this option is selected, users will be able to sign in using either "username" or "Username". Enabling this option also enables both preferred_username and email alias to be case insensitive, in addition to the username attribute. For more information, see CreateUserPool in the Amazon Cognito user pools API Reference.

6. In the left navigation menu, choose Review.

7. Review the user pool information and make any necessary changes. When the information is correct, choose Create pool.

New console

To create a user pool

3. In the top-right corner of the page, choose Create a user pool to start the user pool creation wizard.

4. In Conﬁgure sign-in experience, choose the federated providers that you want to use with this user pool. For more information, see Adding User Pool Sign-in Through a Third Party.

Note

The Make user name case sensitive option is turned oﬀ by default. We recommend that you do not activate this option. When the user name is not case sensitive, users can sign in with either username or Username. The Make user name case sensitive option also governs case sensitivity of the preferred_username and email aliases.

When user name is case sensitive, you must take additional security precautions. For more information, see User pool case sensitivity (p. 375).

5. In Conﬁgure security requirements, choose your password policy, multi-factor authentication (MFA) requirements, and user account recovery options. For more information, see Security in Amazon Cognito.

6. In Conﬁgure sign-up experience, determine how new users will verify their identities when signing up, and which attributes should be required or optional during the user sign-up ﬂow. For more information, see Managing users in user pools.

7. In Configure message delivery, configure integration with Amazon Simple Email Service (Amazon SES) and Amazon Simple Notification Service (Amazon SNS) to send email and SMS messages to your users for sign-up, account confirmation, MFA, and account recovery. For more information, see Email Settings for Amazon Cognito User Pools and SMS message settings for Amazon Cognito user pools.

8. In Integrate your app, name your user pool, conﬁgure the hosted UI, and create an app client.

For more information, see Add an App to Enable the Hosted Web UI

9. Review your choices in the Review and create screen and modify any selections you wish to.

When you are satisﬁed with your user pool conﬁguration, select Create user pool to proceed.

Next Step

Step 2. Add an app to enable the hosted web UI (p. 23)

Step 2. Add an app to enable the hosted web UI

After you create a user pool, you can create an app to use the built-in webpages for signing up and signing in your users.

(31)

Original console

To create an app in your user pool

3. Choose an existing user pool from the list, or create a user pool.

4. On the navigation bar on the left-side of the page, choose App clients under General settings.

5. Choose Add an app client.

6. Enter a name for your app client.

7. For this exercise, clear the option Generate client secret. Using a client secret with client-side authentication, such as the JavaScript used in this exercise, is not secure and not recommended for a production app client. Client secrets should only be used by applications that have a server-side authentication component so that it can secure the client secret.

8. Choose Create app client.

9. Note the App client ID.

10. Choose Return to pool details.

11. Choose App client settings from the navigation bar on the left-side of the console page.

12. Select Cognito User Pool as one of the Enabled Identity Providers.

Note

To sign in with external identity providers (IdPs) such as Facebook, Amazon, Google, and Apple, as well as through OpenID Connect (OIDC) or SAML IdPs, ﬁrst conﬁgure them as described next, and then return to the App client settings page to enable them.

13. Enter a callback URL for the Amazon Cognito authorization server to call after users are authenticated. For a web app, the URL should start with https://, such as https://

www.example.com.

For an iOS or Android app, you can use a callback URL such as myapp://.

14. Enter a Sign out URL.

15. Select Authorization code grant to return an authorization code that is then exchanged for user pool tokens. Because the tokens are never exposed directly to an end user, they are less likely to become compromised. However, a custom application is required on the backend to exchange the authorization code for user pool tokens. For security reasons, we recommend that you use the authorization code grant ﬂow, together with Proof Key for Code Exchange (PKCE), for mobile apps.

16. Under Allowed OAuth Flows, select Implicit grant to have user pool JSON web tokens (JWT) returned to you from Amazon Cognito. You can use this ﬂow when there's no backend available to exchange an authorization code for tokens. It's also helpful for debugging tokens.

Note

You can enable both the Authorization code grant and the Implicit code grant, and then use each grant as needed.

17. Unless you speciﬁcally want to exclude one, select the check boxes for all of the Allowed OAuth scopes.

Note

Select Client credentials only if your app needs to request access tokens on its own behalf, not on behalf of a user.

18. Choose Save changes.

19. On the Domain name page, type a domain preﬁx that's available.

20. Make a note of the complete domain address.

21. Choose Save changes.

(32)

Step 2. Add an app to enable the hosted web UI

New console

To create an app in your user pool

3. Choose an existing user pool from the list, or create a user pool. If you create a new user pool, you will be prompted to set up an app client and conﬁgure the hosted UI during the wizard.

4. Choose the App integration tab for your user pool.

5. Next to Domain, choose Actions, and then select either Create custom domain or Create Cognito domain. If you have already conﬁgured a user pool domain, choose Delete Cognito domain or Delete custom domain before creating your new custom domain.

6. Enter an available domain preﬁx to use with a Cognito domain. For information on setting up a Custom domain, see Using Your Own Domain for the Hosted UI

7. Choose Create.

8. Navigate back to the App integration tab for the same user pool and locate App clients. Choose Create an app client.

9. Choose an Application type. Some recommended settings will be provided based on your selection. An app that uses the hosted UI is a Public client.

10. Enter an App client name.

11. For this exercise, choose Don't generate client secret. The client secret is used by conﬁdential apps that authenticate users from a centralized application. In this exercise, you will present a hosted UI sign-in page to your users and will not require a client secret.

12. Choose the Authentication ﬂows you will allow with your app. Ensure that USER_SRP_AUTH has been selected.

13. Customize token expiration, Advanced security conﬁguration, and Attribute read and write permissions as needed. For more information, see Conﬁguring App Client Settings.

14. Add a callback URL for your app client. This is where you will be directed after hosted UI authentication. You do not need to add an Allowed sign-out URL until you are able to implement sign-out in your app.

For an iOS or Android app, you can use a callback URL such as myapp://.

15. Select the Identity providers for the app client. At minimum, enable Cognito user pool as a provider.

Note

To sign in with external identity providers (IdPs) such as Facebook, Amazon, Google, and Apple, as well as through OpenID Connect (OIDC) or SAML IdPs, ﬁrst conﬁgure them as shown in Add Social Sign-in to a User Pool, and then return to the App client settings page to enable them.

16. Choose OAuth 2.0 Grant Types. Select Authorization code grant to return an authorization code that is then exchanged for user pool tokens. Because the tokens are never exposed directly to an end user, they are less likely to become compromised. However, a custom application is required on the backend to exchange the authorization code for user pool tokens. For security reasons, we recommend that you use the authorization code grant ﬂow, together with Proof Key for Code Exchange (PKCE), for mobile apps.

Select Implicit grant to have user pool JSON web tokens (JWT) returned to you from Amazon Cognito. You can use this ﬂow when there's no backend available to exchange an authorization code for tokens. It's also helpful for debugging tokens.

Note

You can enable both the Authorization code grant and the Implicit code grant, and then use each grant as needed.

(33)

Select Client credentials only if your app needs to request access tokens on its own behalf, not on behalf of a user.

17. Unless you speciﬁcally want to exclude one, select all OpenID Connect scopes.

18. Select any Custom scopes you have conﬁgured. Custom scopes are typically used with conﬁdential clients.

19. Choose Create.

To view your sign-in page

From your App client page, select View hosted UI to open a new browser tab to a sign-in page pre- populated with app client id, scope, grant, and callback URL parameters.

You can view the hosted UI sign-in webpage manually with the following URL. Note the response_type. In this case, response_type=code for the authorization code grant.

https://your_domain/login?

response_type=code&client_id=your_app_client_id&redirect_uri=your_callback_url

You can view the hosted UI sign-in webpage with the following URL for the implicit code grant where response_type=token. After a successful sign-in, Amazon Cognito returns user pool tokens to your web browser's address bar.

https://your_domain/login?

response_type=token&client_id=your_app_client_id&redirect_uri=your_callback_url

You can ﬁnd the JSON web token (JWT) identity token after the #idtoken= parameter in the response.

The following URL is a sample response from an implicit grant request. Your identity token string will be much longer.

https://www.example.com/

#id_token=123456789tokens123456789&expires_in=3600&token_type=Bearer

Amazon Cognito user pools tokens are signed using an RS256 algorithm. You can decode and verify user pool tokens using AWS Lambda, see Decode and verify Amazon Cognito JWT tokens on the AWS GitHub website.

Your domain is shown on the Domain name page. Your app client ID and callback URL are shown on the General settings page. If the changes you made in the console do not appear immediately, wait a few minutes and then refresh your browser.

Next step

Step 3. Add social sign-in to a user pool (optional) (p. 26)

Step 3. Add social sign-in to a user pool (optional)

You can enable your app users to sign in through a social identity provider (IdP) such as Facebook, Google, Amazon, and Apple. Whether your users sign in directly or through a third party, all users have a proﬁle in the user pool. Skip this step if you don't want to add sign in through a social sign-in identity provider.

(34)

Step 3. Add social sign-in to a user pool (optional)

Step 1: Register with a social IdP

Before you create a social IdP with Amazon Cognito, you must register your application with the social IdP to receive a client ID and client secret.

To register an app with Facebook

1. Create a developer account with Facebook.

2. Sign in with your Facebook credentials.

3. From the My Apps menu, choose Create New App.

4. Enter a name for your Facebook app and choose Create App ID.

5. On the left navigation bar, choose Settings, and then choose Basic.

6. Note the App ID and the App Secret. You will use them in the next section.

7. Choose + Add Platform from the bottom of the page.

8. Choose Website.

9. Under Website, enter a sign-in URL for your app client endpoint into Site URL. Your sign-in URL should be in the following format:

https://your_user_pool_domain/login?

response_type=code&client_id=your_app_client_id&redirect_uri=your_callback_url 10. Choose Save changes.

11. For App Domains, enter your user pool domain.

https://your_user_pool_domain 12. Choose Save changes.

13. From the navigation bar, choose Products, and then Set up from Facebook Login.

14. From the navigation bar, choose Facebook Login and then Settings.

Enter your redirect URL into Valid OAuth Redirect URIs. The redirect URL will consist of your user pool domain with the /oauth2/idpresponse endpoint.

https://your_user_pool_domain/oauth2/idpresponse 15. Choose Save changes.

To register an app with Amazon

1. Create a developer account with Amazon.

2. Sign in with your Amazon credentials.

3. You need to create an Amazon security proﬁle to receive the Amazon client ID and client secret.

Choose Apps and Services from navigation bar at the top of the page and then choose Login with Amazon.

4. Choose Create a Security Proﬁle.

5. Enter a Security Proﬁle Name, a Security Proﬁle Description, and a Consent Privacy Notice URL.

6. Choose Save.

7. Choose Client ID and Client Secret to show the client ID and secret. You will use them in the next section.

8. Hover over the gear icon and choose Web Settings, and then choose Edit.

(35)

9. Enter your user pool domain into Allowed Origins.

https://<your-user-pool-domain>

10. Enter your user pool domain with the /oauth2/idpresponse endpoint into Allowed Return URLs.

https://<your-user-pool-domain>/oauth2/idpresponse 11. Choose Save.

To register an app with Google

1. Create a developer account with Google.

2. Sign in with your Google credentials.

3. Choose CONFIGURE A PROJECT.

4. Enter a project name, and then choose NEXT.

5. Enter your product name, and then choose NEXT.

6. Select Web browser from the Where are you calling from? drop-down list.

7. Enter your user pool domain into the Authorized JavaScript origins ﬁeld.

8. Choose CREATE. You will not use the Client ID and Client Secret from this step.

9. Choose DONE.

10. Sign in to the Google Console.

11. On the left navigation bar, choose Credentials.

12. Create your OAuth 2.0 credentials by choosing OAuth client ID from the Create credentials drop- down list.

13. Choose Web application.

14. Enter your user pool domain into the Authorized JavaScript origins ﬁeld.

15. Enter your user pool domain with the /oauth2/idpresponse endpoint into the Authorized Redirect URIs ﬁeld.

https://<your-user-pool-domain>/oauth2/idpresponse 16. Choose Create twice.

17. Note the OAuth client ID and client secret. You will need them for the next section.

18. Choose OK.

To register an app with Apple

1. Create a developer account with Apple.

2. Sign in with your Apple credentials.

3. On the left navigation bar, choose Certiﬁcates, IDs & Proﬁles.

4. On the left navigation bar, choose Identiﬁers.

5. On the Identiﬁers page, choose the + icon.

6. On the Register a New Identiﬁer page, choose App IDs, and then choose Continue.

Amazon Cognito

Amazon Cognito

Developer Guide

Amazon Cognito: Developer Guide

Table of Contents

What is Amazon Cognito?

An Amazon Cognito user pool and identity pool used together

Features of Amazon Cognito

Getting started with Amazon Cognito

Regional availability

Pricing for Amazon Cognito

Using the Amazon Cognito console

Getting started with Amazon Cognito

Get an AWS account and your root user credentials

To sign up for an AWS account

Creating an IAM user

Important

To create an administrator user for yourself and add the user to an administrators group (console)

Note

Note

Signing in as an IAM user

Note

Creating IAM user access keys

To create access keys for an IAM user

Common Amazon Cognito scenarios

Authenticate with a user pool

Access your server-side resources with a user pool

Access resources with API Gateway and Lambda with a user pool

Access AWS services with a user pool and an identity pool

Authenticate with a third party and access AWS services with an identity pool

Access AWS AppSync resources with Amazon Cognito

Amazon Cognito tutorials

Tutorial: Creating a user pool

To create a user pool

To create a user pool

Related Resources

Tutorial: Creating an identity pool

To create an identity pool

Related resources

Tutorial: Cleaning up your AWS resources

To delete an identity pool

To delete a user pool

To delete a user pool

Integrating Amazon Cognito with web and mobile apps

Amazon Cognito authentication with the AWS Amplify framework

Multi-tenant application best practices

Note

User pool-based multi-tenancy

Application client-based multi-tenancy

Group-based multi-tenancy

Custom attribute-based multi-tenancy

Multi-tenancy security recommendations

Amazon Cognito user pools

Getting started with user pools

Prerequisite: Sign up for an AWS account

To sign up for an AWS account

Next step

Step 1. Create a user pool

To create a user pool

Note

To create a user pool

Note

Next Step

Step 2. Add an app to enable the hosted web UI

To create an app in your user pool

Note

Note

Note

To create an app in your user pool

Note

Note

Next step

Step 3. Add social sign-in to a user pool (optional)

Step 1: Register with a social IdP