Set up sign-up and sign-in with a LinkedIn account using Azure Active Directory B2C

Before you begin, use the Choose a policy type selector 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.

Note

In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use built-in user flows.

Prerequisites

Create a LinkedIn application

To enable sign-in for users with a LinkedIn account in Azure Active Directory B2C (Azure AD B2C), you need to create an application in LinkedIn Developers website. For more information, see Authorization Code Flow. If you don't already have a LinkedIn account, you can sign up at https://www.linkedin.com/.

  1. Sign in to the LinkedIn Developers website with your LinkedIn account credentials.
  2. Select My Apps, and then click Create app.
  3. Enter App name, LinkedIn Page, Privacy policy URL, and App logo.
  4. Agree to the LinkedIn API Terms of Use and click Create app.
  5. Select the Auth tab. Under Authentication Keys, copy the values for Client ID and Client Secret. You'll need both of them to configure LinkedIn as an identity provider in your tenant. Client Secret is an important security credential.
  6. Select the edit pencil next to Authorized redirect URLs for your app, and then select Add redirect URL. Enter https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/oauth2/authresp. If you use a custom domain, enter https://your-domain-name/your-tenant-name.onmicrosoft.com/oauth2/authresp. Replace your-tenant-name with the name of your tenant, and your-domain-name with your custom domain. You need to use all lowercase letters when entering your tenant name even if the tenant is defined with uppercase letters in Azure AD B2C. Select Update.
  7. By default, your LinkedIn app isn't approved for scopes related to sign in. To request a review, select the Products tab, and then select Sign In with LinkedIn. When the review is complete, the required scopes will be added to your application.

    Note

    You can view the scopes that are currently allowed for your app on the Auth tab in the OAuth 2.0 scopes section.

Configure LinkedIn as an identity provider

  1. Sign in to the Azure portal as the global administrator of your Azure AD B2C tenant.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant. Select the Directories + subscriptions icon in the portal toolbar.
  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.
  4. Choose All services in the top-left corner of the Azure portal, search for and select Azure AD B2C.
  5. Select Identity providers, then select LinkedIn.
  6. Enter a Name. For example, LinkedIn.
  7. For the Client ID, enter the Client ID of the LinkedIn application that you created earlier.
  8. For the Client secret, enter the Client Secret that you recorded.
  9. Select Save.

Add LinkedIn identity provider to a user flow

At this point, the LinkedIn identity provider has been set up, but it's not yet available in any of the sign-in pages. To add the LinkedIn identity provider to a user flow:

  1. In your Azure AD B2C tenant, select User flows.
  2. Click the user flow that you want to add the LinkedIn identity provider.
  3. Under the Social identity providers, select LinkedIn.
  4. Select Save.
  5. To test your policy, select Run user flow.
  6. For Application, select the web application named testapp1 that you previously registered. The Reply URL should show https://jwt.ms.
  7. Select the Run user flow button.
  8. From the sign-up or sign-in page, select LinkedIn to sign in with LinkedIn account.

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.

Create a policy key

You need to store the client secret that you previously recorded in your Azure AD B2C tenant.

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant. Select the Directories + subscriptions icon in the portal toolbar.
  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.
  4. Choose All services in the top-left corner of the Azure portal, and then search for and select Azure AD B2C.
  5. On the Overview page, select Identity Experience Framework.
  6. Select Policy keys and then select Add.
  7. For Options, choose Manual.
  8. Enter a Name for the policy key. For example, LinkedInSecret. The prefix B2C_1A_ is added automatically to the name of your key.
  9. In Secret, enter the client secret that you previously recorded.
  10. For Key usage, select Signature.
  11. Click Create.

Configure LinkedIn as an identity provider

To enable users to sign in using an LinkedIn account, you need to define the account 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.

Define a LinkedIn account as a claims provider by adding it to the ClaimsProviders element in the extension file of your policy.

  1. Open the SocialAndLocalAccounts/TrustFrameworkExtensions.xml file in your editor. This file is in the Custom policy starter pack you downloaded as part of one of 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>linkedin.com</Domain>
      <DisplayName>LinkedIn</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="LinkedIn-OAuth2">
          <DisplayName>LinkedIn</DisplayName>
          <Protocol Name="OAuth2" />
          <Metadata>
            <Item Key="ProviderName">linkedin</Item>
            <Item Key="authorization_endpoint">https://www.linkedin.com/oauth/v2/authorization</Item>
            <Item Key="AccessTokenEndpoint">https://www.linkedin.com/oauth/v2/accessToken</Item>
            <Item Key="ClaimsEndpoint">https://api.linkedin.com/v2/me</Item>
            <Item Key="scope">r_emailaddress r_liteprofile</Item>
            <Item Key="HttpBinding">POST</Item>
            <Item Key="external_user_identity_claim_id">id</Item>
            <Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>
            <Item Key="ResolveJsonPathsInJsonTokens">true</Item>
            <Item Key="UsePolicyInRedirectUri">false</Item>
            <Item Key="client_id">Your LinkedIn application client ID</Item>
          </Metadata>
          <CryptographicKeys>
            <Key Id="client_secret" StorageReferenceId="B2C_1A_LinkedInSecret" />
          </CryptographicKeys>
          <InputClaims />
          <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="id" />
            <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName.localized" />
            <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName.localized" />
            <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="linkedin.com" AlwaysUseDefaultValue="true" />
            <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" AlwaysUseDefaultValue="true" />
          </OutputClaims>
          <OutputClaimsTransformations>
            <OutputClaimsTransformation ReferenceId="ExtractGivenNameFromLinkedInResponse" />
            <OutputClaimsTransformation ReferenceId="ExtractSurNameFromLinkedInResponse" />
            <OutputClaimsTransformation ReferenceId="CreateRandomUPNUserName" />
            <OutputClaimsTransformation ReferenceId="CreateUserPrincipalName" />
            <OutputClaimsTransformation ReferenceId="CreateAlternativeSecurityId" />
            <OutputClaimsTransformation ReferenceId="CreateSubjectClaimFromAlternativeSecurityId" />
          </OutputClaimsTransformations>
          <UseTechnicalProfileForSessionManagement ReferenceId="SM-SocialLogin" />
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
    
  4. Replace the value of client_id with the client ID of the LinkedIn application that you previously recorded.

  5. Save the file.

Add the claims transformations

The LinkedIn technical profile requires the ExtractGivenNameFromLinkedInResponse and ExtractSurNameFromLinkedInResponse claims transformations to be added to the list of ClaimsTransformations. If you don't have a ClaimsTransformations element defined in your file, add the parent XML elements as shown below. The claims transformations also need a new claim type defined named nullStringClaim.

Add the BuildingBlocks element near the top of the TrustFrameworkExtensions.xml file. See TrustFrameworkBase.xml for an example.

<BuildingBlocks>
  <ClaimsSchema>
    <!-- Claim type needed for LinkedIn claims transformations -->
    <ClaimType Id="nullStringClaim">
      <DisplayName>nullClaim</DisplayName>
      <DataType>string</DataType>
      <AdminHelpText>A policy claim to store output values from ClaimsTransformations that aren't useful. This claim should not be used in TechnicalProfiles.</AdminHelpText>
      <UserHelpText>A policy claim to store output values from ClaimsTransformations that aren't useful. This claim should not be used in TechnicalProfiles.</UserHelpText>
    </ClaimType>
  </ClaimsSchema>

  <ClaimsTransformations>
    <!-- Claim transformations needed for LinkedIn technical profile -->
    <ClaimsTransformation Id="ExtractGivenNameFromLinkedInResponse" TransformationMethod="GetSingleItemFromJson">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="inputJson" />
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="nullStringClaim" TransformationClaimType="key" />
        <OutputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="value" />
      </OutputClaims>
    </ClaimsTransformation>
    <ClaimsTransformation Id="ExtractSurNameFromLinkedInResponse" TransformationMethod="GetSingleItemFromJson">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="inputJson" />
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="nullStringClaim" TransformationClaimType="key" />
        <OutputClaim ClaimTypeReferenceId="surname" TransformationClaimType="value" />
      </OutputClaims>
    </ClaimsTransformation>
  </ClaimsTransformations>
</BuildingBlocks>

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="LinkedInExchange" />
  </ClaimsProviderSelections>
  ...
</OrchestrationStep>

<OrchestrationStep Order="2" Type="ClaimsExchange">
  ...
  <ClaimsExchanges>
    <ClaimsExchange Id="LinkedInExchange" TechnicalProfileReferenceId="LinkedIn-OAuth2" />
  </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 CustomSignUpOrSignIn user journey, the ReferenceId is set to CustomSignUpOrSignIn:

<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 LinkedIn to sign in with LinkedIn account.

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.

Migration from v1.0 to v2.0

LinkedIn recently updated their APIs from v1.0 to v2.0. To migrate your existing configuration to the new configuration, use the information in the following sections to update the elements in the technical profile.

Replace items in the Metadata

In the existing Metadata element of the TechnicalProfile, update the following Item elements from:

<Item Key="ClaimsEndpoint">https://api.linkedin.com/v1/people/~:(id,first-name,last-name,email-address,headline)</Item>
<Item Key="scope">r_emailaddress r_basicprofile</Item>

To:

<Item Key="ClaimsEndpoint">https://api.linkedin.com/v2/me</Item>
<Item Key="scope">r_emailaddress r_liteprofile</Item>

Add items to the Metadata

In the Metadata of the TechnicalProfile, add the following Item elements:

<Item Key="external_user_identity_claim_id">id</Item>
<Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>
<Item Key="ResolveJsonPathsInJsonTokens">true</Item>

Update the OutputClaims

In the existing OutputClaims of the TechnicalProfile, update the following OutputClaim elements from:

<OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
<OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />

To:

<OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName.localized" />
<OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName.localized" />

