From 5e34f0d1a6e22725b39f521178baac2cddd0a306 Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Mon, 20 Mar 2017 15:40:24 -0700 Subject: [PATCH] Documentation: document dex scopes, claims, and client features --- Documentation/custom-scopes-claims-clients.md | 71 +++++++++++++++++++ Documentation/openid-connect.md | 9 +-- README.md | 1 + 3 files changed, 77 insertions(+), 4 deletions(-) create mode 100644 Documentation/custom-scopes-claims-clients.md diff --git a/Documentation/custom-scopes-claims-clients.md b/Documentation/custom-scopes-claims-clients.md new file mode 100644 index 00000000..2c15137e --- /dev/null +++ b/Documentation/custom-scopes-claims-clients.md @@ -0,0 +1,71 @@ +# Custom scopes, claims and client features + +This document describes the set of OAuth2 and OpenID Connect features implemented by dex. + +## Scopes + +The following is the exhaustive list of scopes supported by dex: + +| Name | Description | +| ---- | ------------| +| `openid` | Required scope for all login requests. | +| `email` | ID token claims should include the end user's email and if that email was verified by an upstream provider. | +| `profile` | ID token claims should include the username of the end user. | +| `groups` | ID token claims should include a list of groups the end user is a member of. | +| `offline_access` | Token response should include a refresh token. | +| `audience:server:client_id:( client-id )` | Dynamic scope indicating that the ID token should be issued on behalf of another client. See the _"Cross-client trust and authorized party"_ section below. | + +## Custom claims + +Beyond the [required OpenID Connect claims][core-claims], and a handful of [standard claims][standard-claims], dex implements the following non-standard claims. + +| Name | Description | +| ---- | ------------| +| `groups` | A list of strings representing the groups a user is a member of. | +| `email` | The email of the user. | +| `email_verified` | If the upstream provider has verified the email. | +| `name` | User's display name. | + +## Cross-client trust and authorized party + +Dex has the ability to issue ID tokens to clients on behalf of other clients. In OpenID Connect terms, this means the ID token's `aud` (audience) claim being a different client ID than the client that performed the login. + +For example, this feature could be used to allow a web app to generate an ID token on behalf of a command line tool: + +```yaml +staticClients: +- id: web-app + redirectURIs: + - 'https://web-app.example.com/callback' + name: 'Web app' + secret: web-app-secret + +- id: cli-app + redirectURIs: + - 'https://cli-app.example.com/callback' + name: 'Command line tool' + secret: cli-app-secret + # The command line tool lets the web app issue ID tokens on its behalf. + trustedPeers: + - web-app +``` + +Note that the command line tool must explicitly trust the web app using the `trustedPeers` field. The web app can then use the following scope to request an ID token that's issued for the command line tool. + +``` +audience:server:client_id:cli-app +``` + +The ID token claims will then include the following audience and authorized party: + +``` +{ + "aud": "cli-app", + "azp": "web-app", + "email": "foo@bar.com", + // other claims... +} +``` + +[core-claims]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken +[standard-claims]: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims diff --git a/Documentation/openid-connect.md b/Documentation/openid-connect.md index 60ec35d8..2d338b8c 100644 --- a/Documentation/openid-connect.md +++ b/Documentation/openid-connect.md @@ -1,9 +1,8 @@ # An overview of OpenID Connect -This document attempts to provide an overview of the [OpenID Connect protocol]( -https://openid.net/connect/), a flavor of OAuth2 that dex implements. While -this document isn't complete we hope it provides a enough to get users up and -running. +This document attempts to provide a general overview of the [OpenID Connect protocol](https://openid.net/connect/), a flavor of OAuth2 that dex implements. While this document isn't complete, we hope it provides enough information to get users up and running. + +For an overview of custom claims, scopes, and client features implemented by dex, see [this document][scopes-claims-clients]. ## OAuth2 @@ -138,3 +137,5 @@ $ curl http://127.0.0.1:5556/keys ] } ``` + +[scopes-claims-clients]: custom-scopes-claims-clients.md diff --git a/README.md b/README.md index 10e5ec32..eae89aa4 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ More docs for running dex as a Kubernetes authenticator can be found [here](Docu * [Getting started](Documentation/getting-started.md) * [What's new in v2](Documentation/v2.md) +* [Custom scopes, claims, and client features](Documentation/custom-scopes-claims-clients.md) * [Storage options](Documentation/storage.md) * [Intro to OpenID Connect](Documentation/openid-connect.md) * [gRPC API](Documentation/api.md)