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

# Microsoft Entra External ID OIDC integration guide

> Configure Microsoft Entra External ID to use ID.me as an OpenID Connect identity provider for federated authentication.

## Overview

This guide provides steps to integrate Microsoft Entra External ID (EID) with ID.me using the OpenID Connect (OIDC) protocol.

**Intended audience** \
Developers and IAM administrators responsible for configuring federation between Microsoft Entra External ID and ID.me.

**What you will build** \
A federated authentication flow where Microsoft Entra External ID delegates user authentication to ID.me.

**Result** \
A federated OIDC authentication flow where Entra EID 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, Microsoft Entra External ID, and ID.me:

The user navigates to the application and is redirected to the Microsoft Entra External ID hosted landing page

The user selects the **Sign in with ID.me** option

Entra External ID redirects the user to ID.me

The user completes authentication and identity verification at ID.me

ID.me redirects the user back to Microsoft Entra External ID with an authorization code

Entra External ID exchanges the code for tokens

Entra External ID redirects the user to the target application (for example, `jwt.ms`) with the final ID token

## Prerequisites

* Access to a Microsoft Azure account and tenant
* A Microsoft Entra External ID directory created within the tenant
* Administrator permissions to register applications and configure external identity providers
* 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, using `https://jwt.ms` as a relying party)

## 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 Microsoft Entra External ID

### Register your application

Navigate to the [Microsoft Entra admin center](https://entra.microsoft.com)

Go to **App registrations** > **New registration**

Enter a **Name** for your application (e.g., `Test App`)

For **Supported account types**, select **Single tenant only - \<your tenant name>**

Under **Redirect URI**, select **Web** and enter the URL where Entra should redirect users after authentication (e.g., `https://jwt.ms` in this example)

Select **Register**

### Generate a client secret

In your application's menu, select **Certificates & secrets**

Select **New client secret**

Enter a description and select an expiration duration

Select **Add**

> **Important**
>
> Copy the client secret immediately. You will not be able to see it again.

### Configure ID.me as an OpenID Connect identity provider

Navigate to **External Identities** > **View all Identity Providers**

Select the **Custom** tab, then select **Add new** > **OpenID Connect**

> **Error**
>
> Do not use the standard ID.me well-known endpoint. Using the wrong endpoint can prevent the "Sign in with ID.me" button from appearing on the Entra EID hosted login page. Please use the **Entra-specific** ID.me well-known endpoint configuration URL provided below.

| Field                 | Value                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Display name          | `ID.me Sandbox` (or your preferred label for the login button)                                                             |
| Well-known endpoint   | `https://api.idmelabs.com/oidc/entra/.well-known/openid-configuration`                                                     |
| Issuer URI            | `https://api.idmelabs.com/oidc`                                                                                            |
| Client ID             | The Client ID provided by your ID.me Solution Consultant.                                                                  |
| Client authentication | `client_secret`                                                                                                            |
| Client secret         | The Client Secret provided by your ID.me Solution Consultant.                                                              |
| Scope                 | openid \<policy_handle> (Replace \<policy_handle> with your specific ID.me policy handle, e.g., nist_aal2_ial2 or teacher) |
| Response type         | `code`                                                                                                                     |

Select **Next: Claims mapping**

Map the attributes returned by ID.me to the corresponding user attributes in Entra

> **Info**
>
> You must enter the exact attribute names from the ID.me payload. Get these from your ID.me Solution Consultant. This example only lists a limited set for simplicity.

Select **Next: Review**, then select **Create**

### Configure a user flow

Navigate to **External Identities** > **User flows**

Select **New user flow**

Enter a **Name** for the flow

Under **Identity providers**, select the ID.me provider you created (e.g., **ID.me Sandbox**)

Under **User attributes**, select the attributes you want Entra to populate and emit in the ID token. For federated providers like ID.me, these attributes must first be returned by ID.me (based on scope) and properly mapped in the identity provider configuration before they can be issued to the target application.

Select **Create**

Select the newly created user flow to open its properties

Select **Applications**, then select **Add Application**

Select the application you registered earlier (e.g., `Test App`) to associate it with this user flow

## 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 Entra External ID redirect URIs typically follow this pattern: \
`https://<Entra tenant name>.ciamlogin.com/<Entra tenant GUID>/federation/oauth2`

> **Info**
>
> Microsoft Entra may normalize domains differently, so providing the primary domain and this variant may be required: \
> `https://<Entra tenant name>.ciamlogin.com/<Entra tenant GUID>.onmicrosoft.com/federation/oauth2`

**Policy handle name**

Confirm the ID.me policy handle (e.g., `nist_aal2_ial2` or `teacher`). This value is included in the OIDC scope parameter along with `openid` and is forwarded by Entra to ID.me.

## Test the integration

Two options are available when testing the integration:

### Option 1: Run user flow via Entra

In the Microsoft Entra admin center, go to **External Identities** > **User flows**

Select your user flow

Select **Run user flow** at the top of the screen

Ensure the correct Application and Reply URL are selected, and change Response type to `id_token`

Select **Run user flow** in the lower right

A browser will open. On the sign-in page, select the **Sign in with ID.me Sandbox** button.

Authenticate using your ID.me sandbox credentials

Upon success, you should be redirected to the reply URL (e.g., `https://jwt.ms`) displaying your decoded token

### Option 2: Manually construct URL

Copy the authorization request URL from the lower-right corner of the page, paste it in a text editor, edit the scope parameter as needed, and paste the modified URL into your browser.

Update the scope to:

**`Scope`**

```html Scope
scope=openid%20profile
```

Adding `profile` ensures first name and last name claims are included in the ID token sent to the application from Entra EID.

> **Note**
>
> These OIDC scopes are separate from the ID.me policy handle values configured in the Entra External ID custom OIDC settings

**`Example`**

```html Example
https://<yourdomain>.ciamlogin.com/<yourdomain>.onmicrosoft.com/oauth2/v2.0/authorize
?client_id=<Your Entra App Client ID>
&p=<Your User Flow Name>
&redirect_uri=<Your URL-encoded Redirect URI>
&response_type=id_token
&scope=openid%20profile
&nonce=defaultNonce
```

If you are using [https://jwt.ms](https://jwt.ms) as your target app, the result will look similar to the following:

## Troubleshooting

**AADSTS900144 Error**

If you receive this error after returning from ID.me, check that the policy handle in ID.me matches the scope value in the Entra Identity Provider configuration (e.g. ID.me could have `nist_aal2_ial2` and Entra should therefore have `openid nist_aal2_ial2`).

**Sign in with ID.me button is not appearing**

Ensure you are using the Entra-specific well-known endpoint (`.../entra/.well-known/openid-configuration`). The standard ID.me endpoint will not work for Entra integrations.