Add new OutputClaimsTransformation elements

In the OutputClaimsTransformations of the TechnicalProfile, add the following OutputClaimsTransformation elements:

<OutputClaimsTransformation ReferenceId="ExtractGivenNameFromLinkedInResponse" />
<OutputClaimsTransformation ReferenceId="ExtractSurNameFromLinkedInResponse" />

Define the new claims transformations and claim type

In the last step, you added new claims transformations that need to be defined. To define the claims transformations, add them to the list of ClaimsTransformations. If you don't have a ClaimsTransformations element defined in your file, add the parent XML elements as shown below. The claims transformations also need a new claim type defined named nullStringClaim.

The BuildingBlocks element should be added near the top of the file. See the TrustframeworkBase.xml as an example.

<BuildingBlocks>
  <ClaimsSchema>
    <!-- Claim type needed for LinkedIn claims transformations -->
    <ClaimType Id="nullStringClaim">
      <DisplayName>nullClaim</DisplayName>
      <DataType>string</DataType>
      <AdminHelpText>A policy claim to store unuseful output values from ClaimsTransformations. This claim should not be used in a TechnicalProfiles.</AdminHelpText>
      <UserHelpText>A policy claim to store unuseful output values from ClaimsTransformations. This claim should not be used in a TechnicalProfiles.</UserHelpText>
    </ClaimType>
  </ClaimsSchema>

  <ClaimsTransformations>
    <!-- Claim transformations needed for LinkedIn technical profile -->
    <ClaimsTransformation Id="ExtractGivenNameFromLinkedInResponse" TransformationMethod="GetSingleItemFromJson">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="inputJson" />
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="nullStringClaim" TransformationClaimType="key" />
        <OutputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="value" />
      </OutputClaims>
    </ClaimsTransformation>
    <ClaimsTransformation Id="ExtractSurNameFromLinkedInResponse" TransformationMethod="GetSingleItemFromJson">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="inputJson" />
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="nullStringClaim" TransformationClaimType="key" />
        <OutputClaim ClaimTypeReferenceId="surname" TransformationClaimType="value" />
      </OutputClaims>
    </ClaimsTransformation>
  </ClaimsTransformations>
</BuildingBlocks>

Obtain an email address

As part of the LinkedIn migration from v1.0 to v2.0, an additional call to another API is required to obtain the email address. If you need to obtain the email address during sign-up, do the following:

  1. Complete the steps above to allow Azure AD B2C to federate with LinkedIn to let the user sign in. As part of the federation, Azure AD B2C receives the access token for LinkedIn.

  2. Save the LinkedIn access token into a claim. See the instructions here.

  3. Add the following claims provider that makes the request to LinkedIn's /emailAddress API. In order to authorize this request, you need the LinkedIn access token.

    <ClaimsProvider>
      <DisplayName>REST APIs</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="API-LinkedInEmail">
          <DisplayName>Get LinkedIn email</DisplayName>
          <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
          <Metadata>
              <Item Key="ServiceUrl">https://api.linkedin.com/v2/emailAddress?q=members&amp;projection=(elements*(handle~))</Item>
              <Item Key="AuthenticationType">Bearer</Item>
              <Item Key="UseClaimAsBearerToken">identityProviderAccessToken</Item>
              <Item Key="SendClaimsIn">Url</Item>
              <Item Key="ResolveJsonPathsInJsonTokens">true</Item>
          </Metadata>
          <InputClaims>
              <InputClaim ClaimTypeReferenceId="identityProviderAccessToken" />
          </InputClaims>
          <OutputClaims>
              <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="elements[0].handle~.emailAddress" />
          </OutputClaims>
          <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
    
  4. Add the following orchestration step into your user journey, so that the API claims provider is triggered when a user signs in using LinkedIn. Make sure to update the Order number appropriately. Add this step immediately after the orchestration step that triggers the LinkedIn technical profile.

    <!-- Extra step for LinkedIn to get the email -->
    <OrchestrationStep Order="3" Type="ClaimsExchange">
      <Preconditions>
        <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
          <Value>identityProvider</Value>
          <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="false">
          <Value>identityProvider</Value>
          <Value>linkedin.com</Value>
          <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
      </Preconditions>
      <ClaimsExchanges>
        <ClaimsExchange Id="GetEmail" TechnicalProfileReferenceId="API-LinkedInEmail" />
      </ClaimsExchanges>
    </OrchestrationStep>
    

Obtaining the email address from LinkedIn during sign-up is optional. If you choose not to obtain the email from LinkedIn but require one during sign up, the user is required to manually enter the email address and validate it.

For a full sample of a policy that uses the LinkedIn identity provider, see the Custom Policy Starter Pack.

Migration from v1.0 to v2.0

LinkedIn recently updated their APIs from v1.0 to v2.0. As part of the migration, Azure AD B2C is only able to obtain the full name of the LinkedIn user during the sign-up. If an email address is one of the attributes that is collected during sign-up, the user must manually enter the email address and validate it.