dex/Documentation/custom-scopes-claims-clients.md

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. Doesn't work in combinations with some connectors, notability the SAML connector ignores this scope.
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, and a handful of 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:

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...
}