From 6980920a3a86b976a3141be66450bbb3736ed885 Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Mon, 21 Nov 2016 16:41:06 -0800 Subject: [PATCH] *: document the GitHub connector --- Documentation/github-connector.md | 32 +++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 33 insertions(+) create mode 100644 Documentation/github-connector.md diff --git a/Documentation/github-connector.md b/Documentation/github-connector.md new file mode 100644 index 00000000..6491c78e --- /dev/null +++ b/Documentation/github-connector.md @@ -0,0 +1,32 @@ +# 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][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 + id: github + 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 organization to pull teams from, communicate through the + # "groups" scope. + # + # NOTE: This is an EXPERIMENTAL config option and will likely change. + org: my-oranization +``` + +[github-oauth2]: https://github.com/settings/applications/new diff --git a/README.md b/README.md index 64ac7ed9..454fc4d2 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Standards-based token responses allows applications to interact with any OpenID * [gRPC API](Documentation/api.md) * Identity provider logins * [LDAP](Documentation/ldap-connector.md) + * [GitHub](Documentation/github-connector.md) * Client libraries * [Go][go-oidc]