Connecting GitHub IDP

Instructions on how to connect applications registered in GitHub as Authorization Control Plane's (ACP's) Identity Providers so that you can connect a user pool from GitHub to ACP in accordance with the Bring Your Own Identity (BYOID) principle.

About GitHub as an OIDC Identity Provider

OAuth applications registered in GitHub are natively supported by ACP as OIDC Identity Providers, which means that it has a dedicated connection template in ACP, for your convenience. GitHub OAuth applications implement the OIDC protocol, providing the proof of user authentication to ACP within an ID Token and Access Token.

The client authorization flow with ACP connected to GitHub looks as follows:

[mermaid-begin]
sequenceDiagram participant Client app participant ACP participant GitHub IDP Client app->>ACP: Request authorization code ACP->>GitHub IDP: Request authorization code GitHub IDP-->>GitHub IDP: Authenticate user GitHub IDP-->>GitHub IDP: Ask user for consent to share data with ACP GitHub IDP-->>ACP: Issue authorization code ACP->>GitHub IDP: Request tokens using the code GitHub IDP-->>ACP: Issue tokens opt ACP->>GitHub IDP: Pull group information GitHub IDP-->>ACP: Send group data end opt ACP-->>ACP: Ask user for consent to share data with client app end ACP-->>Client app: Issue authorization code Client app->>ACP: Request tokens using the code ACP-->>Client app: Issue tokens requested by the app
  1. Client app requests the authorization code from ACP.

  2. ACP requests the authorization code from GitHub IDP.

  3. GitHub authenticates the user and asks for consent to share data with ACP.

  4. GitHub issues the code to ACP after user’s authentication.

  5. ACP requests tokens from GitHub using the provided code.

  6. GitHub issues the tokens to ACP.

  7. Optionally, ACP uses the token to pull user’s group membership information - only when the Fetch groups option is selected in the connector.

  8. ACP asks for user consent to share data with the client app, unless the client app is marked as trusted or the requested scopes were already granted for this app.

  9. ACP issues the authorization code to the client app.

  10. Client app requests the tokens from ACP.

  11. ACP issues the tokens to the client app. ACP tokens are minted based on the incoming GitHub tokens with claims mapped to ACP’s authentication context.

The following steps in the flow are optional:

  • ACP only pulls group information if this option is explicitly enabled in the GitHub connector configuration, as explained later in this document.
  • ACP only asks for consent if the client application is not marked as trusted and requests scopes which were not granted previously (or scopes for which the user’s consent has been withdrawn).

Prerequisites

  • You have an OAuth application registered with your GitHub account. Follow GitHub documentation for help.

    Authorization Callback URL for your GitHub application

    When prompted for the Authorization Callback URL in GitHub, use the Redirect URL from ACP once you have registered a GitHub connection in ACP.

Connect GitHub IDP

Basic configuration

  1. In your workspace, go to Identity Data > Identity Providers > Create Identity.

  2. Select the GitHub template and click Next.

  3. Use the Redirect URL as Authorization Callback URL in GitHub to complete connecting the OAuth application on GitHub side.

  4. In the Register OpenID Connect form, enter the Issuer URL, Client ID, and Client Secret.

    Parameter Description
    Name Name for your ACP’s GitHub connection. This name allows users to identify the IDP they need to authenticate with.
    Client ID Client ID of the OAuth application registered with GitHub
    Client secret Secret of OAuth application registered with GitHub
  5. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you wish to store the user’s authentication context locally. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with ACP.

  6. Select Save.

    Result

    Your new IDP connection is created. Users can now authenticate via the OIDC-compliant IDP.

Configure advanced settings

Advanced settings contain optional features which may be necessary to use in specific cases.

  1. From the Identity Data > Identity Providers > YOUR_IDENTITY > Configuration page, select Advanced settings at the bottom.

  2. In the Scopes field, add additional scopes to be returned in the IDP response after user authentication.

    Note

    Since multiple clients can use the same IDP for user authentication, you may need to further restrict specific client’s ability to request a given scope. For more information, read about Configuring applications in ACP.

  3. In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP.

    The amr object is created if it doesn’t exist. If it exists, its values are replaced with the selected item.

  4. Optionally, enable the Fetch groups option.

    Shared group data

    With this option enabled, GitHub shares organization, team membership, and private project boards with the client registered with ACP after user’s approval.

  5. Select Save.

Add custom IDP attributes

If your IDP returns custom claims outside of the standard GitHub scope, make sure to add them to the IDP connector so that they can be recognized and mapped to the authentication context.

  1. Go to Identity Data > Identity Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of attributes returned by this IDP appears.

  3. Select Add attribute.

  4. In Source, select the data source for the custom attribute

    Source Description
    Access token Get data from the access token received from the IDP
    ID token Get data from the ID token received from the IDP
    GitHub authenticated user data Get user data returned by the GitHub user API (note that this must be explicitly enabled on the IDP connector)
  5. Fill in the rest of the form.

    Option Description
    Claim name Name of your custom attribute matching the incoming IDP claim
    Display name User-friendly name for the custom attribute
    Data type Data type matching that of the incoming IDP claim

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  6. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP attributes to authentication context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Identity Data > Identity Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read Setting up authentication context.

  4. Optionally, assign a post-authentication extension to modify your authentication context before issuing the token to the client.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Test your IDP

Prerequisite

Your provider is configured as a user-authentication method by your administrator. Demo workspace is available.

Test

  1. Open the user portal.

  2. Select LOGIN TO DEMO APP.

  3. Select your configured GitHub IDP and, next, authenticate with GitHub IDP.

Result

ACP displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from IDP is delivered through the access token and the ID token generated by ACP.

Read more

For information on granting and managing ACP consents, see ACP OAuth consents.