Microsoft Entra External ID OIDC integration guide

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:

1

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

2

The user selects the Sign in with ID.me option

3

Entra External ID redirects the user to ID.me

4

The user completes authentication and identity verification at ID.me

5

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

6

Entra External ID exchanges the code for tokens

7

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

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

1

Navigate to the Microsoft Entra admin center

2

Go to App registrations > New registration

3

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

4

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

5

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

6

Select Register

Generate a client secret

1

In your application’s menu, select Certificates & secrets

2

Select New client secret

3

Enter a description and select an expiration duration

4

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

1

Navigate to External Identities > View all Identity Providers

2

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

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

3

Select Next: Claims mapping

4

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

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.

5

Select Next: Review, then select Create

Configure a user flow

1

Navigate to External Identities > User flows

2

Select New user flow

3

Enter a Name for the flow

4

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

5

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.

6

Select Create

7

Select the newly created user flow to open its properties

8

Select Applications, then select Add Application

9

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

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

1

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

2

Select your user flow

3

Select Run user flow at the top of the screen

4

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

5

Select Run user flow in the lower right

6

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

7

Authenticate using your ID.me sandbox credentials

8

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:

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

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

If you are using 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.