--- 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. api_name: customer-authentication 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 **Microsoft 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 **Microsoft Entra ID** as the provider type in the Shopify admin. This enables automatic handling of Entra ID's non-standard behavior: Shopify will accept the `mail` or `upn` claim in place of the standard `email` claim, and skip the `email_verified` check that Entra ID doesn't support. 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. To import names and email, you need to add them as optional claims: 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`, `email`. 4. When prompted, consent to the required Microsoft Graph permissions. **Note:** Entra ID uses the `mail` attribute from the user profile rather than a standard `email` claim. When you select Entra ID as the provider type in Shopify, this mapping is handled automatically. 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` | | `email` claim missing | Optional claim not configured, or `mail` attribute empty | Add `email` as an optional claim under Token configuration, and ensure the user's `mail` attribute is populated in Entra | | `email_verified` error | Provider type not set to Entra ID in Shopify | Select **Microsoft Entra ID** as the provider type in the Shopify admin to bypass the `email_verified` check | | 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: 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) ***