This repository has been archived on 2023-08-14. You can view files and clone it, but cannot push or open issues or pull requests.
dex/Documentation/github-connector.md
Eric Stroczynski 26527011ab connector/github: enable private, primary emails; refactor API calls
Documentation: removed private emails caveats section
2017-08-08 18:04:34 -07:00

4.1 KiB

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.

Configuration

Register a new application with GitHub 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:

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:

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