AWS Cognito OIDC integration guide

Overview

This guide provides steps to integrate AWS Cognito with ID.me using the OpenID Connect (OIDC) protocol.

Intended audience
Developers and IAM administrators responsible for configuring federation between AWS Cognito and ID.me.

What you will build
A federated authentication flow where AWS Cognito delegates user authentication to ID.me.

Result
A federated OIDC authentication flow where AWS Cognito delegates authentication to ID.me.

Identity proofing behavior
Authentication behavior, identity verification settings, and returned attributes are driven by ID.me policy configurations.

Authentication flow

The following steps outline the OIDC authentication flow between the user, AWS Cognito, and ID.me:

The user navigates to the application and is redirected to the AWS Cognito hosted landing page

The user selects the ID.me option (for example, “Continue with IDmeSandbox”)

AWS Cognito redirects the user to ID.me

The user completes authentication and identity verification at ID.me

ID.me redirects the user back to AWS Cognito with an authorization code

AWS Cognito exchanges the code for tokens

AWS Cognito redirects the user to the target application (for example, localhost) with the final tokens

Screenshot of an Okta sign-in page offering two options: a "Continue with IDmeSandbox" button for federated login, or an email address field with a "Next" button for existing account login, with a "Create an account" link for new users.

Prerequisites

Access to an AWS account (sign up at https://aws.amazon.com/cognito/ if needed)
Administrator permissions to create and configure AWS Cognito User Pools
An ID.me sandbox account for testing your integration
Understanding of OIDC flows and terminology
An application to test the sign-in flow (for example, a locally-hosted app at http://localhost:8080/v1/idme/callback)

Environments

ID.me provides two environments:

Sandbox

https://api.idmelabs.com/

Production

https://api.id.me/

All ID.me OIDC and SAML endpoints are derived from the base URL above. For production, replace the sandbox base URL in every ID.me endpoint you configure.

Examples

OIDC issuer (Sandbox): https://api.idmelabs.com/oidc
OIDC issuer (Production): https://api.id.me/oidc
SAML metadata URL (Sandbox): https://api.idmelabs.com/saml/metadata
SAML metadata URL (Production): https://api.id.me/saml/metadata

Configure AWS Cognito

Create a User Pool

Select Create user pool and choose Traditional Web Application

Enter a name for your application (e.g., FSA Test App)

Under Required attributes for sign-up, select email, given_name, and family_name

In Return URL, enter your destination app’s callback URL (e.g., http://localhost:8080/v1/idme/callback)

Select Create user directory

Configure ID.me as an OpenID Connect identity provider

Navigate to your User Pool in the AWS Console

In the left-hand column, select Social and external providers > Add identity provider > OpenID Connect (OIDC)

Configure the provider with the following settings:

Field	Value
Provider Name	`IDmeSandbox` (This label appears on the login button)
Client ID	The Client ID provided by your ID.me Solution Consultant
Client Secret	The Client Secret provided by your ID.me Solution Consultant
Authorized scopes	openid <policy_handle> (Replace <policy_handle> with your specific ID.me policy handle)
Attribute Request method	`GET`
Issuer URL	`https://api.idmelabs.com/oidc` (Select “Auto fill through issuer URL”)
Identifiers	(Leave blank)

Cognito automatically fetches endpoints from /.well-known/openid-configuration when you use the Auto fill option. Ensure the populated endpoints look correct.

Under Attribute mapping, map the Cognito attributes to the corresponding ID.me claims (e.g., map email to email)

Screenshot of the "Map attributes between your provider and your user pool" section in AWS Cognito, showing four mappings from OpenID Connect attributes to user pool attributes: email→email, lname→family_name, fname→given_name, and uuid→username.

Save the configuration

Configure App Client settings

Go to Applications > App clients and select your client (e.g., FSA Test App)

Under the Login pages tab, locate Allowed callback URLs and ensure your app’s callback URL is present (e.g., http://localhost:8080/v1/idme/callback)

Under Identity providers, check both Cognito user pool and your new provider (e.g., IDmeSandbox)

Under OAuth 2.0 grant types, check Authorization code grant

Under OpenID Connect scopes, select email, openid, and profile

Select Save changes

Configure ID.me

This portion of the configuration is completed by an ID.me Solution Consultant. You will need to provide the following information to complete the setup:

Redirect URIs

The AWS Cognito redirect URI typically follows this pattern:
https://\<your-cognito-domain\>.auth.\<region\>.amazoncognito.com/oauth2/idpresponse

You can find your Cognito domain by navigating to Cognito > Branding > Domain in the AWS admin panel. Be sure to append /oauth2/idpresponse to the end of the domain.

Policy handle name

Confirm the ID.me policy handle. This value is included in the Authorized scopes field in Cognito (e.g., openid <policy_handle>).

Test the integration

Option 1: Launch from Cognito Hosted UI

In your Cognito App Client settings, select the Login pages tab

Select View login page to open the Hosted UI authorization request

Select the ID.me button (e.g., “IDmeSandbox”) to initiate the flow

Option 2: Direct authorize URL

Construct the URL manually and paste it into your browser.

Example

https://<your-cognito-domain>.auth.<region>.amazoncognito.com/oauth2/authorize
?identity_provider=IDmeSandbox
&response_type=code
&client_id=<YOUR_APP_CLIENT_ID>
&redirect_uri=http://localhost:8080/v1/idme/callback
&scope=openid%20email%20profile

When successful, you will be redirected back to your app’s callback URL with a code parameter.

A webpage showing a successful "callback recieved" with the code parameter

Troubleshooting

redirect_uri_mismatch

Possible Cause: Callback URL not listed in Cognito.
Resolution: Ensure the redirect_uri in your request exactly matches the Allowed Callback URL configured in the Cognito App Client settings (e.g., http://localhost:8080/v1/idme/callback).

invalid_client

Possible Cause: Wrong Client ID or Secret in Cognito.
Resolution: Verify the Client ID and Client Secret entered in the Cognito Identity Provider settings match the credentials from your ID.me Consumer.

no such IdP

Possible Cause: Provider name mismatch.
Resolution: Confirm that the identity_provider parameter in your request (e.g., IDmeSandbox) matches the Provider Name configured in Cognito.

User attributes missing

Possible Cause: Claims not mapped.
Resolution: Revisit the Attribute mapping step in the Cognito Identity Provider configuration and ensure ID.me claims are correctly mapped to Cognito user pool attributes.