Set up sign-in with an Azure Active Directory account using custom policies in Azure Active Directory B2C

Note

Custom policies are in public preview.

Custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use Azure Active Directory B2C built-in policies. Built-in policies are easier to set up for your configuration.

This article shows you how to enable sign-in for users from an Azure Active Directory (Azure AD) organization by using custom policies in Azure Active Directory (Azure AD) B2C.

Prerequisites

Complete the steps in Get started with custom policies in Azure Active Directory B2C.

Register an application

To enable sign-in for users from a specific Azure AD organization, you need to register an application within the organizational Azure AD tenant.

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains organizational Azure AD tenant (contoso.com) by clicking the Directory and subscription filter in the top menu and choosing the directory that contains your tenant.
  3. Choose All services in the top-left corner of the Azure portal, and then search for and select App registrations.
  4. Select New application registration.
  5. Enter a name for your application. For example, Azure AD B2C App.
  6. For the Application type, select Web app / API.
  7. For the Sign-on URL, 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://contoso.b2clogin.com/contoso.onmicrosoft.com/oauth2/authresp.

  8. Click Create. Copy the Application ID to be used later.

  9. Select the application, and then select Settings.
  10. Select Keys, enter the key description, select a duration, and then click Save. Copy the value of the key that is displayed to be used later.

Create a policy key

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

  1. Make sure you're using the directory that contains your Azure AD B2C tenant by clicking the Directory and subscription filter in the top menu and choosing the directory that contains your tenant.
  2. Choose All services in the top-left corner of the Azure portal, and then search for and select Azure AD B2C.
  3. On the Overview page, select Identity Experience Framework - PREVIEW.
  4. Select Policy Keys and then select Add.
  5. For Options, choose Manual.
  6. Enter a Name for the policy key. For example, ContosoAppSecret. The prefix B2C_1A_ is added automatically to the name of your key.
  7. In Secret, enter your application key that you previously recorded.
  8. For Key usage, select Signature.
  9. Click Create.

Add a claims provider

If you want users to sign in by using Azure AD, you need to define Azure AD 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 Azure AD as a claims provider by adding Azure AD to the ClaimsProvider element in the extension file of your policy.

  1. Open the TrustFrameworkExtensions.xml.
  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>Contoso</Domain>
      <DisplayName>Login using Contoso</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="ContosoProfile">
          <DisplayName>Contoso Employee</DisplayName>
          <Description>Login with your Contoso account</Description>
          <Protocol Name="OpenIdConnect"/>
          <OutputTokenFormat>JWT</OutputTokenFormat>
          <Metadata>
            <Item Key="METADATA">https://login.windows.net/your-AD-tenant-name.onmicrosoft.com/.well-known/openid-configuration</Item>
            <Item Key="ProviderName">https://sts.windows.net/00000000-0000-0000-0000-000000000000/</Item>
            <Item Key="client_id">00000000-0000-0000-0000-000000000000</Item>
            <Item Key="IdTokenAudience">00000000-0000-0000-0000-000000000000</Item>
            <Item Key="UsePolicyInRedirectUri">false</Item>
            <Item Key="response_types">code</Item>
            <Item Key="scope">openid</Item>
            <Item Key="response_mode">form_post</Item>
            <Item Key="HttpBinding">POST</Item>
          </Metadata>
          <CryptographicKeys>
            <Key Id="client_secret" StorageReferenceId="B2C_1A_ContosoAppSecret"/>
          </CryptographicKeys>
          <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="socialIdpUserId" PartnerClaimType="oid"/>
            <OutputClaim ClaimTypeReferenceId="tenantId" PartnerClaimType="tid"/>
            <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" DefaultValue="AzureADContoso" AlwaysUseDefaultValue="true" />
          </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. For example Contoso. You don't put a .com at the end of this domain setting.

  5. Under the ClaimsProvider element, update the value for DisplayName to a friendly name for the claims provider. This value is not currently used.

Update the technical profile

