Skip to main content

Set Up AWS Cognito for Authentication

Users in your AWS Cognito tenant can access applications registered in SecureAuth. In this setup, AWS Cognito acts as an external Identity Provider for SecureAuth, following the Bring Your Own Identity (BYOID) model. Follow these steps to configure the integration.

About Cognito as IDP

Cognito is natively supported by SecureAuth as an OIDC Identity Provider, which means that it has a dedicated connection template in SecureAuth for your convenience. Cognito applications implement the OIDC protocol, providing the proof of user authentication to SecureAuth within an ID Token and Access Token.

The client authorization flow with SecureAuth connected to Cognito looks as follows:

About_Cognito_as_IDP.svg

  1. Client app requests the authorization code from SecureAuth.

  2. SecureAuth requests the authorization code from Cognito IDP.

  3. Cognito authenticates the user and asks for consent to share data with SecureAuth.

  4. Cognito issues the code to SecureAuth after user's authentication.

  5. SecureAuth requests tokens from Cognito using the provided code.

  6. Cognito issues the tokens to SecureAuth.

  7. Optionally, SecureAuth uses the token to pull additional user information - only when the Get user info option is selected in the connector. In case of Cognito this shouldn't typically be required, since the user attributes are already exposed in the ID and Access Token.

  8. SecureAuth asks for user consent to share data with the client app, unless the client app is marked as trusted or the requested scopes were already granted for this app.

  9. SecureAuth issues the authorization code to the client app.

  10. Client app requests the tokens from SecureAuth.

  11. SecureAuth issues the tokens to the client app. SecureAuth tokens are minted based on the incoming Cognito tokens with claims mapped to SecureAuth's authentication context.

The following steps in the flow are optional:

  • SecureAuth only pulls user information if this option is explicitly enabled in the Cognito connector configuration, as explained later in this document.

  • SecureAuth only asks for consent if the client application is not marked as trusted and requests scopes which were not granted previously (or scopes for which the user's consent has been withdrawn).

Cognito and SAML

Cognito applications can also use the SAML protocol, but this integration is not natively supported by SecureAuth yet. If necessary, you can use the generic SAML connector to bind Cognito apps via SAML.

Prerequisites

  • AWS account with access to Amazon Cognito console and entitled to manage user pools

  • Cognito User Pool is created

  • Client application is registered in Cognito User Pool

    • Leave out the Callback URL(s) for now. You'll fill it in after getting the URL from the SecureAuth's connector form

    • In the Enabled Identity Providers section, enable Cognito User Pool.

    • In the OAuth 2.0 section

      • For Allowed OAuth Flows, select authorization code grant.

      • For Allowed OAuth Scopes, select email, profile, and openid.

    • If you're using custom attributes with your Cognito app, make sure to enable read permissions for them or SecureAuth won't be able to request these attributes. Cognito custom attributes are exposed via the ID token.

Connect Cognito IDP

Basic Configuration

  1. In your workspace, go to Authentication > Providers > Create Connection.

  2. Select the Cognito template and click Next.

  3. Add the redirect URL from SecureAuth as Callback URL in Cognito.

  4. In the Cognito form in SecureAuth, enter the data of the client application integrated with your Cognito user pool.

    Parameter

    Description

    Name

    Name for your SecureAuth's Cognito connection. This name allows users to identify the IDP they need to authenticate with.

    Pool ID

    Pool ID of your Cognito user pool

    Region

    AWS region where your Cognito user pool is created

    Client ID

    Client ID of the application registered with Cognito.

    Client secret

    Secret of the application registered with Cognito

    Redirect URL

    URL serving as a callback URL for your Cognito client

  5. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you wish to store the user's authentication context locally. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with SecureAuth.

  6. Select Save.

    Result: Your new IDP connection is created. Users can now authenticate via the OIDC-compliant IDP.

Configure Advanced Settings

  1. From the Identities > YOUR_IDENTITY > Configuration page, select Advanced settings at the bottom.

  2. In the Authentication Method Reference, you can select an authentication method to be written into the amr object returned by the IDP. The amr object is created if it doesn't exist. If it exists, its values are replaced with the selected item.

  3. Optionally, enable the Get user info option.

    Note

    If you enable the Get user info option, the connector calls the Cognito userinfo endpoint to retrieve additional user attributes. In case of Cognito it doesn't typically result in any additional data being returned.

  4. Select Save.

Add custom OIDC IDP attributes

If your IDP returns custom claims outside of the standard OIDC scope, make sure to add them to the IDP connector so that they can be recognized and mapped to the authentication context. Some IDPs (for example Cognito) may require you to set custom attribute permissions first.

  1. Go to Authentication > Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of OIDC attributes returned by this IDP appears.

  3. Select Add attribute.

  4. In Source, select the data source for the custom attribute

    Source

    Description

    Access token

    Get data from the access token received from the IDP

    ID token

    Get data from the ID token received from the IDP

    User info

    Get data data returned by the OIDC user info endpoint (note that this must be explicitly enabled on the IDP connector)

  5. Fill in the rest of the form.

    Option

    Description

    Claim name

    Name of your custom attribute matching the incoming IDP claim

    Display name

    User-friendly name for the custom attribute

    Data type

    Data type matching that of the incoming IDP claim

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  6. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP Attributes to Authentication Context

If you've added custom attributes for an IDP, you need to make sure they are mapped to the SecureAuth authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Authentication > Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read the Managing Authentication Context.

  4. Optionally, you can enrich authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Connect Extensions to your IDP

  1. Go to Authentication > Providers > YOUR_IDP > Extensions.

  2. Assign a Post Authentication script to the IDP. This script will be executed upon user authentication via this IDP.

  3. Connect your application to the IDP in the Post Authentication application field. Users will be redirected to this application upon authentication via this IDP.

    Note

    Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag.

Test Cognito IDP

Prerequisite

  • Your provider is configured as a user-authentication method by your administrator.

  • Workspace is available.

Test

  1. Open the user portal.

  2. Select LOGIN TO DEMO APP.

  3. Select your configured IDP and, next, authenticate in IDP.

    Result: SecureAuth displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from IDP is delivered through the access token and the ID token generated by SecureAuth.

    token_issued.png

Note

For information on granting and managing SecureAuth consents, see Consents.

In this section: