diff --git a/docs/docs/identity-providers/github.md b/docs/docs/identity-providers/github.md index 970c348a5..56e4ec449 100644 --- a/docs/docs/identity-providers/github.md +++ b/docs/docs/identity-providers/github.md @@ -9,65 +9,83 @@ meta: # GitHub -This document describes the use of GitHub as an identity provider for Pomerium. +This document describes the use of GitHub as an identity provider for Pomerium. It assumes you have already [installed Pomerium](/docs/install/readme.md) -Before we proceed, please be aware that [GitHub API] does not support [OpenID Connect], just [OAuth 2.0]. +::: 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. -## Setting up GitHub OAuth 2.0 for your Application +## Create a GitHub OAuth 2.0 Application 1. Log in to [Github](https://github.com/login) or create an account. -2. Navigate to your profile using the avatar on the navigation bar. +1. Navigate to your profile using the avatar on the navigation bar, and select **Settings**: -3. Go to your settings. +1. Navigate to **Developer settings ➞ OAuth Apps** and select **New OAuth App**. -![GitHub settings](./img/github/github-user-profile.png) + ![GitHub OAuth2 Application creation](./img/github/github-oauth-creation.png) -4. Click the Developers settings and create a new OAuth Application. +1. Create a new OAuth2 application by filling the form fields above with the following parameters: -![GitHub OAuth2 Application creation](./img/github/github-oauth-creation.png) - -5. 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 pomerium configuration + | 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 the application had been created, you will have access to the credentials, the **Client ID** and **Client Secret**. +1. After creating the application, select **Generate a new client secret** and save **Client Secret** along with the **Client ID**. -## 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, which can be created at [github.com/settings/tokens/new](https://github.com/settings/tokens/new). +## Create a Service Account -![Personal Access Token](./img/github/github-personal-access-token.png) +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 -The format of the `idp_service_account` for GitHub is a base64-encoded JSON document: +1. Create a new token at [github.com/settings/tokens/new](https://github.com/settings/tokens/new). -```json -{ - "username": "YOUR_GITHUB_USERNAME", - "personal_access_token": "GENERATED_GITHUB_ACCESS_TOKEN" -} -``` + ![Personal Access Token](./img/github/github-personal-access-token.png) + +1. The format of the `idp_service_account` for GitHub is a base64-encoded JSON document: + + ```json + { + "username": "YOUR_GITHUB_USERNAME", + "personal_access_token": "GENERATED_GITHUB_ACCESS_TOKEN" + } + ``` + + You can save the object as a temporary file to encode: + + ```bash + cat tmp.json | base64 -w 0 + ``` ## Pomerium Configuration -After creating your GitHub OAuth application, you can create your **Pomerium** configuration like the example below: +After creating your GitHub OAuth application, update the **Pomerium** configuration: +:::: tabs +::: tab config.yaml ```bash -authenticate_service_url: https://authenticate.localhost.pomerium.io idp_provider: "github" -idp_client_id: "REDACTED" // github application ID +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 +```bash +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: +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](./img/github/github-signon-page.png) diff --git a/docs/docs/identity-providers/img/github/github-personal-access-token.png b/docs/docs/identity-providers/img/github/github-personal-access-token.png index 083e24b43..432c0f9fa 100644 Binary files a/docs/docs/identity-providers/img/github/github-personal-access-token.png and b/docs/docs/identity-providers/img/github/github-personal-access-token.png differ diff --git a/docs/docs/identity-providers/img/github/github-user-profile.png b/docs/docs/identity-providers/img/github/github-user-profile.png deleted file mode 100644 index a5b41d660..000000000 Binary files a/docs/docs/identity-providers/img/github/github-user-profile.png and /dev/null differ