dex/Documentation/github-connector.md

# Authentication through GitHub

## Overview

One of the login options for dex uses the GitHub OAuth2 flow to identify the end user through their GitHub account.

When a client redeems a refresh token through dex, dex will re-query GitHub to update user information in the ID Token. To do this, __dex stores a readonly GitHub access token in its backing datastore.__ Users that reject dex's access through GitHub will also revoke all dex clients which authenticated them through GitHub.

## Caveats

* The GitHub API calls dex uses requires a user to have their organization membership visibility set to public. This can be done on the ["request access from org" page][github-request-org-access] which GitHub will skip if the client app is an existing authorized application. The current workaround is as follows: the user should log into their GitHub account, go to Settings -> Authorized OAuth Apps, click 'Revoke' to revoke the application's grant, and restart the dex login process. This will force the "request access from org" page to be shown, allowing the user to request that the organization owner make their membership public.
    * Note: GitHub [organizations][github-orgs] are different from GitHub [teams][github-teams]

## Configuration

Register a new application with [GitHub][github-oauth2] ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.

The following is an example of a configuration for `examples/config-dev.yaml`:

```yaml
connectors:
- type: github
  # Required field for connector id.
  id: github
  # Required field for connector name.
  name: GitHub
  config:
    # Credentials can be string literals or pulled from the environment.
    clientID: $GITHUB_CLIENT_ID
    clientSecret: $GITHUB_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback
    # Optional organizations and teams, communicated through the "groups" scope.
    #
    # NOTE: This is an EXPERIMENTAL config option and will likely change.
    #
    # Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
    # MUST be a member of the following org to authenticate with dex.
    # org: my-organization
    #
    # Dex queries the following organizations for group information if the
    # "groups" scope is provided. Group claims are formatted as "(org):(team)".
    # For example if a user is part of the "engineering" team of the "coreos"
    # org, the group claim would include "coreos:engineering".
    #
    # A user MUST be a member of at least one of the following orgs to
    # authenticate with dex.
    orgs:
    - name: my-organization
      # Include all teams as claims.
    - name: my-organization-with-teams
      # A white list of teams. Only include group claims for these teams.
      teams:
      - read-team
      - blue-team
```

## GitHub Enterprise

Users can use their GitHub Enterprise account to login to dex. The following configuration can be used to enable a GitHub Enterprise connector on dex:

```yaml
connectors:
- type: github
  # Required field for connector id.
  id: github
  # Required field for connector name.
  name: GitHub
  config:
    # Required fields. Dex must be pre-registered with GitHub Enterprise
    # to get the following values.
    # Credentials can be string literals or pulled from the environment.
    clientID: $GITHUB_CLIENT_ID
    clientSecret: $GITHUB_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback
    # Optional organizations and teams, communicated through the "groups" scope.
    #
    # NOTE: This is an EXPERIMENTAL config option and will likely change.
    #
    # Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
    # MUST be a member of the following org to authenticate with dex.
    # org: my-organization
    #
    # Dex queries the following organizations for group information if the
    # "groups" scope is provided. Group claims are formatted as "(org):(team)".
    # For example if a user is part of the "engineering" team of the "coreos"
    # org, the group claim would include "coreos:engineering".
    #
    # A user MUST be a member of at least one of the following orgs to
    # authenticate with dex.
    orgs:
    - name: my-organization
      # Include all teams as claims.
    - name: my-organization-with-teams
      # A white list of teams. Only include group claims for these teams.
      teams:
      - read-team
      - blue-team
    # Required ONLY for GitHub Enterprise.
    # This is the Hostname of the GitHub Enterprise account listed on the
    # management console. Ensure this domain is routable on your network.
    hostName: git.example.com
    # ONLY for GitHub Enterprise. Optional field.
    # Used to support self-signed or untrusted CA root certificates.
    rootCA: /etc/dex/ca.crt
```

[github-oauth2]: https://github.com/settings/applications/new
[github-orgs]: https://developer.github.com/v3/orgs/
[github-teams]: https://developer.github.com/v3/orgs/teams/
[github-request-org-access]: https://help.github.com/articles/requesting-organization-approval-for-oauth-apps/