pomerium/docs/docs/identity-providers/github.md

title	lang	meta
GitHub	en-US	name content keywords github oauth2 provider identity-provider

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 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. :::

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 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.

   

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:

:::: tabs ::: tab config.yaml

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)

::: ::: tab Environment Variables

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: