---
title: Microsoft Entra ID
description: >-
  Configure Microsoft Entra ID (formerly Azure AD) as a third-party identity
  provider for Shopify customer accounts and set up custom claims for customer
  data enrichment.
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-authentication/provider-guides/microsoft-entra-id
  md: >-
    https://shopify.dev/docs/api/customer-authentication/provider-guides/microsoft-entra-id.md
---

# Microsoft Entra ID

This guide covers how to configure [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure Active Directory) as a third-party identity provider for Shopify customer accounts, including how to add custom claims to your ID tokens for [customer data enrichment](https://shopify.dev/docs/api/customer-authentication/claim-import).

Shopify includes built-in handling for Entra ID's non-standard OIDC behavior, including email claim mapping and email verification.

***

## Prerequisites

* A [Shopify Plus](https://www.shopify.com/plus) plan with [new customer accounts](https://help.shopify.com/en/manual/customers/customer-accounts/new-customer-accounts) enabled.
* A Microsoft Entra tenant with an [App Registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) created.
* Token version set to v2.0: in the App Registration manifest, set `accessTokenAcceptedVersion` to `2`.

***

## Connect Entra ID to Shopify

To connect Microsoft Entra ID as your store's identity provider, you'll add your Entra ID credentials to the Shopify admin and configure your App Registration to accept Shopify's callback URL.

### Step 1: Add your Entra ID credentials in the Shopify admin

Add your Discovery URL, Application (client) ID, and Client Secret in the Shopify admin under **Settings** > **Customer accounts** > **Third-party identity provider**. Select **Entra ID** as the provider type.

You can find these values in the Microsoft Entra admin center:

* **Discovery URL:** `https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration`.
* **Application (client) ID:** Found on the **Overview** page of your App Registration.
* **Client Secret:** Create one under **Certificates & secrets** > **Client secrets**.

**Important:**

Select **Entra ID** as the provider type in the Shopify admin. This enables automatic handling of Entra ID's non-standard behavior: Shopify uses the `upn` claim as the customer's email source by default, and validates the ID token against Entra ID's claim set, which doesn't include the standard `email_verified` claim. If your tenant's `upn` isn't the customer's real email address, contact [Shopify Plus Support](https://help.shopify.com/en/support/plus) to switch the email source to `mail`, quoting your store's `.myshopify.com` domain. Custom setups, such as an Entra External ID/B2C policy that emits a real `email` claim, can use that claim instead.

For full setup instructions, refer to [Connect a third-party identity provider](https://help.shopify.com/en/manual/customers/customer-accounts/new-customer-accounts/identity-provider/connect).

### Step 2: Add your Shopify callback URL to Entra ID

To complete the connection, add your Shopify callback URL as a **Redirect URI** under **Authentication** in your App Registration. This lets Entra ID redirect customers back to your store after they authenticate.

You can find your Shopify callback URL in the Shopify admin on the same **Third-party identity provider** settings page from Step 1.

***

## Standard claims

Entra ID doesn't include profile claims in ID tokens by default. It delivers standard claims through **optional claims** that it embeds directly in the ID token. To import names, add them as optional claims and make sure Shopify [requests the matching scope](https://shopify.dev/docs/api/customer-authentication/claim-import#request-the-required-scopes) — Entra emits the `given_name` and `family_name` claims only when the `profile` scope is also requested at sign-in.

1. In the Entra admin center, go to your **App Registration > Token configuration**.
2. Click **Add optional claim** and select **ID** as the token type.
3. Add the following claims: `given_name`, `family_name`.
4. When prompted, consent to the required Microsoft Graph permissions.

**Note:**

By default, Shopify reads the customer's email address from Entra ID's `upn` claim. Only that one claim is used as the email source, so adding a `mail` claim to the token changes nothing on its own — [Shopify Plus Support](https://help.shopify.com/en/support/plus) has to switch your provider's email source claim first.

For more details, refer to [Configure optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims).

***

## Add custom Shopify claims

Adding custom claims in Entra ID is more involved than in Auth0 or Okta. The approach depends on the complexity of the claim.

### Tags (simple claims)

For simple string claims like `urn:shopify:customer:tags`, use a [Claims Mapping Policy](https://learn.microsoft.com/en-us/entra/identity-platform/reference-claims-customization):

1. In the App Registration manifest, set `acceptMappedClaims` to `true`. This is required for Claims Mapping Policies to work.
2. Create a Claims Mapping Policy using [Microsoft Graph](https://learn.microsoft.com/en-us/entra/identity-platform/reference-claims-customization) or PowerShell that maps a user attribute or directory extension to the `urn:shopify:customer:tags` claim in the ID token.

**Important:**

If you don't set `acceptMappedClaims` to `true` in the manifest, you'll get an `AADSTS50146` error during login.

### Addresses (complex claims)

For structured data like `urn:shopify:customer:addresses`, use a [Custom Authentication Extension](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration) with the **TokenIssuanceStart** event type:

1. Create an Azure Function or API endpoint that returns address data in the [Shopify address format](https://shopify.dev/docs/api/customer-authentication/claim-import#addresses).
2. In the Entra admin center, go to **Custom authentication extensions** and create a new extension with the **TokenIssuanceStart** event type.
3. Configure the extension to call your API endpoint and map the response attributes to token claims.
4. Assign the custom attributes as token claims in your App Registration under **Token configuration**.

This approach is more involved than other providers. If you're getting started with customer data enrichment, consider beginning with standard claims (name, email) and tags before implementing address import.

For more details, refer to [Configure a custom claims provider](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration).

***

## Enable enrichment in Shopify

After configuring your identity provider to include custom claims, you need to tell Shopify to read and import them.

In the Shopify admin under your identity provider settings, enable **Sync customer data** and configure the update trigger and overwrite rules. For details on these options, refer to [claim import configuration](https://shopify.dev/docs/api/customer-authentication/claim-import#configuration).

***

## Verify

After enabling enrichment, verify that your claims are included in the ID token and that Shopify imports them correctly:

1. Use [jwt.ms](https://jwt.ms) to decode your ID token and verify that custom claims are present before testing on Shopify.
2. Authenticate on your store through Entra ID.
3. In the Shopify admin, go to **Customers** and open the customer record to confirm the imported data.

***

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| `AADSTS50146` error during login | `acceptMappedClaims` not enabled | In the App Registration manifest, set `acceptMappedClaims` to `true` |
| Claims missing from ID token | Token version set to 1.0 | In the App Registration manifest, set `accessTokenAcceptedVersion` to `2` |
| Customer email missing or empty | The attribute behind the email source claim isn't populated for the user | Make sure the attribute behind your provider's email source claim — `upn` by default, or `mail` if you've had it switched — is populated for the user in Entra |
| Customers created with a GUID-style or non-email address | The tenant's `upn` isn't the user's real email address | Ask [Shopify Plus Support](https://help.shopify.com/en/support/plus) to switch the email source claim to `mail`, quoting your store's `.myshopify.com` domain, and ensure the user's `mail` attribute is populated in Entra |
| `email_verified` error | Provider type not set to Entra ID in Shopify | Select **Entra ID** as the provider type in the Shopify admin so Shopify validates against Entra ID's claim set, which doesn't include the standard `email_verified` claim |
| Name claims (`given_name`, `family_name`) not imported | `profile` scope not requested, optional claims not configured, or enrichment disabled | Add `profile` to the **Additional scopes** field in the Shopify admin so names are requested at sign-in; add `given_name` and `family_name` as optional ID token claims under **Token configuration**; and confirm **Sync customer data** is enabled |
| Custom claims not appearing | Claims Mapping Policy not applied | Verify the policy is assigned to the service principal and that `acceptMappedClaims` is `true` |

***

## Resources

* [Microsoft: Configure optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims)
* [Microsoft: Optional claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference)
* [Microsoft: Claims customization](https://learn.microsoft.com/en-us/entra/identity-platform/reference-claims-customization)
* [Microsoft: Custom claims provider configuration](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration)
* [Microsoft: ID token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference)
* [Microsoft: Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
* [Shopify: Claim import reference](https://shopify.dev/docs/api/customer-authentication/claim-import)

***