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

  • A user must explicitly requestan organizationgive dex resource access. Dex will not have the correct permissions to determine if the user is in that organization otherwise, and the user will not be able to log in. This request mechanism is a feature of the GitHub API.

Configuration

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

  1. connectors:
  2. - type: github
  3.   # Required field for connector id.
  4.   id: github
  5.   # Required field for connector name.
  6.   name: GitHub
  7.   config:
  8.     # Credentials can be string literals or pulled from the environment.
  9.     clientID: $GITHUB_CLIENT_ID
  10.     clientSecret: $GITHUB_CLIENT_SECRET
  11.     redirectURI: http://127.0.0.1:5556/dex/callback
  13.     # Optional organizations and teams, communicated through the "groups" scope.
  14.     #
  15.     # NOTE: This is an EXPERIMENTAL config option and will likely change.
  16.     #
  17.     # Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
  18.     # MUST be a member of the following org to authenticate with dex.
  19.     # org: my-organization
  20.     #
  21.     # Dex queries the following organizations for group information if the
  22.     # "groups" scope is provided. Group claims are formatted as "(org):(team)".
  23.     # For example if a user is part of the "engineering" team of the "coreos"
  24.     # org, the group claim would include "coreos:engineering".
  25.     #
  26.     # If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to
  27.     # authenticate with dex.
  28.     #
  29.     # If neither 'org' nor 'orgs' are specified in the config and 'loadAllGroups' setting set to true then user
  30.     # authenticate with ALL user's Github groups. Typical use case for this setup:
  31.     # provide read-only access to everyone and give full permissions if user has 'my-organization:admins-team' group claim.  
  32.     orgs:
  33.     - name: my-organization
  34.       # Include all teams as claims.
  35.     - name: my-organization-with-teams
  36.       # A white list of teams. Only include group claims for these teams.
  37.       teams:
  38.       - red-team
  39.       - blue-team
  40.     # Flag which indicates that all user groups and teams should be loaded.
  41.     loadAllGroups: false
  43.     # Optional choice between 'name' (default), 'slug', or 'both'.
  44.     #
  45.     # As an example, group claims for member of 'Site Reliability Engineers' in
  46.     # Acme organization would yield:
  47.     #   - ['acme:Site Reliability Engineers'] for 'name'
  48.     #   - ['acme:site-reliability-engineers'] for 'slug'
  49.     #   - ['acme:Site Reliability Engineers', 'acme:site-reliability-engineers'] for 'both'
  50.     teamNameField: slug
  51.     # flag which will switch from using the internal GitHub id to the users handle (@mention) as the user id.
  52.     # It is possible for a user to change their own user name but it is very rare for them to do so
  53.     useLoginAsID: false

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:

  1. connectors:
  2. - type: github
  3.   # Required field for connector id.
  4.   id: github
  5.   # Required field for connector name.
  6.   name: GitHub
  7.   config:
  8.     # Required fields. Dex must be pre-registered with GitHub Enterprise
  9.     # to get the following values.
  10.     # Credentials can be string literals or pulled from the environment.
  11.     clientID: $GITHUB_CLIENT_ID
  12.     clientSecret: $GITHUB_CLIENT_SECRET
  13.     redirectURI: http://127.0.0.1:5556/dex/callback
  14.     # Optional organizations and teams, communicated through the "groups" scope.
  15.     #
  16.     # NOTE: This is an EXPERIMENTAL config option and will likely change.
  17.     #
  18.     # Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
  19.     # MUST be a member of the following org to authenticate with dex.
  20.     # org: my-organization
  21.     #
  22.     # Dex queries the following organizations for group information if the
  23.     # "groups" scope is provided. Group claims are formatted as "(org):(team)".
  24.     # For example if a user is part of the "engineering" team of the "coreos"
  25.     # org, the group claim would include "coreos:engineering".
  26.     #
  27.     # A user MUST be a member of at least one of the following orgs to
  28.     # authenticate with dex.
  29.     orgs:
  30.     - name: my-organization
  31.       # Include all teams as claims.
  32.     - name: my-organization-with-teams
  33.       # A white list of teams. Only include group claims for these teams.
  34.       teams:
  35.       - red-team
  36.       - blue-team
  37.     # Required ONLY for GitHub Enterprise.
  38.     # This is the Hostname of the GitHub Enterprise account listed on the
  39.     # management console. Ensure this domain is routable on your network.
  40.     hostName: git.example.com
  41.     # ONLY for GitHub Enterprise. Optional field.
  42.     # Used to support self-signed or untrusted CA root certificates.
  43.     rootCA: /etc/dex/ca.crt

Generate TLS assets

Running Dex with HTTPS enabled requires a valid SSL certificate, and the API server needs to trust the certificate of the signing CA using the --oidc-ca-file flag.

For our example use case, the TLS assets can be created using the following command:

  1. $ ./examples/k8s/gencert.sh

This will generate several files under the ssl directory, the important ones being cert.pem ,key.pem and ca.pem. The generated SSL certificate is for ‘dex.example.com’, although you could change this by editing gencert.sh if required.

Run example client app with Github config

  1. ./bin/example-app --issuer-root-ca examples/k8s/ssl/ca.pem
  1. Open browser to http://127.0.0.1:5555
  2. Click Login
  3. Select Log in with GitHub and grant access to dex to view your profile