Adding social identity providers to a user pool - Amazon Cognito

Adding social identity providers to a user pool

Your web and mobile app users can sign in through social identity providers (IdP) like Facebook, Google, Amazon, and Apple. With the built-in hosted web UI, Amazon Cognito provides token handling and management for all authenticated users, so your backend systems can standardize on one set of user pool tokens. You must enable the hosted UI to integrate with supported social identity providers. When Amazon Cognito builds your hosted UI, it creates OAuth 2.0 endpoints that are used to exchange information with your provider. For more information, see the Amazon Cognito user pools Auth API reference.

You can add a social identity provider in the AWS Management Console, with the AWS CLI, or using Amazon Cognito API calls.


                Authentication overview with social sign-in
Note

Sign-in through a third party (federation) is available in Amazon Cognito user pools. This feature is independent of federation through Amazon Cognito identity pools (federated identities).

Prerequisites

Before you begin, you need:

  • A user pool with an app client and a user pool domain. For more information, see Create a user pool.

  • A social identity provider.

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.

  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 then choose Create App ID.

  5. On the left navigation bar, choose Settings, and then 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 the path to the sign-in page for your app into Site URL.

    https://<your_user_pool_domain>/login?response_type=code&client_id=<your_client_id>&redirect_uri=https://www.example.com
  10. Choose Save changes.

  11. Enter the path to the root of your user pool domain into App Domains.

    https://<your-user-pool-domain>
  12. Choose Save changes.

  13. From the navigation bar choose Add Product and choose Set up for the Facebook Login product.

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

    Enter the path to the /oauth2/idpresponse endpoint for your user pool domain into Valid OAuth Redirect URIs.

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

  1. Create a developer account with Amazon.

  2. Sign in with your Amazon credentials.

  3. You need to create an Amazon security profile 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 Profile.

  5. Enter a Security Profile Name, a Security Profile 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.

  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.

  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 choose NEXT.

  5. Enter your product name and choose NEXT.

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

  7. Enter your user pool domain into Authorized JavaScript origins.

    https://<your-user-pool-domain>
  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 Authorized JavaScript origins.

    https://<your-user-pool-domain>
  15. Enter your user pool domain with the /oauth2/idpresponse endpoint into Authorized Redirect URIs.

    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.

  1. Create a developer account with Apple.

  2. Sign in with your Apple credentials.

  3. On the left navigation bar, choose Certificates, IDs & Profiles.

  4. On the left navigation bar, choose Identifiers.

  5. On the Identifiers page, choose the + icon.

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

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

    1. Enter a Description.

    2. Under App ID Prefix, enter an identifier. Make a note of the value under App ID Prefix as you will use this value after you choose Apple as your identity provider in Step 2: Add a social IdP to your user pool.

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

    4. On the Sign in with Apple: App ID Configuration page, select the appropriate setting for your app, and then choose Save.

    5. Choose Continue.

  8. On the Confirm your App ID page, choose Register.

  9. On the Identifiers page, hover over App IDs on the right side of the page, choose Services IDs, and then choose the + icon.

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

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

    1. Enter a Description.

    2. Under Identifier, enter an identifier. Make a note of this Services ID as you will use this value after you choose Apple as your identity provider in Step 2: Add a social IdP to your user pool.

    3. Select Sign In with Apple, and then choose Configure.

    4. On the Web Authentication Configuration page, choose a Primary App ID. Under Web Domain, enter your user pool domain. Under Return URLs, enter your user pool domain and include the /oauth2/idpresponse endpoint. For example:

      https://<your-user-pool-domain>/oauth2/idpresponse
    5. Choose Add, and then Save. You do not need to verify the domain.

    6. Choose Continue, and then choose Register.

  12. On the left navigation bar, choose Keys.

  13. On the Keys page, choose the + icon.

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

    1. Enter a Key Name.

    2. Choose Sign In with Apple, and then choose Configure.

    3. On the Configure Key page, choose a Primary App ID, and then choose Save.

    4. Choose Continue, and then choose Register.

  15. On the Download Your Key page, choose Download to download the private key, 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 Step 2: Add a social IdP to your user pool.

Step 2: Add a social IdP to your user pool

Original console

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

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

  2. Choose Manage User Pools.

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

  4. On the left navigation bar, choose Identity providers.

  5. Choose a social identity provider: Facebook, Google, Login with Amazon, or Apple.

  6. 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 generated in the previous section.

    • Facebook — Enter the app client ID and app client secret generated in the previous section, and then choose an API version (for example, version 2.12). We recommend chosing the latest possible version, as 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 generated in the previous section.

  7. Enter the names of the scopes that you want to authorize. 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.

    Social identity provider Example scopes
    Facebook public_profile, email
    Google profile email openid
    Login with Amazon profile postal_code
    Sign in with Apple email name

    Your app user is asked to consent to providing these attributes to your app. For more information about their 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 (can be from Internal failures within Amazon Cognito or anything written by the developer)

    • The service ID identifier is used across user pools and other authentication services

    • A developer adds additional scopes after the end user has signed in before (no new information is retrieved)

    • A developer deletes the user and then the user signs in again without removing the app from their Apple ID profile

  8. Choose Enable for the social identity provider that you are configuring.

  9. Choose App client settings from the navigation bar.

  10. Select your social identity provider as one of the Enabled Identity Providers for your user pool app.

  11. Enter your callback URL into Callback URL(s) for your user pool app. This is the URL to which your user will be redirected after a successful authentication.

    https://www.example.com
  12. Choose Save changes.

  13. On the Attribute mapping tab, add mappings for at least the required attributes, typically email, as follows:

    1. Select the check box to choose the Facebook, Google, or Amazon attribute name. You can also type the names of additional attributes that are not listed in the Amazon Cognito console.

    2. Choose the destination user pool attribute from the drop-down list.

    3. Choose Save changes.

    4. Choose Go to summary.

New console

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

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

  2. Choose User Pools.

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

  4. Choose the Sign-in experience tab. Locate Federated sign-in and then select Add an identity provider.

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

  6. 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 generated in the previous section.

    • Facebook — Enter the app client ID and app client secret generated in the previous section, and then choose an API version (for example, version 2.12). We recommend chosing the latest possible version, as 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 generated in the previous section.

  7. Enter the names of the Authorized scopes 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.

    Social identity provider Example scopes
    Facebook public_profile, email
    Google profile email openid
    Login with Amazon profile postal_code
    Sign in with Apple email name

    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 (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 end user has signed in before (no new information is retrieved)

    • A developer deletes the user and then the user signs in again without removing the app from their Apple ID profile

  8. Map attributes from your identity provider to your user pool. For more information, see Specifying Identity Provider Attribute Mappings for Your User Pool.

  9. Choose Create.

  10. From the App client integration tab, 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.

  11. Choose Save changes.

Step 3: Test your social IdP configuration

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

https://<your_user_pool_domain>/login?response_type=code&client_id=<your_client_id>&redirect_uri=https://www.example.com

You can find your domain on the user pool Domain name console page. The client_id is on the App client settings page. Use your callback URL for the redirect_uri parameter. This is the URL of the page where your user will be redirected after a successful authentication.

Note

Requests that are not completed within 5 minutes will be cancelled, redirected to the login page, and then display a Something went wrong error message.