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

Short description

Okta SAML IdP integration with Amazon Cognito requires configuration on both platforms. First, you create and configure a SAML app integration in Okta. Then, you add Okta as an IdP in your Amazon Cognito user pool and configure your app client settings to allow Okta authentication. After setup, it's a best practice to test the authentication flow to confirm that users receive tokens from Amazon Cognito after they sign in through Okta.

Resolution

Before you configure Okta as a SAML IdP, take the following actions:

• Create an Amazon Cognito user pool and app client.
• Configure a domain name for your user pool.

(Optional) Sign up for an Okta developer account

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

Complete the following steps:

1. Open the Okta Developer signup page on the Okta Developer website.
2. Enter the required information, and then choose Sign up. Okta sends a verification email to the email address that you provide.
3. From the verification email, find the sign-in information for your account.
4. Choose Activate account, and then sign in to complete account creation.

Create a SAML app in Okta

Complete the following steps:

1. Open the Okta Developer console.
2. In the navigation pane, expand Applications, and then choose Applications.
3. Choose Create app integration.
4. On the Create a new app integration menu, for Sign-in method, choose SAML 2.0.
5. Choose Next.

Configure SAML integration for your Okta app

Complete the following steps:

1. On the Create SAML Integration page, under General Settings, enter a name for your app.
2. (Optional) Upload a logo and choose visibility settings for your app.
3. Choose Next.
4. Under SAML Settings, for Single sign on URL, enter https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse.
   Note: Replace yourDomainPrefix and region with your user pool's values. To find find these values, open the Amazon Cognito console, and then choose Domain from the Branding section.
5. For Audience URI (SP Entity ID), enter urn:amazon:cognito:sp:yourUserPoolId.
   Note: Replace yourUserPoolId with your user pool ID. To find the user pool ID, check the Overview section on the Amazon Cognito console.
6. Under Attribute Statements (optional), add a statement and use 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.
   For other settings on the page, use the default values or adjust them based on your requirements.
7. Choose Next.
8. When prompted, choose a feedback response about the app setup experience.
   Note: This is part of Okta's standard application creation process to gather user experience feedback.
9. Choose Finish.

Assign a user to your Okta application

Complete the following steps:

1. On the Assignments tab for your Okta app, for Assign, choose Assign to People.
2. Choose Assign next to the user that you want to assign.
   Note: If this is a new account, then you can only choose yourself as the user.
3. (Optional) For User Name, enter a custom username. Okta uses the user's email address as the username if you don't specify one.
4. Choose Save and Go Back to complete the user assignment.
5. Choose Done.

Get the IdP metadata for your Okta application

On the Sign On tab for your Okta app, under Metadata details, copy the Metadata URL.

Configure Okta as a SAML IdP in your user pool

Complete the following steps:

1. Open the Amazon Cognito console.
2. Choose your user pool.
3. In the navigation pane, under Authentication, choose Social and external providers.
4. Choose Add identity provider, and then select SAML.
5. Under Register your app with your SAML provider, for Provider name, enter Okta.
6. (Optional) Add SAML identifiers to route sign-in and sign-out requests to Okta.
7. (Optional) Activate single logout to sign users out of Okta when they sign out of your user pool.
8. Under Metadata document source, choose Enter metadata document endpoint URL, and then paste the Metadata URL that you copied from the Okta Sign On tab.
9. Under Map attributes between your SAML provider and your user pool, specify email for the SAML attribute.
10. Choose Add identity provider.

For more information, see Adding and managing SAML identity providers in a user pool.

Change app client settings for your user pool

Complete the following steps:

1. From the Amazon Cognito console, under App clients, choose your user pool.
2. In the navigation pane, under Applications, choose App clients.
3. On the app client page, navigate to the Login pages section. Then, under Managed login pages configuration, choose Edit.
4. From the Identity Providers dropdown list, select the checkbox for both Okta and Cognito User Pool.
   For Callback URL(s), specify the destination URL for your users after successful log in.
   For Sign out URL(s), specify the destination URL for your users after log out.
   Note: If you want to test the integration, then use a placeholder URL such as https://www.example.com/. You can later update this placeholder with your application's URL.
   Under Allowed OAuth Flows, choose the Implicit grant checkbox.
   Under Allowed OAuth Scopes, choose the email and openid checkbox.
5. Choose Save changes.

For more information, see App client terms.

Access the login page to test the SAML authentication flow

You can access the login page through the Amazon Cognito console or create a login endpoint URL.

1. From the Amazon Cognito console, under App clients, choose your user pool.
2. Choose the Login pages tab, and then choose View login page.
   -or-
   Create the login endpoint URL. To create the login endpoint, use the following naming pattern:
   https://yourDomainPrefix.auth.region.amazoncognito.com/login?response_type=token&client_id=yourClientId&redirect_uri=redirectUrl
   Note: Replace yourDomainPrefix and region with your user pool's values. To find these values in the Amazon Cognito console, choose the Domain name page.
3. On the login endpoint webpage, choose Okta.
   Note: If the system redirects you to your app client's callback URL, then you're already logged in to your Okta account. Proceed to step 5.
4. On the Okta Sign In page, enter the username and password for the user that you assigned to your app.
5. Choose Sign in.
6. Look for the user pool tokens in your browser's address bar.

(Optional) Bypass the Amazon Cognito hosted UI

To bypass the Amazon Cognito hosted web UI and send users directly to Okta for sign-in, use the following /oauth2/authorize endpoint URL:

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

Note: Replace yourDomainPrefix, region, samlProviderName, yourClientId, redirectUrl, and allowedOauthScopes with your values. To find yourDomainPrefix and region, from the Amazon Cognito console, choose Domain from the Branding section. For yourClientId and redirectUrl, choose the App client settings page in the Amazon Cognito console.

(Optional) If you added a SAML identifier, then replace the placeholder identity_provider=samlProviderName with idp_identifier=idpIdentifier. Replace idpIdentifier with your custom identifier string.

Related information

SAML session initiation in Amazon Cognito user pools

How do I set up a third-party SAML identity provider with an Amazon Cognito user pool?

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

User pool sign-in with third party identity providers