Edit

Set up sign-in for multitenant Microsoft Entra ID using custom policies in Azure Active Directory B2C

  • Article

Before you begin, use the Choose a policy type selector at the top of this page to choose the type of policy you’re setting up. Azure Active Directory B2C offers two methods to define how users interact with your applications: through predefined user flows or through fully configurable custom policies. The steps required in this article are different for each method.

This feature is available only for custom policies. For setup steps, select Custom policy in the preceding selector.

This article shows you how to enable sign-in for users using the multitenant endpoint for Microsoft Entra ID, allowing users from multiple Microsoft Entra tenants to sign in using Azure AD B2C, without you having to configure an identity provider for each tenant. However, guest members in any of these tenants will not be able to sign in. For that, you need to individually configure each tenant.

Prerequisites

Note

In this article, it is assumed that the SocialAndLocalAccounts starter pack is used in the previous steps mentioned in the pre-requisite.

Register a Microsoft Entra app

To enable users to sign in to Azure AD B2C with a Microsoft Entra account, you first need to create an application in the Microsoft Entra tenant from the Azure portal. For more information, see Register an application with the Microsoft identity platform.

  1. Sign in to the Azure portal.

  2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Microsoft Entra tenant from the Directories + subscriptions menu.

  3. Choose All services in the top-left corner of the Azure portal, and then search for and select App registrations.

  4. Select New registration.

  5. Enter a Name for your application. For example, Azure AD B2C App.

  6. Select Accounts in any organizational directory (Any Microsoft Entra directory – Multitenant) for this application.

  7. For the Redirect URI, accept the value of Web, and enter the following URL in all lowercase letters, where your-B2C-tenant-name is replaced with the name of your Azure AD B2C tenant.

    https://your-B2C-tenant-name.b2clogin.com/your-B2C-tenant-name.onmicrosoft.com/oauth2/authresp

    For example, https://fabrikam.b2clogin.com/fabrikam.onmicrosoft.com/oauth2/authresp.

    If you use a custom domain, enter https://your-domain-name/your-tenant-name.onmicrosoft.com/oauth2/authresp. Replace your-domain-name with your custom domain, and your-tenant-name with the name of your tenant.

  8. Select Register. Record the Application (client) ID for use in a later step.

  9. Select Certificates & secrets, and then select New client secret.

  10. Enter a Description for the secret, select an expiration, and then select Add. Record the Value of the secret for use in a later step.

Note

The client secret will not be shown again after this point. If you do not make a record of it, you will have to create a new one.

[Optional] Configuring optional claims

If you want to get the family_name, and given_name claims from Microsoft Entra ID, you can configure optional claims for your application in the Azure portal UI or application manifest. For more information, see How to provide optional claims to your Microsoft Entra app.

  1. Sign in to the Azure portal. Search for and select Microsoft Entra ID.
  2. From the Manage section, select App registrations.
  3. Select the application you want to configure optional claims for in the list.
  4. From the Manage section, select Token configuration.
  5. Select Add optional claim.
  6. For the Token type, select ID.
  7. Select the optional claims to add, family_name, and given_name.
  8. Select Add. If Turn on the Microsoft Graph email permission (required for claims to appear in token) appears, enable it, and then select Add again.

[Optional] Verify your app authenticity

Publisher verification helps your users understand the authenticity of the app you registered. A verified app means that the publisher of the app has verified their identity using their Microsoft Partner Network (MPN). Learn how to mark your app as publisher verified.

Create a policy key

You now need to store the application key that you created in your Azure AD B2C tenant.

  1. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Azure AD B2C tenant from the Directories + subscriptions menu.
  2. Choose All services in the top-left corner of the Azure portal, and then search for and select Azure AD B2C.
  3. Under Policies, select Identity Experience Framework.
  4. Select Policy keys and then select Add.
  5. For Options, choose Manual.
  6. Enter a Name for the policy key. For example, AADAppSecret. The prefix B2C_1A_ is added automatically to the name of your key when it's created, so its reference in the XML in following section is to B2C_1A_AADAppSecret.
  7. In Secret, enter your client secret that you recorded earlier.
  8. For Key usage, select Signature.
  9. Select Create.

Configure Microsoft Entra ID as an identity provider

