Skip to main content

GitHub

This document describes the use of GitHub as an identity provider for Pomerium. It assumes you have already installed Pomerium.

caution

The GitHub API does not support OpenID Connect, just OAuth 2.0. For this reason, it was challenging to implement revocation of a user's Access Token (a string representing the granted permissions) when they sign out from Pomerium's user info endpoint.

Create a GitHub OAuth 2.0 Application​

  1. Log in to Github or create an account.

  2. Navigate to your profile using the avatar on the navigation bar, and select Settings:

  3. Navigate to Developer settings ➞ OAuth Apps and select New OAuth App.

GitHub OAuth2 Application creation

  1. Create a new OAuth2 application by filling the form fields above with the following parameters:

    FieldDescription
    Application nameThe name of your web app.
    Homepage URLThe homepage URL of the application to be integrated with Pomerium.
    Authorization callback URLhttps://${authenticate_service_url}/oauth2/callback, authenticate_service_url from your Pomerium configuration.

  2. After creating the application, select Generate a new client secret and save Client Secret along with the Client ID.

Pomerium Configuration​

After creating your GitHub OAuth application, update the Pomerium configuration:

idp_provider: "github"
idp_client_id: "REDACTED"       // github application ID
idp_client_secret: "REDACTED"   // github application secret

Whenever a user tries to access your application integrated with Pomerium, they will be presented with a sign-on page as below:

GitHub Sign-on Page

User IDs​

Starting in version 0.34, Pomerium uses a GitHub user's node_id as their Pomerium user_id. This is the identifier used for the user PPL criterion. Prior to this Pomerium used a user's login.

To find a user's node_id, query the GitHub API:

curl -s https://api.github.com/users/USER_LOGIN | jq -r .node_id

It will be a base64-encoded string.

Getting Groups​

Custom Claim (Open Source)​

The GitHub API does not support OpenID Connect, just OAuth 2.0 and it is not possible to get groups using a custom identity (id_token) claim. A full directory sync is required.