diff --git a/docs/docs/identity-providers/cognito.md b/docs/docs/identity-providers/cognito.md index 1c4792fdb..f8a05da36 100644 --- a/docs/docs/identity-providers/cognito.md +++ b/docs/docs/identity-providers/cognito.md @@ -9,6 +9,8 @@ meta: # AWS Cognito +This document describes the use of AWS Cognito as an identity provider with Pomerium. + ## Setting up AWS Cognito Log in to the [AWS Console](https://console.aws.amazon.com) account. diff --git a/docs/docs/identity-providers/github.md b/docs/docs/identity-providers/github.md index e61412f7f..9f6a387a1 100644 --- a/docs/docs/identity-providers/github.md +++ b/docs/docs/identity-providers/github.md @@ -9,23 +9,28 @@ meta: # GitHub -## Setting up GitHub OAuth2 for your Application +This document describes the use of GitHub as an identity provider for Pomerium. -We would like you to be aware that GitHub did not implement the OpenID Connect just OAuth2 and for this reason, we have not gotten a better way to implement revocation of user access on sign out yet. +Before we proceed, please be aware that [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 dashboard. -Also, the organizations a user belongs to will be used as the groups on Pomerium dashboard. +In addition, the teams of the organization(s) a user belongs to, will be used as groups on Pomerium. -Log in to [Github](https://github.com/login) or create an account. +## Setting up GitHub OAuth 2.0 for your Application -Navigate to your profile using the avatar on the navigation bar and go to your settings. +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. + +3. Go to your settings. ![GitHub settings](./img/github/github-user-profile.png) -Click the Developers settings and create a new OAuth Application +4. Click the Developers settings and create a new OAuth Application. ![GitHub OAuth2 Application creation](./img/github/github-oauth-creation.png) -Create a new OAuth2 application by filling the field with the following parameters: +5. Create a new OAuth2 application by filling the form fields above with the following parameters: Field | Description --------------------------- | -------------------------------------------- @@ -36,9 +41,10 @@ Authorization callback URL | `https://${authenticate_service_url}/oauth2/callba After the application had been created, you will have access to the credentials, the **Client ID** and **Client Secret**. + ## Pomerium Configuration -If the setup for GitHub OAuth application has been completed, you can create your **Pomerium** configuration like the example below: +After creating your GitHub OAuth application, you can create your **Pomerium** configuration like the example below: ```bash authenticate_service_url: https://authenticate.localhost.pomerium.io @@ -50,3 +56,7 @@ 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](./img/github/github-signon-page.png) + +[Github API]: https://developer.github.com/v3/#oauth2-token-sent-in-a-header +[openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect +[OAuth 2.0]: https://auth0.com/docs/protocols/oauth2 diff --git a/docs/docs/identity-providers/gitlab.md b/docs/docs/identity-providers/gitlab.md index e6e97e4df..4c2479505 100644 --- a/docs/docs/identity-providers/gitlab.md +++ b/docs/docs/identity-providers/gitlab.md @@ -9,13 +9,17 @@ meta: # GitLab -Log in to your GitLab account or create one [here](https://gitlab.com/users/sign_in) +This document describes the use of GitLab as an identity provider with Pomerium. -Go to the user settings which can be found in the user profile to [create an application](https://gitlab.com/profile/applications) where you will get your app credentials +## Setting up GitLab OAuth2 for your Application + +1. Log in to your GitLab account or create one [here](https://gitlab.com/users/sign_in). + +2. Go to the user settings which can be found in the user profile to [create an application](https://gitlab.com/profile/applications) like below: ![create an application](./img/gitlab/gitlab-create-applications.png) -On the **Applications** page, add a new application by setting the following parameters: +3. Add a new application by setting the following parameters: Field | Description ------------ | -------------------------------------------- @@ -23,13 +27,15 @@ Name | The name of your web app Redirect URI | `https://${authenticate_service_url}/oauth2/callback` Scopes | **Must** select **read_user** and **openid** -[Group ID](https://docs.gitlab.com/ee/api/groups.html#details-of-a-group) will be used to affirm group(s) a user belongs to. -Your `Client ID` and `Client Secret` will be displayed: +Your `Client ID` and `Client Secret` will be displayed like below: ![Gitlab OAuth Client ID and Secret](./img/gitlab/gitlab-credentials.png) -Set `Client ID` and `Client Secret` in Pomerium's settings. Your environment variables should look something like this. +4. Set `Client ID` and `Client Secret` in Pomerium's settings. + + +Your configuration should look like the following example: ```bash authenticate_service_url: https://authenticate.localhost.pomerium.io @@ -38,6 +44,8 @@ idp_client_id: "REDACTED" // gitlab application ID idp_client_secret: "REDACTED" // gitlab application secret ``` -When a user first uses pomerium to login, they will be presented with an authorization screen similar to the following depending on the scope parameters setup. +When a user first uses pomerium to login, they will be presented with an authorization screen similar to the following depending on the scope parameters setup: ![gitlab access authorization screen](./img/gitlab/gitlab-verify-access.png) + +Please be aware that [Group ID](https://docs.gitlab.com/ee/api/groups.html#details-of-a-group) will be used to affirm group(s) a user belongs to.