Merge pull request #883 from ericchiang/scopes-docs

Documentation: document dex scopes, claims, and client features
This commit is contained in:
Eric Chiang 2017-03-28 21:26:01 -07:00 committed by GitHub
commit 5eb8210eb4
3 changed files with 77 additions and 4 deletions

View file

@ -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

View file

@ -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

View file

@ -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)