How To Integrate Okta In Amazon Cognito User Pool

When you are building enterprise software, you will often encounter requests to integrate your system with the identity management systems of the enterprise. In this article, assuming that your software uses AWS Cognito as the identity provider, I have indicated how to integrate with Okta as the identity provider. Amazon Cognito user pool allows users to sign-in through an external identity provider (federation), such as Okta. A user pool integrated with Okta allows users in your Okta app to get user pool tokens from Amazon Cognito and authenticate apps that use cognito.

Prerequisites

  • Cognito user pool created in the aws account
  • Okta developer account

Steps

Create an app client in your user pool
  • When adding an app client, clear the “Generate client secret check box”.
  • Select the required auth flows – Select at least ALLOW_USER_SRP_AUTH and ALLOW_REFRESH_TOKEN_AUTH
img 1 create app client

Note:  We are using “Authorization code grant” authentication flow which does not require client secrets.

Create your cognito user pool domain

  • Under App Integration tab in user pool console side menu, choose Domain name
  • Enter your choice of unique domain prefix which is used to build cognito login url for your SAML app

Create a SAML app in Okta

  • Sign in to Okta with admin access credentials and click on “Admin” button on top right corner
  • On the admin menu choose Applications, and then choose Add Application.
  • On the Add Application page, choose Create New App.
  • In the Create a New Application Integration dialog, confirm that Platform is set to Web.
  • For Sign on method, choose SAML 2.0.
  • Choose Create, this will open a General Settings page for SAML app.
    • Enter a name for your app.
    • Upload a logo and choose the visibility settings for your app.(Optional)
    • Choose Next.
img 2 creating saml app
  • 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.
  • 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.
img 3 configuring saml app

Under ATTRIBUTE STATEMENTS (OPTIONAL- specifies which user attributes you want to export to cognito), add a statement with the following information:
For Name, enter the SAML attribute name (attribute name by which you want to user attributes to be passed to cognito in SAML response).

img 4 attribute statements
  • Eg: If you want to pass user email in SAML response and you want to call it ‘Email Id’ enter ‘Email id’ in Name field and enter ‘user.email’ in Value field.
  • For all other settings on the page, leave them as their default values or set them according to your preferences.
  • Choose Next.
  • Choose a feedback response for Okta Support.
  • Choose Finish.

Assign an user to your Okta application

  • On the Assignments tab for your Okta app, for Assign, choose Assign to People.
  • 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.
  • (Optional) For User Name, enter a user name, or leave it as the user’s email address, if you want.
  • Choose Save and Go Back. Your user is assigned.
  • Choose Done.

Get the IdP metadata for your Okta application

  • On Okta developer console, navigate to Applications tab and select your application.
  • On the Sign On tab, find the Identity Provider metadata hyperlink (Look for text ‘Identity Provider metadata is available if this application supports dynamic configuration.’). Right-click the hyperlink (Identity Provider metadata), and then copy the URL.

Configure Okta as a SAML IdP in your user pool

  • In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  • In the left navigation pane, under Federation, choose Identity providers.
  • Choose SAML.
  • Under the Metadata document, paste the Identity Provider metadata URL that you copied.
  • For Provider name, enter Okta.
  • (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).
  • Choose Create provider.
img 5 cognito create saml

Map SAML attributes to user pool attributes

  • In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  • In the left navigation pane, under Federation, choose Attribute mapping.
  • On the attribute mapping page, choose the SAML tab.
  • Choose Add SAML attribute.
  • For SAML attribute, enter the SAML attribute name (attribute name which you have mentioned in ATTRIBUTE STATEMENTS while creating SAML app in Okta.
img 6 cognito attribute mapping

Eg: We had specified ‘Email Id’ in the example above so mention ‘Email Id’ under SAML attribute and select Email under User pool attribute, continue and map all other attributes if you had mentioned any other in ATTRIBUTE STATEMENTS and Choose Save changes.

Note:Make sure all mapped attributes in cognito are readable and writable, you can set attribute permissions in General settings->App clients->Set read and write permissions.

Change app client settings for your user pool

  • In the Amazon Cognito console, choose Manage user pools, and then choose your user pool.
  • In the left navigation pane, under App integration, choose App client settings.
  • On the app client page, do the following:
    Under Enabled Identity Providers, select the Okta and Cognito User Pool check boxes.
    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.techpearl.com/.
    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.techpearl.com/.
    Under Allowed OAuth Flows, be sure to select Authorization code grant check box.
    Under Allowed OAuth Scopes, be sure to select the email and profile check boxes.
  • Choose Save changes
img 7 cogntio app client settings

Construct the endpoint URL

  • Using values from your user pool, construct this login endpoint URL:
    https://yourDomainPrefix.auth.region.amazoncognito.com/login?response_type=code&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.

Test the endpoint URL

  • Enter the constructed login endpoint URL in your web browser.
  • On your login endpoint webpage, choose Okta.
img 8 test endpoint
  • 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.
  • On the Okta Sign In page, enter the username and password for the user that you assigned to your app.
img 9 okta login
  • Choose Sign in.
    After logging in, you’re redirected to your app client’s callback URL. The authorization code appears in the URL in your web browser’s address bar.

Complete authentication by getting tokens from cognito

    • Your application can then extract the authorization code from the query parameters and exchange it for user pool tokens. The exchange occurs by submitting a POST request to
      https://yourDomainPrefix.auth.region.amazoncognito.com/oauth2/token with the following parameters:
      • grant_type – Set to “authorization_code” for this grant.
      • code – The authorization code that’s vended to the user.
      • client_id – yourClientId.
      • redirect_uri – redirectUrl.
  • The JSON returned in the resulting response has the following keys:
  • id_token – A valid user pool ID token. Note that an ID token is only provided if the openid scope was requested.
  • access_token – A valid user pool access token.
  • refresh_token – A valid user pool refresh token. This can be used to retrieve new tokens by sending it through a POST request to
    https://yourDomainPrefix.auth.region.amazoncognito.com/oauth2/token, specifying the refresh_token and client_idparameters, and setting the grant_type parameter to “refresh_token“.
  • expires_in – The length of time (in seconds) that the provided ID and/or access token(s) are valid for.
  • token_type – Set to “Bearer“.

Check out OKTA integration in Swae – A product developed by Techpearl.

Companies will face many challenges during the product’s lifetime. A mature product manager will be able to handle the changes needed in the product, due to changing market trends and technologies and still be able to keep the product in track.

Read More Articles

 Contact Us Now

Talk to us to find out about our flexible engagement models.

Get In Touch With Us