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.
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
Log in to Github or create an account.
Navigate to your profile using the avatar on the navigation bar, and select Settings:
Navigate to Developer settings ➞ OAuth Apps and select New OAuth App.
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.
- 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
Create a new token at github.com/settings/tokens/new.
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:
- config.yaml
- 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)
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: