Add a Microsoft Entra ID tenant as an OpenID Connect identity provider

Applies to: External tenants (learn more)

By setting up OpenID Connect (OIDC) federation with a Microsoft Entra ID tenant, you enable users from that tenant to sign in to your applications using their existing organizational accounts. This approach uses the custom OIDC identity provider feature to federate with a Microsoft Entra ID tenant. (Learn more about authentication methods and identity providers for customers.)

Prerequisites

• An external tenant.
• A Microsoft Entra ID tenant to use as the identity provider. If you don't have one, create a new tenant.
• A registered application in the external tenant.
• A sign-up and sign-in user flow.

Register the external tenant in your Microsoft Entra ID tenant

To federate users from your Microsoft Entra ID tenant, first register the external tenant as an application in the Microsoft Entra ID tenant that acts as the identity provider.

When you register the application, use the following federation-specific settings:

1. Under Supported account types, select Accounts in this organizational directory only.

2. Under Redirect URI, select Web and add the following URIs:

   https://<tenant-subdomain>.ciamlogin.com/<tenant-ID>/federation/oauth2

   https://<tenant-subdomain>.ciamlogin.com/<tenant-subdomain>.onmicrosoft.com/federation/oauth2

   Replace <tenant-subdomain> and <tenant-ID> with the values from your external tenant. If your external tenant uses a custom domain, add the redirect URI with the custom domain as well, for example:

   https://<tenant-subdomain>.ciamlogin.com/<custom-domain>/federation/oauth2

For step-by-step guidance, see Register an application.

After the app is registered, complete the following configuration:

1. Add a client secret and record the secret value (not the secret ID). You need this value when you configure the identity provider in your external tenant.
2. Under Token configuration, add the optional claims you want the identity provider to send.
3. Under API permissions, add Microsoft Graph delegated permissions: email, openid, profile, and User.Read. Then grant admin consent for the identity provider tenant.
4. Under Overview, record the Application (client) ID and Directory (tenant) ID. You need these values to configure federation in the external tenant.

Configure the identity provider in the external tenant

After you register the external tenant in the Microsoft Entra ID tenant, add it as a custom OIDC identity provider in the external tenant. Follow the steps in Configure a new OpenID Connect identity provider in the admin center and use the following Microsoft Entra ID-specific values:

Use domain_hint

To accelerate sign-in to the Microsoft Entra ID identity provider, pass the tenant's domain name in the domain_hint parameter. For example, use domain_hint=contoso.onmicrosoft.com. Don't use the tenant ID (GUID) as the domain_hint value.

When you use domain_hint, configure the OpenID Issuer URI with the corresponding onmicrosoft.com domain. For example, for domain_hint=contoso.onmicrosoft.com, use https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0.

Enable users to sign in and sign up with the identity provider

After you configure the Microsoft Entra ID identity provider, there are multiple ways to enable users to sign in and sign up:

Add the identity provider to a user flow

Add the identity provider to a sign-up and sign-in user flow to allow sign-in and sign-up with the identity provider. See Add an identity provider to a user flow. An external user can then self-register in the External ID tenant. When the user selects the federated Microsoft Entra ID identity provider on the sign-in page and authenticates with their organizational account, a user account is automatically created in the external tenant.

Create the user with Microsoft Graph API

An admin can use the Microsoft Graph API to create a user directly in the External ID tenant. This approach is useful for automated provisioning or migration scenarios.

The following example creates a federated user with an identity linked to the source Microsoft Entra ID tenant:

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
  "accountEnabled": true,
  "displayName": "Test User",
  "givenName": "Test",
  "mail": "testuser@contoso.com",
  "surname": "Test User",
  "identities": [
    {
      "signInType": "federated",
      "issuer": "https://login.microsoftonline.com/<entra-tenant-primary-domain-name>/v2.0<entra-external-tenant-id>",
      "issuerAssignedId": "<entra-tenant-user-object-id>"
    }
  ]
}

Replace the following values:

• <entra-tenant-primary-domain-name>: The directory (tenant) primary domain name of the source Microsoft Entra ID tenant. For example, contoso.onmicrosoft.com.
• <entra-external-tenant-id>: The directory (tenant) ID of the External ID tenant.
• <entra-tenant-user-object-id>: The object ID of the user in the source Microsoft Entra ID tenant.