To enable users to sign in using a Microsoft Entra account, you need to define Microsoft Entra ID as a claims provider that Azure AD B2C can communicate with through an endpoint. The endpoint provides a set of claims that are used by Azure AD B2C to verify that a specific user has authenticated.

You can define Microsoft Entra ID as a claims provider by adding Microsoft Entra ID to the ClaimsProvider element in the extension file of your policy.

  1. Open the SocialAndLocalAccounts/TrustFrameworkExtensions.xml file (see the files you've used in the prerequisites).

  2. Find the ClaimsProviders element. If it does not exist, add it under the root element.

  3. Add a new ClaimsProvider as follows:

    <ClaimsProvider>
  <Domain>commonaad</Domain>
  <DisplayName>Common AAD</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="AADCommon-OpenIdConnect">
      <DisplayName>Multi-Tenant AAD</DisplayName>
      <Description>Login with your Contoso account</Description>
      <Protocol Name="OpenIdConnect"/>
      <Metadata>
        <Item Key="METADATA">https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration</Item>
        <!-- Update the Client ID below to the Application ID -->
        <Item Key="client_id">00000000-0000-0000-0000-000000000000</Item>
        <Item Key="response_types">code</Item>
        <Item Key="scope">openid profile</Item>
        <Item Key="response_mode">form_post</Item>
        <Item Key="HttpBinding">POST</Item>
        <Item Key="UsePolicyInRedirectUri">false</Item>
        <Item Key="DiscoverMetadataByTokenIssuer">true</Item>
        <!-- The key below allows you to specify each of the Azure AD tenants that can be used to sign in. Update the GUIDs below for each tenant. -->
        <Item Key="ValidTokenIssuerPrefixes">https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000,https://login.microsoftonline.com/11111111-1111-1111-1111-111111111111</Item>
        <!-- The commented key below specifies that users from any tenant can sign-in. Uncomment if you would like anyone with an Azure AD account to be able to sign in. -->
        <!-- <Item Key="ValidTokenIssuerPrefixes">https://login.microsoftonline.com/</Item> -->
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_AADAppSecret"/>
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="oid"/>
        <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="given_name" />
        <OutputClaim ClaimTypeReferenceId="surName" PartnerClaimType="family_name" />
        <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
        <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" AlwaysUseDefaultValue="true" />
        <OutputClaim ClaimTypeReferenceId="identityProvider" PartnerClaimType="iss" />
      </OutputClaims>
      <OutputClaimsTransformations>
        <OutputClaimsTransformation ReferenceId="CreateRandomUPNUserName"/>
        <OutputClaimsTransformation ReferenceId="CreateUserPrincipalName"/>
        <OutputClaimsTransformation ReferenceId="CreateAlternativeSecurityId"/>
        <OutputClaimsTransformation ReferenceId="CreateSubjectClaimFromAlternativeSecurityId"/>
      </OutputClaimsTransformations>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-SocialLogin"/>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

  4. Under the ClaimsProvider element, update the value for Domain to a unique value that can be used to distinguish it from other identity providers.

  5. Under the TechnicalProfile element, update the value for DisplayName, for example, Multi-Tenant AAD. This value is displayed on the sign-in button on your sign-in page.

  6. Set client_id to the application ID of the Microsoft Entra multitenant application that you registered earlier.

  7. Under CryptographicKeys, update the value of StorageReferenceId to the name of the policy key that you created earlier. For example, B2C_1A_AADAppSecret.

Restrict access

Using https://login.microsoftonline.com/ as the value for ValidTokenIssuerPrefixes allows all Microsoft Entra users to sign in to your application. Update the list of valid token issuers and restrict access to a specific list of Microsoft Entra tenant users who can sign in.

To obtain the values, look at the OpenID Connect discovery metadata for each of the Microsoft Entra tenants that you would like to have users sign in from. The format of the metadata URL is similar to https://login.microsoftonline.com/your-tenant/v2.0/.well-known/openid-configuration, where your-tenant is your Microsoft Entra tenant name. For example:

https://login.microsoftonline.com/fabrikam.onmicrosoft.com/v2.0/.well-known/openid-configuration

Perform these steps for each Microsoft Entra tenant that should be used to sign in:

  1. Open your browser and go to the OpenID Connect metadata URL for the tenant. Find the issuer object and record its value. It should look similar to https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0.
  2. Copy and paste the value into the ValidTokenIssuerPrefixes key. Separate multiple issuers with a comma. An example with two issuers appears in the previous ClaimsProvider XML sample.

Add a user journey

At this point, the identity provider has been set up, but it's not yet available in any of the sign-in pages. If you don't have your own custom user journey, create a duplicate of an existing template user journey, otherwise continue to the next step.

  1. Open the TrustFrameworkBase.xml file from the starter pack.
  2. Find and copy the entire contents of the UserJourney element that includes Id="SignUpOrSignIn".
  3. Open the TrustFrameworkExtensions.xml and find the UserJourneys element. If the element doesn't exist, add one.
  4. Paste the entire content of the UserJourney element that you copied as a child of the UserJourneys element.
  5. Rename the Id of the user journey. For example, Id="CustomSignUpSignIn".

Add the identity provider to a user journey

Now that you have a user journey, add the new identity provider to the user journey. You first add a sign-in button, then link the button to an action. The action is the technical profile you created earlier.

  1. Find the orchestration step element that includes Type="CombinedSignInAndSignUp", or Type="ClaimsProviderSelection" in the user journey. It's usually the first orchestration step. The ClaimsProviderSelections element contains a list of identity providers that a user can sign in with. The order of the elements controls the order of the sign-in buttons presented to the user. Add a ClaimsProviderSelection XML element. Set the value of TargetClaimsExchangeId to a friendly name.

  2. In the next orchestration step, add a ClaimsExchange element. Set the Id to the value of the target claims exchange Id. Update the value of TechnicalProfileReferenceId to the Id of the technical profile you created earlier.

The following XML demonstrates the first two orchestration steps of a user journey with the identity provider:

<OrchestrationStep Order="1" Type="CombinedSignInAndSignUp" ContentDefinitionReferenceId="api.signuporsignin">
  <ClaimsProviderSelections>
    ...
    <ClaimsProviderSelection TargetClaimsExchangeId="AzureADCommonExchange" />
  </ClaimsProviderSelections>
  ...
</OrchestrationStep>

<OrchestrationStep Order="2" Type="ClaimsExchange">
  ...
  <ClaimsExchanges>
    <ClaimsExchange Id="AzureADCommonExchange" TechnicalProfileReferenceId="AADCommon-OpenIdConnect" />
  </ClaimsExchanges>
</OrchestrationStep>

Configure the relying party policy

The relying party policy, for example SignUpSignIn.xml, specifies the user journey which Azure AD B2C will execute. Find the DefaultUserJourney element within relying party. Update the ReferenceId to match the user journey ID, in which you added the identity provider.

In the following example, for the CustomSignUpSignIn user journey, the ReferenceId is set to CustomSignUpSignIn:

<RelyingParty>
  <DefaultUserJourney ReferenceId="CustomSignUpSignIn" />
  ...
</RelyingParty>

Upload the custom policy

  1. Sign in to the Azure portal.
  2. Select the Directory + Subscription icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
  3. In the Azure portal, search for and select Azure AD B2C.
  4. Under Policies, select Identity Experience Framework.
  5. Select Upload Custom Policy, and then upload the two policy files that you changed, in the following order: the extension policy, for example TrustFrameworkExtensions.xml, then the relying party policy, such as SignUpSignIn.xml.

Test your custom policy

  1. Select your relying party policy, for example B2C_1A_signup_signin.
  2. For Application, select a web application that you previously registered. The Reply URL should show https://jwt.ms.
  3. Select the Run now button.
  4. From the sign-up or sign-in page, select Common Microsoft Entra ID to sign in with Microsoft Entra account.

To test the multitenant sign-in capability, perform the last two steps using the credentials for a user that exists with another Microsoft Entra tenant. Copy the Run now endpoint and open it in a private browser window, for example, Incognito Mode in Google Chrome or an InPrivate window in Microsoft Edge. Opening in a private browser window allows you to test the full user journey by not using any currently cached Microsoft Entra credentials.

If the sign-in process is successful, your browser is redirected to https://jwt.ms, which displays the contents of the token returned by Azure AD B2C.

See also