# Getting started with user pools
<a name="getting-started-user-pools"></a>

You have an application that requires authentication and access control. You can work within the OpenID Connect (OIDC) framework for single sign-on (SSO). Amazon Cognito has tools for handling the logic of authentication in the application back end with an AWS SDK, and for invoking a browser in your client to access a managed authorization server.

The Amazon Cognito console guides you through the creation of a user pool from the view of your preferred application framework. From there, you can continue on to add features like federated sign-in with external [social](tutorial-create-user-pool-social-idp.md) or [SAML 2.0](tutorial-create-user-pool-saml-idp.md) identity providers (IdPs). The application models in the Amazon Cognito console lean on the addition of OIDC libraries to your project and invoking a browser.

As you work to expand your feature set and incorporate more components of Amazon Cognito, read the [Amazon Cognito user pools](cognito-user-pools.md) chapter for full descriptions of everything you can do with user pools.

The examples in this chapter and in the Amazon Cognito console demonstrate a basic integration of application resources with Amazon Cognito user pools. Later, you can adjust your user pool to use more of the options that are available to you. Then you can update your application to adopt new features and interact with IdPs.

If you don't want to use the [managed login pages](cognito-terms.md#terms-managedlogin), you can create an application with custom-built authentication interfaces using an AWS SDK or AWS Amplify. Applications that you build in this way interact with the [user pools API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) and are suitable only for authenticating [local users](cognito-terms.md#terms-localuser). Continue learning about this authentication model at [Other application options](getting-started-user-pools-application-other-options.md).

**Topics**
+ [

# Create a new application in the Amazon Cognito console
](getting-started-user-pools-application.md)
+ [

# Other application options
](getting-started-user-pools-application-other-options.md)
+ [

# Add more features and security options to your user pool
](user-pool-next-steps.md)

# Create a new application in the Amazon Cognito console
<a name="getting-started-user-pools-application"></a>

User pools add authentication options to software applications. For the easiest getting-started experience, step into the Amazon Cognito console and follow the instructions there. The creation process there guides you not only through setup of user pool resources, but through setting up the initial pieces of your application.

When you're ready to begin, navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/v2/idp/user-pools) and select the button to create a new user pool. The setup process will guide you through your configuration and programming-language options.

**Additional resources for authentication concepts**
+ [Authentication with Amazon Cognito user pools](authentication.md)
+ [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations)
+ [How authentication works with Amazon Cognito](cognito-how-to-authenticate.md)
+ [Integrating Amazon Cognito authentication and authorization with web and mobile apps](cognito-integrate-apps.md)

**To create Amazon Cognito resources for your application**

1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/). To assign permissions to your IAM principal so that they can create and manage Amazon Cognito resources, refer to [AWS managed policies for Amazon Cognito](security-iam-awsmanpol.md). The `AmazonCognitoPowerUser` policy is sufficient for the creation of user pools.

1. Select **Create user pool** from the **User pools** menu, or select **Get started for free in less than five minutes**.

1. Under **Define your application**, choose the **Application type** that best fits the application scenario that you want to create authentication and authorization services for.

1. In **Name your application**, enter a descriptive name or proceed with the default name.

1. You must make some basic choices under **Configure options** that support settings that you can't change after you create your user pool.

   1. Under **Options for sign-in identifiers**, tell us how you want to identify users when they sign in. You can prefer user-generated usernames, email addresses, or phone numbers. You can also allow a combination of multiple options. Amazon Cognito accepts the options that you configure here in the username field of [managed login](cognito-user-pools-managed-login.md) sign-in forms.

   1. Under **Required attributes for sign-up**, tell us what user information you want to collect when users register for a new account. In managed login pages, Amazon Cognito presents prompts for all required attributes.

      **Options for sign-in identifiers** influences your required attributes. **Username** requires email or phone attributes for each user so that they can receive a password-reset code in an email or SMS message. **Email** requires the email attribute, and **Phone number** requires the phone number attribute.

