GitHub

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

WARNING

The GitHub API (opens new window) does not support OpenID Connect (opens new window), just OAuth 2.0 (opens new window). 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.

In addition, the teams of the organization(s) a user belongs to, will be used as groups on Pomerium.

Create a GitHub OAuth 2.0 Application

1. Log in to Github (opens new window) 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.

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

   Field	Description
   Application name	The name of your web app.
   Homepage URL	The homepage URL of the application to be integrated with Pomerium.
   Authorization callback URL	https://${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.

Create a Service Account

To use allowed_groups in a policy, an idp_service_account needs to be set in the Pomerium configuration. The Service Account for GitHub should be a personal access token with read:org permissions

1. Create a new token at github.com/settings/tokens/new (opens new window).

   

2. The format of the idp_service_account for GitHub is a base64-encoded JSON document:

   {
   "username": "YOUR_GITHUB_USERNAME",
   "personal_access_token": "GENERATED_GITHUB_ACCESS_TOKEN"
   }
   

   You can save the object as a temporary file to encode:

   cat tmp.json | base64 -w 0
   

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
idp_service_account: "REDACTED" // github service account (personal access token)

IDP_PROVIDER="github"
IDP_CLIENT_ID="REDACTED"       // github application ID
IDP_CLIENT_SECRET="REDACTED"   // github application secret
IDP_SERVICE_ACCOUNT="REDACTED" // github service account (personal access token)

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