Skip to content

identity-provider-github.md

Latest commit

 

History

History
228 lines (175 loc) · 12.1 KB

identity-provider-github.md

File metadata and controls

228 lines (175 loc) · 12.1 KB
title Set up sign-up and sign-in with a GitHub account
titleSuffix Azure AD B2C
description Provide sign-up and sign-in to customers with GitHub accounts in your applications using Azure Active Directory B2C.
author garrodonnell
manager CelesteDG
ms.service azure-active-directory
ms.topic how-to
ms.date 03/10/2022
ms.author godonnell
ms.subservice b2c
zone_pivot_groups b2c-policy-type

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

[!INCLUDE active-directory-b2c-end-of-sale-notice-b]

[!INCLUDE active-directory-b2c-choose-user-flow-or-custom-policy]

::: zone pivot="b2c-user-flow"

[!INCLUDE active-directory-b2c-public-preview]

::: zone-end

::: zone pivot="b2c-custom-policy"

Important

Starting May 2021, GitHub announced a change that impacts your Azure AD B2C custom policy federation. Due to the change, add <Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item> metadata to your GitHub technical profile. For more information, see Deprecating API authentication through query parameters.

::: zone-end

Prerequisites

[!INCLUDE active-directory-b2c-customization-prerequisites]

Create a GitHub OAuth application

To enable sign-in with a GitHub account in Azure Active Directory B2C (Azure AD B2C), you need to create an application in GitHub Developer portal. For more information, see Creating an OAuth App. If you don't already have a GitHub account, you can sign up at https://www.github.com/.

  1. Sign in to the GitHub Developer with your GitHub credentials.
  2. Select OAuth Apps and then select New OAuth App.
  3. Enter an Application name and your Homepage URL.
  4. For the Authorization callback 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-domain-name with your custom domain, and your-tenant-name with the name of your tenant. Use all lowercase letters when entering your tenant name even if the tenant is defined with uppercase letters in Azure AD B2C.
  5. Click Register application.
  6. Copy the values of Client ID and Client Secret. You need both to add the identity provider to your tenant.

::: zone pivot="b2c-user-flow"

Configure GitHub as an identity provider

  1. Sign in to the Azure portal with an account that has at least External Identity Provider Administrator privileges.
  2. 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.
  3. Choose All services in the top-left corner of the Azure portal, search for and select Azure AD B2C.
  4. Select Identity providers, then select GitHub (Preview).
  5. Enter a Name. For example, GitHub.
  6. For the Client ID, enter the Client ID of the GitHub application that you created earlier.
  7. For the Client secret, enter the Client Secret that you recorded.
  8. Select Save.

Add GitHub identity provider to a user flow

At this point, the GitHub identity provider has been set up, but it's not yet available in any of the sign-in pages. To add the GitHub 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 GitHub identity provider.
  3. Under the Social identity providers, select GitHub.
  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 GitHub to sign in with GitHub 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.

::: zone-end

::: zone pivot="b2c-custom-policy"

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. 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.
  3. Choose All services in the top-left corner of the Azure portal, and then search for and select Azure AD B2C.
  4. On the Overview page, select Identity Experience Framework.
  5. Select Policy Keys and then select Add.
  6. For Options, choose Manual.
  7. Enter a Name for the policy key. For example, GitHubSecret. The prefix B2C_1A_ is added automatically to the name of your key.
  8. In Secret, enter your client secret that you previously recorded.
  9. For Key usage, select Signature.
  10. Click Create.

Configure GitHub as an identity provider

To enable users to sign in using a GitHub 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.

You can define a GitHub account as a claims provider by adding it to the ClaimsProviders 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>github.com</Domain>
  <DisplayName>GitHub</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="GitHub-OAuth2">
      <DisplayName>GitHub</DisplayName>
      <Protocol Name="OAuth2" />
      <Metadata>
        <Item Key="ProviderName">github.com</Item>
        <Item Key="authorization_endpoint">https://github.com/login/oauth/authorize</Item>
        <Item Key="AccessTokenEndpoint">https://github.com/login/oauth/access_token</Item>
        <Item Key="ClaimsEndpoint">https://api.github.com/user</Item>
        <Item Key="HttpBinding">GET</Item>
        <Item Key="scope">read:user user:email</Item>
        <Item Key="UsePolicyInRedirectUri">0</Item>
        <Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>  
        <Item Key="UserAgentForClaimsExchange">CPIM-Basic/{tenant}/{policy}</Item>
        <!-- Update the Client ID below to the Application ID -->
        <Item Key="client_id">Your GitHub application ID</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_GitHubSecret"/>
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="email" />
        <OutputClaim ClaimTypeReferenceId="numericUserId" PartnerClaimType="id" />
        <OutputClaim ClaimTypeReferenceId="issuerUserId" />
        <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="github.com" AlwaysUseDefaultValue="true" />
        <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" AlwaysUseDefaultValue="true" />
      </OutputClaims>
      <OutputClaimsTransformations>
        <OutputClaimsTransformation ReferenceId="CreateIssuerUserId" />
        <OutputClaimsTransformation ReferenceId="CreateRandomUPNUserName"/>
        <OutputClaimsTransformation ReferenceId="CreateUserPrincipalName"/>
        <OutputClaimsTransformation ReferenceId="CreateAlternativeSecurityId"/>
        <OutputClaimsTransformation ReferenceId="CreateSubjectClaimFromAlternativeSecurityId"/>
      </OutputClaimsTransformations>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-SocialLogin" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

  4. Set client_id to the application ID from the application registration.

  5. Save the file.

Add the claims transformations

The GitHub technical profile requires the CreateIssuerUserId claim 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 numericUserId.

  1. Search for the BuildingBlocks element. If the element doesn't exist, add it.
  2. Locate the ClaimsSchema element. If the element doesn't exist, add it.
  3. Add the numericUserId claim to the ClaimsSchema element.
  4. Locate the ClaimsTransformations element. If the element doesn't exist, add it.
  5. Add the CreateIssuerUserId claims transformations to the ClaimsTransformations element.
<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="numericUserId">
      <DisplayName>Numeric user Identifier</DisplayName>
      <DataType>long</DataType>
    </ClaimType>
  </ClaimsSchema>
  <ClaimsTransformations>
    <ClaimsTransformation Id="CreateIssuerUserId" TransformationMethod="ConvertNumberToStringClaim">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="numericUserId" TransformationClaimType="inputClaim" />
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="issuerUserId" TransformationClaimType="outputClaim" />
      </OutputClaims>
    </ClaimsTransformation>
  </ClaimsTransformations>
</BuildingBlocks>

[!INCLUDE active-directory-b2c-add-identity-provider-to-user-journey]

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

<OrchestrationStep Order="2" Type="ClaimsExchange">
  ...
  <ClaimsExchanges>
    <ClaimsExchange Id="GitHubExchange" TechnicalProfileReferenceId="GitHub-OAuth2" />
  </ClaimsExchanges>
</OrchestrationStep>

[!INCLUDE active-directory-b2c-configure-relying-party-policy]

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

Next steps

::: zone-end