Using OIDC identity providers with a user pool

Users can sign in to your application using their existing accounts from OpenID Connect (OIDC) identity providers (IdPs). With OIDC providers, users of independent single sign-on systems can provide existing credentials while your application receives OIDC tokens in the shared format of user pools. A user pool is an OIDC IdP that can also serve as an intermediate relying party between multiple external OIDC IdPs and your application.

Users who sign in with an OIDC IdP aren't required to provide new credentials or information to access your user pool application. Your application can silently redirect them to their IdP for sign-in, with a user pool as a tool in the background that standardizes the token format for your application. To learn more about IdP redirection, see Authorize endpoint.

Like with other third-party identity providers, you must register your application with the OIDC provider and obtain information about the IdP application that you want to connect to your user pool. A user pool OIDC IdP requires a client ID, client secret, scopes that you want to request, and information about provider service endpoints. Your user pool can discover the provider OIDC endpoints from a discovery endpoint or you can enter them manually. You must also examine provider ID tokens and create attribute mappings between the IdP and the attributes in your user pool.

Note

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

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

Topics

• Prerequisites
• Step 1: Register with an OIDC IdP
• Step 2: Add an OIDC IdP to your user pool
• Step 3: Test your OIDC IdP configuration
• OIDC user pool IdP authentication flow

Prerequisites

Before you begin, you need the following:

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

• An OIDC IdP with the following configuration:

  • Supports client_secret_post client authentication. Amazon Cognito doesn't check the token_endpoint_auth_methods_supported claim at the OIDC discovery endpoint for your IdP. Amazon Cognito doesn't support client_secret_basic client authentication. For more information on client authentication, see Client Authentication in the OpenID Connect documentation.

  • Only uses HTTPS for OIDC endpoints such as openid_configuration, userInfo, and jwks_uri.

  • Only uses TCP ports 80 and 443 for OIDC endpoints.

  • Only signs ID tokens with HMAC-SHA, ECDSA, or RSA algorithms.

  • Publishes a key ID kid claim at its jwks_uri and includes a kid claim in its tokens.

  • Presents a non-expired public key with a valid root CA trust chain.

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.microsoftonline.com/{tenant}/v2.0
   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 Using social identity providers with 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://mydomain.us-east-1.amazoncognito.com/oauth2/idpresponse

3. Register your callback URL with your Amazon Cognito user pool. This is the URL of the page where Amazon Cognito redirects your user 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 IdP 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. From your Salesforce page, do one of the following:

   • 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, enter a domain, and choose Create.

6. On the left navigation bar, under Platform Tools, choose Apps.

7. Choose App Manager.

8. 1. Choose New connected app.

   2. Complete the required fields.

      Under Start URL, enter a URL at the /authorize endpoint for the user pool domain that signs in with your Salesforce IdP. When your users access your connected app, Salesforce directs them to this URL to complete sign-in. Then Salesforce redirects the users to the callback URL that you have associated with your app client.

      https://mydomain.us-east-1.amazoncognito.com/authorize?response_type=code&client_id=<your_client_id>&redirect_uri=https://www.example.com&identity_provider=CorpSalesforce

   3. Enable OAuth settings and enter the URL of the /oauth2/idpresponse endpoint for your user pool domain in Callback URL. This is the URL where Salesforce issues the authorization code that Amazon Cognito exchanges for an OAuth token.

      https://mydomain.us-east-1.amazoncognito.com/oauth2/idpresponse

9. Select your scopes. You must include the scope openid. To grant access to the email and email_verified claims, add the email scope. Separate scopes by spaces.

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

Add an OIDC IdP

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

2. Choose User Pools from the navigation menu.

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 select Add an identity provider.

5. Choose an OpenID Connect IdP.

6. Enter a unique name into Provider name.

7. Enter the client ID you received from your provider into Client ID.

8. Enter the client secret you received from your provider into Client secret.

9. Enter Authorized scopes for this provider. Scopes define which groups of user attributes (such as name and email) that your application will request from your provider. Scopes must be separated by spaces, following the OAuth 2.0 specification.

   Your user will be asked to consent to providing these attributes to your application.

10. Choose an Attribute request method to provide Amazon Cognito with the HTTP method (either GET or POST) that it must use to fetch the details of the user from the userInfo endpoint operated by your provider.

11. Choose a Setup method to retrieve OpenID Connect endpoints either by Auto fill through issuer URL or Manual input. Use Auto fill through issuer URL when your provider has a public .well-known/openid-configuration endpoint where Amazon Cognito can retrieve the URLs of the authorization, token, userInfo, and jwks_uri endpoints.

12. Enter the issuer URL or authorization, token, userInfo, and jwks_uri endpoint URLs from your IdP.

    Note

    The URL should start with https://, and shouldn't end with a slash /. Only port numbers 443 and 80 can be used with this URL. For example, Salesforce uses this URL:

    https://login.salesforce.com

    If you choose auto fill, the discovery document must use HTTPS for the following values: authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri. Otherwise the login will fail.

13. The OIDC claim sub is mapped to the user pool attribute Username by default. You can map other OIDC claims to user pool attributes. Enter 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.

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

15. Choose Create.

16. From the App client integration tab, choose one of the App clients in the list and Edit hosted UI settings. Add the new OIDC IdP to the app client under Identity providers.

17. Choose Save changes.

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://mydomain.us-east-1.amazoncognito.com/oauth2/authorize?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_id is on the General 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.