To get a token from the Azure AD endpoint, you need to define the protocols that Azure AD B2C should use to communicate with Azure AD. This is done inside the TechnicalProfile element of ClaimsProvider.

  1. Update the ID of the TechnicalProfile element. This ID is used to refer to this technical profile from other parts of the policy.
  2. Update the value for DisplayName. This value will be displayed on the sign-in button on your sign-in screen.
  3. Update the value for Description.
  4. Azure AD uses the OpenID Connect protocol, so make sure that the value for Protocol is OpenIdConnect.
  5. Set value of the METADATA to https://login.windows.net/your-AD-tenant-name.onmicrosoft.com/.well-known/openid-configuration, where your-AD-tenant-name is your Azure AD tenant name. For example, https://login.windows.net/fabrikam.onmicrosoft.com/.well-known/openid-configuration
  6. Open your browser and go to the METADATA URL that you just updated, look for the issuer object, copy and paste the value into the value for ProviderName in the XML file.
  7. Set client_id and IdTokenAudience to the application ID from the application registration.
  8. Under CryptograhicKeys, Update the value for StorageReferenceId to the policy key that you defined. For example, ContosoAppSecret.

Upload the extension file for verification

By now, you have configured your policy so that Azure AD B2C knows how to communicate with your Azure AD directory. Try uploading the extension file of your policy just to confirm that it doesn't have any issues so far.

  1. On the Custom Policies page in your Azure AD B2C tenant, select Upload Policy.
  2. Enable Overwrite the policy if it exists, and then browse to and select the TrustFrameworkExtensions.xml file.
  3. Click Upload.

Register the claims provider

At this point, the identity provider has been set up, but it’s not available in any of the sign-up/sign-in screens. To make it available, you create a duplicate of an existing template user journey, and then modify it so that it also has the Azure AD identity provider:

  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, SignUpSignInContoso.

Display the button

The ClaimsProviderSelection element is analogous to an identity provider button on a sign-up/sign-in screen. If you add a ClaimsProviderSelection element for Azure AD, a new button shows up when a user lands on the page.

  1. Find the OrchestrationStep element that includes Order="1" in the user journey that you created.
  2. Under ClaimsProviderSelections, add the following element. Set the value of TargetClaimsExchangeId to an appropriate value, for example ContosoExchange:

    <ClaimsProviderSelection TargetClaimsExchangeId="ContosoExchange" />
    

Now that you have a button in place, you need to link it to an action. The action, in this case, is for Azure AD B2C to communicate with Azure AD to receive a token. Link the button to an action by linking the technical profile for your Azure AD claims provider:

  1. Find the OrchestrationStep that includes Order="2" in the user journey.
  2. Add the following ClaimsExchange element making sure that you use the same value for Id that you used for TargetClaimsExchangeId:

    <ClaimsExchange Id="ContosoExchange" TechnicalProfileReferenceId="ContosoProfile" />
    

    Update the value of TechnicalProfileReferenceId to the Id of the technical profile you created earlier. For example, ContosoProfile.

  3. Save the TrustFrameworkExtensions.xml file and upload it again for verification.

Create an Azure AD B2C application

Communication with Azure AD B2c occurs through an application that you create in your tenant. This section lists optional steps you can complete to create a test application if you haven't already done so.

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant by clicking the Directory and subscription filter in the top menu and choosing the directory that contains your tenant.
  3. Choose All services in the top-left corner of the Azure portal, and then search for and select Azure AD B2C.
  4. Select Applications, and then select Add.
  5. Enter a name for the application, for example testapp1.
  6. For Web App / Web API, select Yes, and then enter https://jwt.ms for the Reply URL.
  7. Click Create.

Update and test the relying party file

Update the relying party (RP) file that initiates the user journey that you created.

  1. Make a copy of SignUpOrSignIn.xml in your working directory, and rename it. For example, rename it to SignUpSignInContoso.xml.
  2. Open the new file and update the value of the PolicyId attribute for TrustFrameworkPolicy with a unique value. For example, SignUpSignInContoso.
  3. Update the value of PublicPolicyUri with the URI for the policy. For example,http://contoso.com/B2C_1A_signup_signin_contoso
  4. Update the value of the ReferenceId attribute in DefaultUserJourney to match the ID of the new user journey that you created (SignUpSignInContoso).
  5. Save your changes, upload the file, and then select the new policy in the list.
  6. Make sure that Azure AD B2C application that you created is selected in the Select application field, and then test it by clicking Run now.