How do I set up Okta as an OpenID Connect identity provider in an Amazon Cognito user pool?

Last updated: 2019-12-20

I want to use Okta as an OpenID Connect (OIDC) identity provider (IdP) in an Amazon Cognito user pool. How do I set that up?

Short Description

Amazon Cognito user pools allow sign-in through a third party (federation), including through an IdP such as Okta. For more information, see Adding User Pool Sign-in Through a Third Party and Adding OIDC Identity Providers to a User Pool.

A user pool integrated with Okta allows users in your Okta app to get user pool tokens from Amazon Cognito. For more information, see Using Tokens with User Pools.

Resolution

Create an Amazon Cognito user pool with an app client and domain name

  1. Create a user pool.
    Note: During creation, the standard attribute email is selected by default. For more information, see Configuring User Pool Attributes.
  2. Create an app client in your user pool. For more information, see Add an App to Enable the Hosted Web UI.
  3. Add a domain name for your user pool.

Sign up for an Okta developer account

Note: If you already have an Okta developer account, sign in.

  1. On the Okta Developer signup webpage, enter your personal information, and then choose GET STARTED. The Okta Developer Team sends a verification email to the email address that you provided.
  2. In the verification email, find the sign-in information for your account. Choose ACTIVATE MY ACCOUNT, sign in, and finish creating your account.

Create an Okta app

  1. Open the Okta Developer Console. For more information about the console, see The Okta Developer Console: All New, All You on the Okta Developer Blog.
  2. In the top left corner, pause on Developer Console, and then choose Classic UI. This opens the Admin Console. For more information, see Administrator Console on the Okta Organizations page of the Okta Developer website.
  3. Under Shortcuts, choose Add Applications. Or, choose Applications, and then choose Add Application.
  4. On the Add Application page, choose Create New App.
  5. In the Create a New Application Integration dialog, confirm that Platform is set to Web.
  6. For Sign on method, choose OpenID Connect.
  7. Choose Create.

Configure settings for your Okta app

  1. On the Create OpenID Connect Integration page, under GENERAL SETTINGS, enter a name for your app. For example, TestApp.
  2. (Optional) Upload a logo and choose the visibility settings for your app.
  3. Under CONFIGURE OPENID CONNECT, for Login redirect URIs, enter https://myUserPoolDomain/oauth2/idpresponse. This is where Okta sends the authentication response and ID token.
    Note: Replace myUserPoolDomain with your Amazon Cognito user pool domain. Find the domain in the Amazon Cognito console on the Domain name page for your user pool.
  4. Choose Save. You're redirected to the General tab for your Okta app.
  5. Under General Settings, for Allowed grant types, confirm that the Authorization Code check box is selected. Your user pool uses this flow to communicate with Okta OIDC for federated user sign-in.
  6. Under Client Credentials, find the Client ID and Client secret, and note them for later. You'll need these when configuring Okta in your Amazon Cognito user pool. For more information, see the Find your application credentials guide on the Okta Developer website.
  7. Choose Sign On.
  8. On the Sign On tab, under OpenID Connect ID Token, note the Issuer URL. You'll also need this later when configuring Okta in your user pool.

Add an OIDC IdP in your user pool

  1. In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  2. In the left navigation pane, under Federation, choose Identity providers.
  3. Choose OpenID Connect.
  4. Do the following:
    For Provider name, enter a name for the IdP. This name appears in the Amazon Cognito hosted web UI.
    Note: You can't change this field after creating the provider. If you plan to include this field in your app or use the Amazon Cognito hosted web UI, use a name that you're comfortable with your app's users seeing.
    For Client ID, paste the Client ID that you noted earlier from Okta.
    For Client secret (optional), paste the Client secret that you noted earlier from Okta.
    For Attributes request method, leave the setting as GET.
    For Authorize scope, enter the OIDC scope values that you want to authorize, separated by spaces. For more information, see Scope Values in OpenID Connect Basic Client Implementer's Guide 1.0 on the OpenID website.
    Important: The openid scope is required for OIDC IdPs, and you can add other scopes according to your user pool configuration. For example, if you kept email as a required attribute when creating your user pool, enter email openid to include both scopes. You can map the email attribute to your user pool later in this setup.
    For Issuer, paste the Issuer URL that you copied earlier from Okta.
    For Identifiers (optional), you can optionally enter a custom string to use later in the endpoint URL in place of your OIDC IdP's name.
  5. Choose Run discovery to fetch the OIDC configuration endpoints for Okta.
  6. Choose Create provider.

For more information, see Add an OIDC IdP to Your User Pool.

Change app client settings for your user pool

  1. In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  2. In the left navigation pane, under App integration, choose App client settings.
  3. On the app client page, do the following:
    Under Enabled Identity Providers, select the OIDC provider and Cognito User Pool check boxes.
    For Callback URL(s), enter a URL where you want your users to be redirected after logging in. For testing, you can enter any valid URL, such as https://example.com/.
    For Sign out URL(s), enter a URL where you want your users to be redirected after logging out. For testing, you can enter any valid URL, such as https://example.com/.
    Under Allowed OAuth Flows, select the flows that correspond to the grant types that you chose earlier for your Okta app.
    Note: The allowed OAuth flows you enable determine which values (code or token) you can use for the response_type parameter in your endpoint URL.
    Under Allowed OAuth Scopes, select at least the email and openid check boxes.
  4. Choose Save changes.

For more information, see App Client Settings Overview.

Map the email attribute to a user pool attribute

If you authorized the email OIDC scope value earlier, map it to a user pool attribute.

  1. In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  2. In the left navigation pane, under Federation, choose Attribute mapping.
  3. On the attribute mapping page, choose the OIDC tab.
  4. If you have more than one OIDC provider in your user pool, choose your new provider from the dropdown list.
  5. Confirm that the OIDC attribute sub is mapped to the user pool attribute Username.
  6. Choose Add OIDC attribute, and then do the following:
    For OIDC attribute, enter email.
    For User pool attribute, choose Email.

For more information, see Specifying Identity Provider Attribute Mappings for Your User Pool.

Log in to test your setup

Authenticate with Okta using the Amazon Cognito hosted web UI. After you log in successfully, you're redirected to your app client's callback URL. The authorization code or user pool tokens appear in the URL in your web browser's address bar.

For more information, see Using the Amazon Cognito Hosted UI for Sign-Up and Sign-In.