Connecting GitHub IDP

Instructions on how to configure GitHub as IDP

Purpose

Enable users to log in to ACP and applications with a GitHub identity provider (IDP).

Prerequisites

You have a GitHub account.

Create GitHub application

  1. Go to the GitHub portal and sign in to your account.

  2. From the top right corner, select the profile photo icon, and next, Settings from the dropdown list.

  3. From the left sidebar, select Developer settings.

  4. In the Developer settings view, select OAuth Apps from the left sidebar, and next, New OAuth App from the top left corner.

    Note

    If you haven’t had any OAuth applications with GitHub by now, select Register a new application.

  5. In the Register a new OAuth application view

    1. Enter the required details for your application: name, description, homepage URL.

    2. Leave out Authorization callback URL for now. You’ll be back here when you get to steps 4-6 of Connect GitHub IDP in this instruction.

  6. Keep the Register a new OAuth application tab open in your browser so that you can come back to it as soon as you retrieve the authorization callback URL in the subsequent steps.

Connect GitHub IDP

  1. Go to https://localhost:8443/app/default/admin for the ACP administrator portal and log in with your credentials.

    Result

    The administrator portal is displayed.

  2. Make sure you are in the Consumer workspace (selectable from the left sidebar) and select ADD IDENTITIES to add a new connection.

    Result

    The pop-up dialog box shows and lists available predefined IDP templates.

  3. Select the GitHub template, enter the name for your new identity provider, and click Next.

    Result

    The Register GitHub fill-in form opens with blanks for details on your GitHub IDP.

  4. Copy the redirect URL provided in the Register GitHub fill-in form.

  5. Go back to the GitHub portal and the Register a new OAuth application view (see step 5.2 in Create GitHub application).

  6. Paste the copied redirect URL (from the ACP administrator portal) into the Authorization callback URL field for your OAuth application (in the GitHub portal) and select Register application.

    Result

    Your OAuth application in the GitHub portal has been created successfully and its details are displayed, including its client secret and client ID.

  7. Copy your application client secret and client ID (so that you can paste it into the Register GitHub fill-in form in the ACP administrator portal in the subsequent step).

  8. Back in the Register GitHub fill-in form (the ACP administrator portal)

    1. Paste the copied client secret and client ID into relevant fields.

    2. Select Save.

    Result

    Your new GitHub IDP connection in the ACP administrator portal is configured and visible on the list of available IDP connections.

Advanced settings

To configure your new IDP advanced settings

  • Go to Identities in the left sidebar and select your IDP from the list of available IDP connections.

  • Make sure that you are in the CONFIGURATION view and select Advanced settings at the bottom.

  • Configure the Scopes field and decide if you want to use the Fetch groups option.

Note

If you enable the Fetch groups option, the groups attribute (authentication context attribute available from the left sidebar in AuthN Context) gets populated with user’s groups and takes form organization_id:group name.

Enable the stateful authorization

This step is optional.

To have the user’s data cached in ACP and avoid re-authenticating within one use’s session, follow the instruction in Enable the stateful authZ in ACP.

User’s test

Purpose

Test your new IDP as a user

Prerequisite

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

Test

  1. Go to https://localhost:8443/default/default/demo and select LOG IN TO DEMO APP.

  2. Select your configured IDP (if you have multiple ones) and, next, authenticate in 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.

Developer’s test

Purpose

Test your new IDP as a developer

Prerequisite

Your provider is configured as a developer-authentication method by your administrator. To register your IDP for the developer, follow instructions in Connect GitHub IDP, this time selecting the Developer workspace in step 2.

Test

  1. Go to https://localhost:8443/app/default/developer to access the ACP developer portal.

  2. Log in to your account by entering your login credentials and selecting LOG IN.

Result

You are logged in to the ACP developer portal with the newly-configured IDP.