Frequently asked questions

I get an error: "No email address was obtained from the external OIDC identity provider." How do I fix it?

The email claim is required for External ID federation scenarios. Make sure the email claim is included in the application's Token configuration in the Microsoft Entra ID tenant used as the external identity provider.

My Microsoft Entra ID identity provider doesn't appear on the sign-in page, or domain_hint doesn't redirect to it. What should I check?

Verify that the issuer URI and well-known OpenID configuration endpoint are correctly configured. An incorrect issuer or discovery endpoint prevents the identity provider from appearing during sign-in. Also check that:

• The Microsoft Entra ID tenant is fully configured as a custom OIDC identity provider.
• Required redirect URIs, issuer values, and scopes are present and correct.
• The identity provider is added to the user flow, not just to the tenant.
• The OpenID Issuer URI uses either the Microsoft Entra ID tenant ID (GUID) or the tenant's onmicrosoft.com domain. Currently, other verified custom domains aren't supported for the issuer URI.
• If you use domain_hint, specify the tenant's domain name rather than its tenant ID. For example, use domain_hint=contoso.onmicrosoft.com with the corresponding issuer URI https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0.
• If you changed the issuer or identity provider configuration after adding the provider to a user flow, refresh the user-flow configuration. Remove the identity provider from the user flow, save the flow, add the identity provider again, and save before retesting. See Add the identity provider to a user flow for the refresh steps.

What does the error AADSTS500208: The domain is not a valid login domain for the account type mean?

This error indicates that sign-in failed because the account type isn't permitted to use the login URL or tenant being accessed. Verify that the correct sign-in endpoint is being used and that the account has access to the target tenant.

What does error 40015 mean when using a custom OIDC identity provider?

Error 40015 means that authentication at the external identity provider succeeded, but External ID rejected the response because the custom OIDC identity provider configuration or returned tokens couldn't be validated. Common causes include:

• The issuer URI doesn't exactly match the issuer value in the identity provider's discovery document.
• Authorization, token, or JWKS endpoints are incorrect or unreachable.
• Required attributes (such as subject or email) aren't returned by the identity provider.

How is adding Microsoft Entra ID as a custom OIDC federation different from inviting Microsoft Entra ID users as B2B guests?

Invited users from another Microsoft Entra tenant use the default invitation redemption flow unless your application explicitly routes them to the custom OIDC identity provider.

With Microsoft Entra ID federation:

• User authentication always occurs in the home Microsoft Entra ID tenant.
• Workforce Conditional Access and MFA policies are enforced.
• The sign-in experience is a full redirect to the home tenant, rather than the mixed-branding experience associated with B2B guest sign-in.

Do Microsoft Entra Conditional Access and MFA policies apply?

Yes. Because all authentication occurs in the user's home Microsoft Entra ID tenant, the following are enforced exactly as they are for native Microsoft Entra ID sign-ins:

• Conditional Access policies
• MFA requirements
• Device-based and risk-based controls

Why do I see a domain confirmation dialog when using domain_hint?

When domain_hint is used, a domain confirmation dialog appears to ensure the user is intentionally signing in to the correct organization and to protect against unauthorized or unexpected redirection. This security check can't be suppressed today, even when the redirect is expected.

Can new users be automatically redirected based on their email domain when they enter their email address on the sign-in page?

There's limited support today. Domain-based acceleration using domain_hint is supported in specific configurations, but fully automatic redirection based solely on email domain for new users isn't yet supported. If domain-based routing is required, consider using explicit identity provider buttons or passing a domain_hint parameter when initiating sign-in. The domain_hint value for Microsoft Entra ID should be the domain name, for example domain_hint=contoso.onmicrosoft.com. For more information, see Issuer Acceleration.

Can I hide specific identity provider buttons?

No, the identity provider buttons cannot be hidden.

Are ID tokens returned as opaque values?

No. Microsoft Entra ID issues standard signed JWT tokens. ID tokens are readable and conform to OpenID Connect specifications.

Can I use multiple Microsoft Entra ID tenants with a single external tenant?

Yes. You can configure multiple Microsoft Entra ID tenants as separate custom OIDC identity providers and expose them within External ID user flows.

Related content

• Add OpenID Connect as an external identity provider
• Route invited users to an external identity provider
• OIDC claims mapping