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:

NameDescription
openidRequired scope for all login requests.
emailID token claims should include the end user’s email and if that email was verified by an upstream provider.
profileID token claims should include the username of the end user.
groupsID token claims should include a list of groups the end user is a member of.
federated:idID token claims should include information from the ID provider. The token will contain the connector ID and the user ID assigned at the provider.
offline_accessToken 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.

NameDescription
groupsA list of strings representing the groups a user is a member of.
federated_claimsThe connector ID and the user ID assigned to the user at the provider.
emailThe email of the user.
email_verifiedIf the upstream provider has verified the email.
nameUser’s display name.

The federated_claims claim has the following format:

  1. "federated_claims": {
  2. "connector_id": "github",
  3. "user_id": "110272483197731336751"
  4. }

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:

  1. staticClients:
  2. - id: web-app
  3. redirectURIs:
  4. - 'https://web-app.example.com/callback'
  5. name: 'Web app'
  6. secret: web-app-secret
  7. - id: cli-app
  8. redirectURIs:
  9. - 'https://cli-app.example.com/callback'
  10. name: 'Command line tool'
  11. secret: cli-app-secret
  12. # The command line tool lets the web app issue ID tokens on its behalf.
  13. trustedPeers:
  14. - 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.

  1. audience:server:client_id:cli-app

The ID token claims will then include the following audience and authorized party:

  1. {
  2. "aud": "cli-app",
  3. "azp": "web-app",
  4. "email": "foo@bar.com",
  5. // other claims...
  6. }

Public clients

Public clients are inspired by Google’s “Installed Applications”and are meant to impose restrictions on applications that don’t intend to keep their client secret private. Clients can be declared as public using the public config option.

  1. staticClients:
  2. - id: cli-app
  3. public: true
  4. name: 'CLI app'
  5. secret: cli-app-secret

Instead of traditional redirect URIs, public clients are limited to either redirects that begin with “http://localhost” or a special “out-of-browser” URL “urn:ietf:wg:oauth:2.0:oob”. The latter triggers dex to display the OAuth2 code in the browser, prompting the end user to manually copy it to their app. It’s the client’s responsibility to either create a screen or a prompt to receive the code, then perform a code exchange for a token response.

When using the “out-of-browser” flow, an ID Token nonce is strongly recommended.