Set up Okta as a SAML identity provider in an Amazon Cognito user pool

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

Do you want to use Okta as a Security Assertion Markup Language 2.0 (SAML 2.0) 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 SAML 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.
    Note: When adding an app client, clear the Generate client secret check box. In certain authorization flows, such as the authorization code grant flow and token refresh flow, authorization servers use an app client secret to authorize a client to make requests on behalf of a user. For the implicit grant flow used in this setup, an app client secret isn’t required.
  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 a SAML app in Okta

  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.
    Important: You must be in the Admin Console (Classic UI) to create a SAML app.
  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 SAML 2.0.
  7. Choose Create.

For more information, see Add general app information in the Set up a SAML application in Okta guide on the Okta Developer website.

Configure SAML integration for your Okta app

  1. On the Create SAML Integration page, under General Settings, enter a name for your app.
  2. (Optional) Upload a logo and choose the visibility settings for your app.
  3. Choose Next.
  4. Under GENERAL, for Single sign on URL, enter https://yourDomainPrefix.auth.region.amazoncognito.com/saml2/idpresponse.
    Note: Replace yourDomainPrefix and region with the values for your user pool. Find these values in the Amazon Cognito console on the Domain name page for your user pool.
  5. For Audience URI (SP Entity ID), enter urn:amazon:cognito:sp:yourUserPoolId.
    Note: Replace yourUserPoolId with your Amazon Cognito user pool ID. Find it in the Amazon Cognito console on the General settings page for your user pool.
  6. Under ATTRIBUTE STATEMENTS (OPTIONAL), add a statement with the following information:
    For Name, enter the SAML attribute name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
    For Value, enter user.email.
  7. For all other settings on the page, leave them as their default values or set them according to your preferences.
  8. Choose Next.
  9. Choose a feedback response for Okta Support.
  10. Choose Finish.

For more information, see Configure SAML in Okta in the Set up a SAML application in Okta guide on the Okta Developer website.

Assign a user to your Okta application

  1. On the Assignments tab for your Okta app, for Assign, choose Assign to People.
  2. Next to the user that you want to assign, choose Assign.
    Note: If this is a new account, the only option available is to choose yourself (the admin) as the user.
  3. (Optional) For User Name, enter a user name, or leave it as the user’s email address, if you want.
  4. Choose Save and Go Back. Your user is assigned.
  5. Choose Done.

For more information, see Assign users to the app in the Set up a SAML application in Okta guide on the Okta Developer website.

Get the IdP metadata for your Okta application

On the Sign On tab for your Okta app, find the Identity Provider metadata hyperlink. Right-click the hyperlink, and then copy the URL.

For more information, see Configure SAML in your app in the Set up a SAML application in Okta guide on the Okta Developer website.

Configure Okta as a SAML 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 SAML.
  4. Under Metadata document, paste the Identity Provider metadata URL that you copied.
  5. For Provider name, enter Okta. For more information, see Choosing SAML Identity Provider Names.
  6. (Optional) Enter any SAML identifiers (Identifiers (Optional)) and enable sign-out from the IdP (Okta) when your users sign out from your user pool (Enable IdP sign out flow).
  7. Choose Create provider.

For more information, see Creating and Managing a SAML Identity Provider for a User Pool (AWS Management Console).

Map email address from IdP attribute to 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 SAML tab.
  4. Choose Add SAML attribute.
  5. For SAML attribute, enter the SAML attribute name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
  6. For User pool attribute, choose Email from the list.

For more information, see Specifying Identity Provider Attribute Mappings for 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 Okta and Cognito User Pool check boxes.
    For Callback URL(s), enter a URL where you want your users to be redirected after they log in. For testing, you can enter any valid URL, such as https://www.example.com/.
    For Sign out URL(s), enter a URL where you want your users to be redirected after they log out. For testing, you can enter any valid URL, such as https://www.example.com/.
    Under Allowed OAuth Flows, be sure to select at least the Implicit grant check box.
    Under Allowed OAuth Scopes, be sure to select at least the email and openid check boxes.
  4. Choose Save changes.

For more information, see App Client Settings Overview.

Construct the endpoint URL

Using values from your user pool, construct this login endpoint URL:

https://yourDomainPrefix.auth.region.amazoncognito.com/login?response_type=token&client_id=yourClientId&redirect_uri=redirectUrl

Be sure to do the following:

  • Replace yourDomainPrefix and region with the values for your user pool. Find these values in the Amazon Cognito console on the Domain name page for your user pool.
  • Replace yourClientId with your app client’s ID, and replace redirectUrl with your app client’s callback URL. Find these in the Amazon Cognito console on the App client settings page for your user pool.

For more information, see How do I configure the hosted web UI for Amazon Cognito? and LOGIN Endpoint.

Test the endpoint URL

  1. Enter the constructed login endpoint URL in your web browser.
  2. On your login endpoint webpage, choose Okta.
    Note: If you’re redirected to your app client’s callback URL, you’re already logged in to your Okta account in your browser. The user pool tokens appear in the URL in your web browser’s address bar.
  3. On the Okta Sign In page, enter the username and password for the user that you assigned to your app.
  4. Choose Sign in.

After logging in, you’re redirected to your app client’s callback URL. The user pool tokens appear in the URL in your web browser’s address bar.

(Optional) Skip the Amazon Cognito hosted UI

If you want your users to skip the Amazon Cognito hosted web UI when signing in to your app, use this as the endpoint URL instead:

https://yourDomainPrefix.auth.region.amazoncognito.com/oauth2/authorize?response_type=token&identity_provider=samlProviderName&client_id=yourClientId&redirect_uri=redirectUrl&scope=allowedOauthScopes

Be sure to do the following:

  • Replace yourDomainPrefix and region with the values for your user pool. Find these values in the Amazon Cognito console on the Domain name page for your user pool.
  • Replace samlProviderName with the name of the SAML provider in your user pool (Okta).
  • (Optional) If you added an identifier for your SAML IdP earlier in the Identifiers (optional) field, you can replace identity_provider=samlProviderName with idp_identifier=idpIdentifier, replacing idpIdentifier with your custom identifier string.
  • Replace yourClientId with your app client’s ID, and replace redirectUrl with your app client’s callback URL. Find them in the Amazon Cognito console on the App client settings page for your user pool.
  • Replace allowedOauthScopes with the specific scopes that you want your Amazon Cognito app client to request. For example, scope=email+openid.

For more information, see How do I configure the hosted web UI for Amazon Cognito? and AUTHORIZATION Endpoint.