> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/guides/iam-platforms/aws/cognito/oidc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# AWS Cognito OIDC integration guide

> Configure AWS Cognito to use ID.me as an OpenID Connect identity provider for federated authentication.

## 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.](/_fern-img/872062f08cea0f7e28925e30ffa6ef863d83e2b246ab860c10417f9f8a306cda.webp)

## 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](/guides/oidc/overview) 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/`

> **Note**
>
> 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

Log in to the AWS Console, search for **Cognito**, and select it

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)                                                                               |

> **Note**
>
> 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.](/_fern-img/4c170931de7a2e8066c675dc95dd0fe1a2bfb97a437394c48c0175331175f0d9.webp)

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`

> **Info**
>
> 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`**

```text 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
```

## 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.

> Configure AWS Cognito to use ID.me as an OpenID Connect identity provider.