Amazon Cognito
Developer Guide

Adding OIDC Identity Providers to a User Pool

You can enable your users who already have accounts with OpenID Connect (OIDC) identity providers (IdPs) (like Salesforce or Ping Identity) to skip the sign-up step—and sign in to your application using an existing account. 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.


                Authentication overview with an OIDC IdP

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).

You can add an OIDC IdP to your user pool in the AWS Management Console, with the AWS CLI, or by using the user pool API method CreateIdentityProvider.

Prerequisites

Before you begin, you need:

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

  • An OIDC IdP.

Step 1: Register with an OIDC IdP

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

To register with an OIDC IdP

  1. Create a developer account with the OIDC IdP.

    Links to OIDC IdPs

    OIDC IdP How to Install OIDC Discovery URL
    Salesforce

    Install a Salesforce identity provider

    https://login.salesforce.com

    Ping Identity

    Install a Ping Identity identity provider

    https://Your Ping domain address:9031/idp/userinfo.openid

    For example: https://pf.company.com:9031/idp/userinfo.openid

    Okta

    Install an Okta identity provider

    https://Your Okta subdomain.oktapreview.com

    or https://Your Okta subdomain.okta.com

    Microsoft Azure Active Directory (Azure AD)

    Install a Microsoft Azure AD identity provider

    https://login.windows.net/common

    Google

    Install a Google identity provider

    https://accounts.google.com

    Note

    Amazon Cognito offers Google as an integrated social sign-in IdP. We recommend that you use the integrated IdP. See Adding Social Identity Providers to a User Pool.

  2. Register your user pool domain URL with the /oauth2/idpresponse endpoint with your OIDC IdP. This ensures that the OIDC IdP later accepts it from Amazon Cognito when it authenticates users.

    https://<your-user-pool-domain>/oauth2/idpresponse
  3. Register your callback URL with your OIDC IdP. This is the URL of the page where your user will be redirected after a successful authentication.

    https://www.example.com
  4. Select your scopes. The scope openid is required. The email scope is needed to grant access to the email and email_verified claims.

  5. The OIDC IdP provides you with a client ID and a client secret. You'll use them when you set up an OIDC IdP in your user pool.

Example: Use Salesforce as an OIDC IdP with your user pool

You use an OIDC identity provider when you want to establish trust between an OIDC-compatible IdP such as Salesforce and your user pool.

  1. Create an account on the Salesforce Developers website.

  2. Sign in through your developer account that you set up in the previous step.

  3. Look at the top of your Salesforce page.

    • If you’re using Lightning Experience, choose the Setup gear icon, then choose Setup Home.

    • If you’re using Salesforce Classic and you see Setup in the user interface header, choose it.

    • If you’re using Salesforce Classic and you don’t see Setup in the header, choose your name from the top navigation bar, and choose Setup from the drop-down list.

  4. On the left navigation bar, choose Company Settings.

  5. On the navigation bar, choose Domain, type a domain, and choose Create.

  6. On the left navigation bar, go to Platform Tools and choose Apps.

  7. Choose App Manager.

    1. Choose new connected app.

    2. Fill out the required fields.

      Under Start URL, type your user pool domain URL with the /oauth2/idpresponse endpoint.

      https://<your-user-pool-domain>/oauth2/idpresponse
    3. Enable OAuth settings and, type your callback URL into Callback URL. This is the URL of the page where your user will be redirected after a successful sign-in.

      https://www.example.com
  8. Select your scopes. The scope openid is required. The email scope is needed to grant access to the email and email_verified claims.

    Scopes are separated by spaces.

  9. Choose Create.

    In Salesforce, the client ID is called a Consumer Key, and the client secret is a Consumer Secret. Note your client ID and client secret. You will use them in the next section.

Step 2: Add an OIDC IdP to Your User Pool

In this section, you configure your user pool to process OIDC-based authentication requests from an OIDC IdP.

To add an OIDC IdP (Amazon Cognito console)
  1. Go to the Amazon Cognito console. You might be prompted for your AWS credentials.

  2. Choose Manage your 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 OpenId Connect.

  6. Type a unique name into Provider name.

  7. Type the OIDC IdP's client ID from the previous section into Client ID.

  8. Type the client secret from the previous section into Client secret.

  9. In the drop-down list, choose the HTTP method (either GET or POST) that's used to fetch the details of the user from the userinfo endpoint into Attributes request method.

  10. Type the names of the scopes that you want to authorize. Scopes define which user attributes (such as name and email) that you want to access with your application. Scopes are separated by spaces, according to the OAuth 2.0 specification.

    Your app user is asked to consent to providing these attributes to your application.

  11. Type the URL of your IdP and choose Run discovery.

    For example, Salesforce uses this URL:

    https://login.salesforce.com

    Note

    The URL should start with https://, and shouldn't end with a slash /.

    1. If Run discovery isn't successful, then you need to provide the Authorization endpoint, Token endpoint, Userinfo endpoint, and Jwks uri (the location of the JSON Web Key).

  12. Choose Create provider.

  13. On the left navigation bar, choose App client settings.

  14. Select the OIDC provider that you set up in the previous step as one of the Enabled Identity Providers.

  15. Type a callback URL for the Amazon Cognito authorization server to call after users are authenticated. This is the URL of the page where your user will be redirected after a successful authentication.

    https://www.example.com
  16. Under Allowed OAuth Flows, enable both the Authorization code grant and the Implicit code grant.

    Unless you specifically want to exclude one, select the check boxes for all of the Allowed OAuth scopes.

  17. Choose Save changes.

  18. On the Attribute mapping tab on the left navigation bar, add mappings of OIDC claims to user pool attributes.

    1. As a default, the OIDC claim sub is mapped to the user pool attribute Username. You can map other OIDC claims to user pool attributes. Type in the OIDC claim, and choose the corresponding user pool attribute from the drop-down list. For example, the claim email is often mapped to the user pool attribute Email.

    2. In the drop-down list, choose the destination user pool attribute.

    3. Choose Save changes.

    4. Choose Go to summary.

To add an OIDC IdP (AWS CLI)
  • See the parameter descriptions for the CreateIdentityProvider API method.

    aws cognito-idp create-identity-provider --user-pool-id string --provider-name string --provider-type OIDC --provider-details map --attribute-mapping string --idp-identifiers (list) --cli-input-json string --generate-cli-skeleton string

    Use this map of provider details:

    { "client_id": "string", "client_secret": "string", "authorize_scopes": "string", "attributes_request_method": "string", "oidc_issuer": "string", "authorize_url": "string", "token_url": "string", "attributes_url": "string", "jwks_uri": "string" }

Step 3: Test Your OIDC IdP Configuration

You can create the authorization URL by using the elements from the previous two sections, and using them to test your OIDC IdP configuration.

https://<your_user_pool_domain>/oauth2/authorize?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.