1. Under **Add a return URL**, enter a redirect path to your application for after users complete authentication. This location should be a route in your application that uses OpenID Connect (OIDC) libraries to process user-authentication outcomes. An example of a return URL for a test application is `https://localhost:3000/callback`. In the example NodeJS application in the Amazon Cognito console, this route employs [openid-client](https://www.npmjs.com/package/openid-client) to collect the access token and redeem it for user information. You'll be able to browse examples for your development platform after you create your resources.

1. Choose **Create your application**. Amazon Cognito creates a user pool and app client with default settings for your application type. You can configure additional options like [external identity providers](cognito-user-pools-identity-federation.md) and [multi-factor authentication (MFA)](user-pool-settings-mfa.md#user-pool-configuring-mfa) after you create your initial resources.

1. On the **Set up your application** page, you can immediately get code examples for your application. To explore your new user pool, scroll down and select **Go to overview**.

1. To add more applications in the same user pool, navigate to the **App clients** menu and add a new app client. This will repeat the process of application-focused creation, but only add a new app client to the existing user pool.

After you create a user pool and one or more app clients with this process, you can start testing authentication operations with managed login. These quick-start options are open to public self sign-up. We recommend that you create a testing environment with the console process, then move your finalized design to production. Spend time familiarizing yourself with the capabilities of Amazon Cognito. Then, to move to production workloads, craft custom configurations and deploy them with automation tools like AWS CloudFormation and the AWS Cloud Development Kit (AWS CDK).

Amazon Cognito makes some default configurations in this process that you can't reverse. For more information about user pool settings that you can't change and those options that you can choose in the console, see [Updating user pool and app client configuration](cognito-user-pool-updating.md).


| Setting | Effect | How to change | More information | 
| --- | --- | --- | --- | 
| Client secret | Requires a client secret hash in authentication requests. | Create a new app client with a Traditional web application or Machine-to-machine application profile. | [Application-specific settings with app clients](user-pool-settings-client-apps.md) | 
| Preferred username | User pool doesn't accept the preferred\$1username attribute as an alias. | Create a user pool programmatically with an AWS SDK. | [Customizing sign-in attributes](user-pool-settings-attributes.md#user-pool-settings-aliases) | 
| Case sensitivity | User pool usernames are case insensitive, for example JohnD is considered to be the same user as johnd. | Create a user pool programmatically with an AWS SDK. | [User pool case sensitivity](user-pool-case-sensitivity.md) | 

# Other application options
<a name="getting-started-user-pools-application-other-options"></a>

You might have an existing application UI that you want to integrate with Amazon Cognito authentication. You might even have your own existing authentication pages with a less-functional directory setup than Amazon Cognito user pools. You can add or replace an authentication component to an application of this type with Amazon Cognito integrations in AWS SDKs for a variety of programming languages. Some examples follow.

If you create a user pool for this purpose in the Amazon Cognito console, it might not be necessary to have a [user pool domain](cognito-user-pools-assign-domain.md) that hosts interactive sign-in pages and OpenID Connect (OIDC) services. The process of user pool creation in the console automatically generates a domain for you. You can delete this domain from the **Domain** tab of your user pool. Other options include programmatic creation of Amazon Cognito resources for you application with API requests in AWS SDKs and with the automated-setup options in the AWS Amplify CLI. For more information, see [Integrating Amazon Cognito authentication and authorization with web and mobile apps](cognito-integrate-apps.md).

**Topics**
+ [

## Set up an example React single page application
](#getting-started-test-application-react)
+ [

## Set up an example Android app with Flutter
](#getting-started-test-application-flutter)

## Set up an example React single page application
<a name="getting-started-test-application-react"></a>

In this tutorial, you'll create a React single page application where you can test user sign-up, confirmation, and sign-in. React is a JavaScript-based library for web and mobile apps, with a focus on the user interface (UI). This example application demonstrates some basic functions of Amazon Cognito user pools. If you're already experienced in web app development with React, [download the example app from GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cognito-identity-provider/scenarios/cognito-developer-guide-react-example).

The following screenshot is of the initial authentication page in the application that you'll create.

![\[A screenshot of the sign-up page for a React-based example web application.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cognito-getting-started-react-app-running.png)


To set up this application, your user pool must meet the following requirements:
+ Users can sign in with their email address. **Cognito user pool sign-in options**: **Email**.
+ Usernames are case insensitive. **User name requirements**: **Make user name case sensitive** is not selected.
+ Multi-factor authentication (MFA) isn't required. **MFA enforcement**: **Optional MFA**.
+ Your user pool verifies attributes for user-profile confirmation with an email message. **Attributes to verify**: **Send email message, verify email address**.
+ Email is the only required attribute. **Required attributes**: **email**.
+ Users can sign themselves up in your user pool. **Self-registration**: **Enable self-registration** is selected.
+ Your initial app client is a public client that permits sign-in with username and password. **App type**: **Public client**, **Authentication flows**: `ALLOW_USER_PASSWORD_AUTH`.

### Create an application
<a name="getting-started-test-application-react-create-app"></a>

To build this application, you must set up a developer environment. The developer environment requirements are:

1. Node.js is installed and updated.

1. Node package manager (npm) is installed and updated to at least version 10.2.3.

1. The environment is accessible on TCP port 5173 in a web browser.

**To create an example React web application**

1. Sign in to your developer environment and navigate to the parent directory for your application.

   ```
   cd ~/path/to/project/folder/
   ```

1. Create a new React service.

   ```
   npm create vite@latest frontend-client -- --template react-ts
   ```

1. Clone the `cognito-developer-guide-react-example` [project folder](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cognito-identity-provider/scenarios/cognito-developer-guide-react-example) from the AWS code examples repository on GitHub.

   ```
   cd ~/some/other/path
   ```

   ```
   git clone https://github.com/awsdocs/aws-doc-sdk-examples.git
   ```

   ```
   cp -r ./aws-doc-sdk-examples/javascriptv3/example_code/cognito-identity-provider/scenarios/cognito-developer-guide-react-example/frontend-client ~/path/to/project/folder/
   ```

1. Navigate to the `src` directory in your project.

   ```
   cd ~/path/to/project/folder/frontend-client/src
   ```

1. Edit `config.json` and replace the following values:

   1. Replace `YOUR_AWS_REGION` with an AWS Region code. For example: `us-east-1`.

   1. Replace `YOUR_COGNITO_USER_POOL_ID` with the ID of the user pool that you have designated for testing. For example: `us-east-1_EXAMPLE`. The user pool must be in the AWS Region that you entered in the previous step.

   1. Replace `YOUR_COGNITO_APP_CLIENT_ID` with the ID of the app client that you have designated for testing. For example: `1example23456789`. The app client must be in the user pool from the previous step.

1. If you want to access your example application from an IP other than `localhost`, edit `package.json` and change the line `"dev": "vite",` to `"dev": "vite --host 0.0.0.0",`.

1. Install your application.

   ```
   npm install
   ```

1. Launch the application.

   ```
   npm run dev
   ```

1. Access the application in a web browser at `http://localhost:5173` or `http://[IP address]:5173`.

1. Sign up a new user with a valid email address.

1. Retrieve the confirmation code from your email message. Enter the confirmation code into the application.

1. Sign in with your username and password.

### Creating a React developer environment with Amazon Lightsail
<a name="getting-started-test-application-react-lightsail"></a>

A quick way to get started with this application is to create a virtual cloud server with Amazon Lightsail. 

With Lightsail, you can quickly create a small server instance that comes preconfigured with the prerequisites for this example application. You can SSH to your instance with a browser-based client, and connect to the web server at a public or private IP address.

**To create a Lightsail instance for this example application**

1. Go to the [Lightsail console](https://lightsail.aws.amazon.com/ls/webapp/). If prompted, enter your AWS credentials.

1. Choose **Create instance**.

1. For **Select a platform**, choose **Linux/Unix**.

1. For **Select a blueprint**, choose **Node.js**.

1. Under **Identify your instance**, give your development environment a friendly name.

1. Choose **Create instance**.

1. After Lightsail has created your instance, select it and from the **Connect** tab, choose **Connect using SSH**.

1. An SSH session opens in a browser window. Run `node -v` and `npm -v` to confirm that your instance was provisioned with Node.js and the minimum npm version of 10.2.3.

1. Proceed to [configure your React application](#getting-started-test-application-react).

## Set up an example Android app with Flutter
<a name="getting-started-test-application-flutter"></a>

In this tutorial, you'll create a mobile application in Android Studio where you can emulate a device and test user sign-up, confirmation, and sign-in. This example application creates a basic Amazon Cognito user pools mobile client for Android in Flutter. If you're already experienced in mobile app development with Flutter, [download the example app from GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/usecases/cognito_flutter_mobile_app).

The following screenshot shows the app running on a virtual Android device.

![\[A screenshot of the sign-up page for a virtualized Android example app.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cognito-getting-started-android-app-running.png)


To set up this application, you user pool must meet the following requirements:
+ Users can sign in with their email address. **Cognito user pool sign-in options**: **Email**.
+ Usernames are case insensitive. **User name requirements**: **Make user name case sensitive** is not selected.
+ Multi-factor authentication (MFA) isn't required. **MFA enforcement**: **Optional MFA**.
+ Your user pool verifies attributes for user-profile confirmation with an email message. **Attributes to verify**: **Send email message, verify email address**.
+ Email is the only required attribute. **Required attributes**: **email**.
+ Users can sign themselves up in your user pool. **Self-registration**: **Enable self-registration** is selected.
+ Your initial app client is a public client that permits sign-in with username and password. **App type**: **Public client**, **Authentication flows**: `ALLOW_USER_PASSWORD_AUTH`.

### Create an application
<a name="getting-started-test-application-flutter-create-app"></a>

**To create an example Android app**

1. Install [Android studio](https://developer.android.com/studio) and [command-line tools](https://developer.android.com/tools).

1. In Android Studio, install the [Flutter plugin](https://docs.flutter.dev/get-started/editor?tab=androidstudio).

1. Create a new Android Studio project from the contents of the `cognito_flutter_mobile_app` directory in [this example app](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/usecases/cognito_flutter_mobile_app).

   1. Edit `assets/config.json` and replace `<<YOUR USER POOL ID>>` and `<< YOUR CLIENT ID>>` with the IDs of your user pool and app client.

1. Install [Flutter](https://docs.flutter.dev/get-started/install).

   1. Add Flutter to your PATH variable.

   1. Accept licenses with the following command.

      `flutter doctor --android-licenses`

   1. Verify your Flutter environment and install any missing components.

      `flutter doctor`

      1. If any components are missing, run `flutter doctor -v` to learn how to fix the issue.

   1. Change to the directory of your new Flutter project and install dependencies.

      1. Run `flutter pub add amazon_cognito_identity_dart_2`.

   1. Run `flutter pub add flutter_secure_storage`.

1. Create a virtual Android device.

   1. In the Android studio GUI, create a new device with the [device manager](https://developer.android.com/studio/run/managing-avds).

   1. In the CLI, run `flutter emulators --create --name android-device`.

1. Launch your virtual Android device.

   1. In the Android Studio GUI, select the start ![\[Play button icon with a blue triangle pointing to the right.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cognito-getting-started-android-virtual-device-start.png) icon next to your virtual device.

   1. In the CLI, run `flutter emulators --launch android-device`.

1. Launch your app on your virtual device.

   1. In the Android Studio GUI, select the deploy ![\[Green play button icon representing a start or play action.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cognito-getting-started-android-app-start.png) icon.

   1. In the CLI, run `flutter run`.

1. Navigate to your running virtual device in Android Studio.

1. Sign up a new user with a valid email address.

1. Retrieve the confirmation code from your email message. Enter the confirmation code into the application.

1. Sign in with your username and password.

# Add more features and security options to your user pool
<a name="user-pool-next-steps"></a>

After you have followed the tutorials to complete example applications, you can broaden the scope of your user pool implementation. Or, if you didn't create a test application, create a new user pool according to your preferences. You can customize user pool features for other applications or [add external identity providers](tutorial-create-user-pool-social-idp.md). As you plan your move to put Amazon Cognito user pools in production applications, you can evaluate [additional examples and tutorials](cognito-guided-setup.md).

If your next priority is to examine and apply application security options in your user pools, see [Security best practices for Amazon Cognito user pools](user-pool-security-best-practices.md).

Amazon Cognito has feature plans that add functional and security options when you opt in to higher tiers. You can start with the *Lite* plan, add advanced authentication and authorization options with the *Essentials* plan, and add automated-reasoning security guardrails with the *Plus* plan. For more information, see [User pool feature plans](cognito-sign-in-feature-plans.md).

The following are some additional Amazon Cognito user pools features:
+ [Apply branding to managed login pages](managed-login-branding.md)
+ [Adding MFA to a user pool](user-pool-settings-mfa.md)
+ [Advanced security with threat protection](cognito-user-pool-settings-threat-protection.md)
+ [Customizing user pool workflows with Lambda triggers](cognito-user-pools-working-with-lambda-triggers.md)
+ [Using Amazon Pinpoint for user pool analytics](cognito-user-pools-pinpoint-integration.md)

For an overview of Amazon Cognito authentication and authorization models, see [How authentication works with Amazon Cognito](cognito-how-to-authenticate.md).

To access other AWS services after a successful user pool authentication, see [Accessing AWS services using an identity pool after sign-in](amazon-cognito-integrating-user-pools-with-identity-pools.md).

In addition to using the AWS Management Console and the user pool SDKs, you can also manage your user pools by using the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/index.html).

**Topics**
+ [

# Add social sign-in to your user pool
](tutorial-create-user-pool-social-idp.md)
+ [

# Add a SAML 2.0 identity provider
](tutorial-create-user-pool-saml-idp.md)

# Add social sign-in to your user pool
<a name="tutorial-create-user-pool-social-idp"></a>

Providing users with the ability to sign in to your application through their existing public, or social, identity providers can improve their authentication experience. Amazon Cognito user pools integrate with popular social identity providers (IdPs) like Facebook, Google, Amazon, and Apple, giving your users convenient sign-in options that they are already familiar with.

When you set up social sign-in, you are giving your users an alternative to creating a dedicated account just for your application. This can improve conversion rates and make the sign-up process more seamless. From the user's perspective, they can apply their existing social credentials to quickly authenticate, without the friction of remembering another username and password.

Configuring a social IdP in your user pool involves a few key steps. You must register your application with the social provider to obtain a client ID and secret. Then you can add the social IdP configuration to your user pool, specifying the scopes that you want to request and the user pool attributes that you want to map from IdP attributes. At runtime, Amazon Cognito handles the token exchange with the provider, maps user attributes, and issues tokens to your application in the shared user pool format.

## Register with a social IdP
<a name="cognito-user-pools-social-step-1"></a>

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
<a name="register-an-app-with-facebook"></a>

1. Create a [developer account with Facebook](https://developers.facebook.com/docs/facebook-login).

1. [Sign in](https://developers.facebook.com/) with your Facebook credentials.

1. From the **My Apps** menu, choose **Create New App**. 

   If you don't have an existing Facebook app, you will see a different option. Choose **Create App**.

1. On the **Create an app** page, choose a use case for your app, and then choose **Next**.

1. Enter a name for your Facebook app and choose **Create App**.

1. On the left navigation bar, choose **App Settings**, and then choose **Basic**.

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

1. Choose **\$1 Add platform** from the bottom of the page.

1. On the **Select Platform** screen, select your platforms, and then choose **Next**.

1. Choose **Save changes**.

1. For **App Domains**, enter your user pool domain.

   ```
   https://your_user_pool_domain
   ```

1. Choose **Save changes**.

1. From the navigation bar, choose **Products**, and then choose **Configure** from **Facebook Login**.

1. From the **Facebook Login** **Configure** menu, choose **Settings**.

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

   ```
   https://your_user_pool_domain/oauth2/idpresponse
   ```

1. Choose **Save changes**.

### To register an app with Amazon
<a name="register-an-app-with-amazon"></a>

1. Create a [developer account with Amazon](https://developer.amazon.com/login-with-amazon).

1. [Sign in](https://developer.amazon.com/lwa/sp/overview.html) with your Amazon credentials.

1. You need to create an Amazon security profile to receive the Amazon client ID and client secret.

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

1. Choose **Create a Security Profile**.

1. Enter a **Security Profile Name**, a **Security Profile Description**, and a **Consent Privacy Notice URL**.

1. Choose **Save**.

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

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

1. Enter your user pool domain into **Allowed Origins**.

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

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

   ```
   https://<your-user-pool-domain>/oauth2/idpresponse
   ```

1. Choose **Save**.

### To register an app with Google
<a name="register-an-app-with-google"></a>

For more information about OAuth 2.0 in the Google Cloud platform, see [Learn about authentication & authorization](https://developers.google.com/workspace/guides/auth-overview) in the Google Workspace for Developers documentation.

1. Create a [developer account with Google](https://developers.google.com/identity).

1. Sign in to the [Google Cloud Platform console](https://console.cloud.google.com/home/dashboard).

1. From the top navigation bar, choose **Select a project**. If you already have a project in the Google platform, this menu displays your default project instead.

1. Select **NEW PROJECT**.

1. Enter a name for your product and then choose **CREATE**.

1. On the left navigation bar, choose **APIs and Services**, and then choose **Oauth consent screen**.

1. Enter the app information, an **App domain**, **Authorized domains**, and **Developer contact information**. Your **Authorized domains** must include `amazoncognito.com` and the root of your custom domain. For example: `example.com`. Choose **SAVE AND CONTINUE**.

1. 1. Under **Scopes**, choose **Add or remove scopes**, and then choose, at a minimum, the following OAuth scopes.

   1. `.../auth/userinfo.email`

   1. `.../auth/userinfo.profile`

   1. openid

1. Under **Test users**, choose **Add users**. Enter your email address and any other authorized test users, and then choose **SAVE AND CONTINUE**.

1. Expand the left navigation bar again, choose **APIs and Services**, and then choose **Credentials**. 

1. Choose **CREATE CREDENTIALS**, and then choose **OAuth client ID**.

1. Choose an **Application type** and give your client a **Name**.

1. Under **Authorized JavaScript origins**, choose **ADD URI**. Enter your user pool domain.

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

1. Under **Authorized redirect URIs**, choose **ADD URI**. Enter the path to the `/oauth2/idpresponse` endpoint of your user pool domain.

   ```
   https://<your-user-pool-domain>/oauth2/idpresponse
   ```

1. Choose **CREATE**.

1. Securely store the values that Google displays under **Your client ID** and **Your client secret**. Provide these values to Amazon Cognito when you add a Google IdP.

### To register an app with Apple
<a name="register-an-app-with-apple"></a>

For more information about setting up Sign in with Apple, see [Configuring Your Environment for Sign in with Apple](https://developer.apple.com/documentation/signinwithapple/configuring-your-environment-for-sign-in-with-apple) in the Apple Developer documentation.

1. Create a [developer account with Apple](https://developer.apple.com/programs/enroll/).

1. [Sign in](https://developer.apple.com/account/#/welcome) with your Apple credentials.

1. On the left navigation bar, choose **Certificates, Identifiers & Profiles**.

1. On the left navigation bar, choose **Identifiers**.

1. On the **Identifiers** page, choose the **\$1** icon.

1. On the **Register a New Identifier** page, choose **App IDs**, and then choose **Continue**.

1. On the **Select a type** page, choose **App**, and then choose **Continue**.

1. On the **Register an App ID** page, do the following:

   1. Under **Description**, enter a description.

   1. Under **App ID Prefix**, enter a **Bundle ID**. Make a note of the value under **App ID Prefix**. You will use this value after you choose Apple as your identity provider in [Configure your user pool with a social IdP](cognito-user-pools-social-idp.md#cognito-user-pools-social-idp-step-2).

   1. Under **Capabilities**, choose **Sign In with Apple**, and then choose **Edit**.

   1. On the **Sign in with Apple: App ID Configuration** page, choose to set up the app as either primary or grouped with other App IDs, and then choose **Save**.

   1. Choose **Continue**.

1. On the **Confirm your App ID** page, choose **Register**.

1. On the **Identifiers** page, choose the **\$1** icon.

1. On the **Register a New Identifier** page, choose **Services IDs**, and then choose **Continue**.

1. On the **Register a Services ID** page, do the following:

   1. Under **Description**, enter a description.

   1. Under **Identifier**, enter an identifier. Make a note of this Services ID because you'll need this value after you choose Apple as your identity provider in [Configure your user pool with a social IdP](cognito-user-pools-social-idp.md#cognito-user-pools-social-idp-step-2).

   1. Choose **Continue** and then choose **Register**.

1. Choose the Services ID that you just created from the Identifiers page.

   1. Select **Sign In with Apple**, and then choose **Configure**.

   1. On the **Web Authentication Configuration** page, select the app ID that you created earlier as the **Primary App ID**. 

   1. Choose the **\$1** icon next to **Website URLs**. 

   1. Under **Domains and subdomains**, enter your user pool domain without an `https://` prefix.

      ```
      <your-user-pool-domain>
      ```

   1. Under **Return URLs**, enter the path to the `/oauth2/idpresponse` endpoint of your user pool domain.

      ```
      https://<your-user-pool-domain>/oauth2/idpresponse
      ```

   1. Choose **Next**, and then choose **Done**. You don't need to verify the domain.

   1. Choose **Continue**, and then choose **Save**.

1. On the left navigation bar, choose **Keys**.

1. On the **Keys** page, choose the **\$1** icon.

1. On the **Register a New Key** page, do the following:

   1. Under **Key Name**, enter a key name. 

   1. Choose **Sign In with Apple**, and then choose **Configure**.

   1. On the **Configure Key** page, select the app ID that you created earlier as the **Primary App ID**. Choose **Save**.

   1. Choose **Continue**, and then choose **Register**.

1. On the **Download Your Key** page, choose **Download** to download the private key, note the **Key ID** shown, and then choose **Done**. You will need this private key and the **Key ID** value shown on this page after you choose Apple as your identity provider in [Configure your user pool with a social IdP](cognito-user-pools-social-idp.md#cognito-user-pools-social-idp-step-2).

## Add a social IdP to your user pool
<a name="cognito-user-pools-social-step-2"></a>

In this section, you configure a social IdP in your user pool using the client ID and client secret from the previous section.

**To configure a user pool social identity provider with the AWS Management Console**

1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). You might be prompted for your AWS credentials.

1. Choose **User Pools**.

1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).

1. Choose the **Social and external providers** menu. Locate **Federated sign-in** and select **Add an identity provider**.

1. Choose a social identity provider: **Facebook**, **Google**, **Login with Amazon**, or **Sign in with Apple**.

1. Choose from the following steps, based on your choice of social identity provider:
   + **Google** and **Login with Amazon** – Enter the **app client ID** and **app client secret** that was generated in the previous section.
   + **Facebook** – Enter the **app client ID** and **app client secret** that was generated in the previous section, and then choose an API version (for example, version 2.12). We recommend choosing the latest possible version—each Facebook API has a lifecycle and deprecation date. Facebook scopes and attributes can vary between API versions. We recommend testing your social identity log in with Facebook to ensure that federation works as intended.
   + **Sign in with Apple** – Enter the **Services ID**, **Team ID**, **Key ID**, and **private key** that was generated in the previous section.

1. Enter the names of the **Authorized scopes** that you want to use. Scopes define which user attributes (such as `name` and `email`) you want to access with your app. For Facebook, these should be separated by commas. For Google and Login with Amazon, they should be separated by spaces. For Sign in with Apple, select the check boxes for the scopes you want access to.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool-social-idp.html)

   Your app user is prompted to consent to providing these attributes to your app. For more information about social provider scopes, see the documentation from Google, Facebook, Login with Amazon, or Sign in with Apple. 

   With Sign in with Apple, the following are user scenarios where scopes might not be returned:
   + An end user encounters failures after leaving Apple’s sign in page (these can be from internal failures within Amazon Cognito or anything written by the developer).
   + The service ID identifier is used across user pools and/or other authentication services.
   + A developer adds additional scopes after the user signs in. Users only retrieve new information when they authenticate and when they refresh their tokens.
   + A developer deletes the user and then the user signs in again without removing the app from their Apple ID profile.

1. Map attributes from your identity provider to your user pool. For more information, see [Things to know about mappings](cognito-user-pools-specifying-attribute-mapping.md#cognito-user-pools-specifying-attribute-mapping-requirements).

1. Choose **Create**.

1. From the **App clients** menu, choose one of the app clients in the list and **Edit hosted UI settings**. Add the new social identity provider to the app client under **Identity providers**.

1. Choose **Save changes**.

## Test your social IdP configuration
<a name="cognito-user-pools-social-step-3"></a>

You can create a login URL by using the elements from the previous two sections. Use it to test your social IdP configuration.

```
https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```

You can find your domain on the user pool **Domain name** console page. The client\$1id is on the **App client settings** page. Use your callback URL for the **redirect\$1uri** parameter. This is the URL of the page where your user will be redirected after a successful authentication.

**Note**  
Amazon Cognito cancels authentication requests that do not complete within 5 minutes, and redirects the user to managed login. The page displays a `Something went wrong` error message.

# Add a SAML 2.0 identity provider
<a name="tutorial-create-user-pool-saml-idp"></a>

Your app users can sign in with a SAML 2.0 identity provider (IdP). You might choose SAML 2.0 IdPs over social IdPs when your customers are the internal customers or linked businesses of your organization. Where a social IdP permits all users to register for an account, a SAML IdP is more likely to pair with a user directory that your organization controls. Whether your users sign in directly or through a third party, all users have a profile in the user pool. Skip this step if you don't want to add sign in through a SAML identity provider. 

For more information, see [Using SAML identity providers with a user pool](cognito-user-pools-saml-idp.md).

You must update your SAML identity provider and configure your user pool. For information about how to add your user pool as a relying party or application for your SAML 2.0 identity provider, see the documentation for your SAML identity provider.

You must also provide an assertion consumer service (ACS) endpoint to your SAML identity provider. Configure the following endpoint in your user pool domain for SAML 2.0 POST binding in your SAML identity provider. For more information about user pool domains, see [Configuring a user pool domain](cognito-user-pools-assign-domain.md).

```
https://Your user pool domain/saml2/idpresponse
With an Amazon Cognito domain:
https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
With a custom domain:
https://Your custom domain/saml2/idpresponse
```

You can find your domain prefix and the Region value for your user pool in the **Domain** menu in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).

For some SAML identity providers, you also need to provide the service provider (SP) `urn`, also called the audience URI or SP entity ID, in the format:

```
urn:amazon:cognito:sp:<yourUserPoolID>
```

You can find your user pool ID in the **Overview** dashboard for your user pool in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).

You should also configure your SAML identity provider to provide attribute values for any attributes that are required in your user pool. Typically, `email` is a required attribute for user pools. In that case, the SAML identity provider should provide an `email` value (claim) in the SAML assertion.

Amazon Cognito user pools support SAML 2.0 federation with post-binding endpoints. This eliminates the need for your app to retrieve or parse SAML assertion responses because the user pool directly receives the SAML response from your identity provider through a user agent.

**To configure a SAML 2.0 identity provider in your user pool**

1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.

1. Choose **User Pools**.

1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).

1. Choose the **Social and external providers** menu. Locate **Federated sign-in** and select **Add an identity provider**.

1. Choose a **SAML** social identity provider.

1. Enter **Identifiers** separated by commas. An identifier tells Amazon Cognito it should check the email address that a user enters when they sign in. Then it directs them to the provider that corresponds to their domain.

1. Choose **Add sign-out flow** if you want Amazon Cognito to send signed sign-out requests to your provider when a user logs out. You must configure your SAML 2.0 identity provider to send sign-out responses to the `https://<your Amazon Cognito domain>/saml2/logout` endpoint that is created when you configure managed login. The `saml2/logout` endpoint uses the POST binding.
**Note**  
If this option is selected and your SAML identity provider expects a signed logout request, you will also need to configure the signing certificate that is provided by Amazon Cognito with your SAML IdP.   
The SAML IdP will process the signed logout request and will log out your user from the Amazon Cognito session.

1. Choose a **Metadata document source**. If your identity provider offers SAML metadata at a public URL, you can choose **Metadata document URL** and enter that public URL. Otherwise, choose **Upload metadata document** and select a metadata file you downloaded from your provider earlier.
**Note**  
We recommend that you enter a metadata document URL if your provider has a public endpoint, rather than uploading a file. This allows Amazon Cognito to refresh the metadata automatically. Typically, metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier.

1. Select **Map attributes between your SAML provider and your app** to map SAML provider attributes to the user profile in your user pool. Include your user pool required attributes in your attribute map. 

   For example, when you choose the **User pool attribute** `email`, enter the SAML attribute name as it appears in the SAML assertion from your identity provider. Your identity provider might offer sample SAML assertions for reference. Some identity providers use simple names, such as `email`, while others use URL-formatted attribute names, such as the following example:

   ```
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   ```

1. Choose **Create**.