Customize OpenID Connect scope and claims

In this document you will learn how OpenID Connect scope and claims work with Ory OAuth2 and OpenID Connect. It will also cover the default setup of Ory, which uses Ory Identities for logging in and the Ory Account Experience for getting user consent. This setup supports the email and profile OpenID Connect scopes.

The default setup of Ory OAuth2 and OpenID Connect

By default, Ory OAuth2 and OpenID Connect use Ory Identities to handle login. It also uses the Ory Account Experience to ask for user consent. This setup supports the email and profile scopes as defined by OpenID Connect.

How the email scope works

For the email scope, the system uses the verifiable addresses of a user. The first verifiable email is used to include the email in the ID token claims. This means that both email_verified and email claims get set.

How the profile scope works

For the profile scope, the system uses traits associated with a user. Here's how they map:

• identity.traits.username is used for the username claim.
• identity.traits.website is used for the website claim.
• identity.updated_at is used for the updated_at claim.

Also, the name field can be a string or an object:

• If identity.traits.name is a string, it is used for the name claim.
• If identity.traits.name is an object, traits.name.first and traits.name.last are used for the given_name and family_name traits.

Customize Scopes and Claims

Refer to the documentation about OAuth2 webhooks to learn about adding custom claims to your tokens for different OAuth flows.

For full control over the resource owner's user experience during the consent phase in the Authorizatio Code / OpenID Connect flow, check out the Ory Consent UI documentation.

Customize scope claim key

You can customize the claim key for the scope in access tokens by setting /strategies/jwt/scope_claim. The following values are supported:

• list (default): The scope claim is an array of strings named scope:

  {
    // "sub": "...",
    // ...
    scope: ["read", "write"],
    // ...
  }
• string: The scope claim is a space delimited list of strings named scp:

  {
    // "sub": "...",
    // ...
    scp: "read write",
    // ...
  }
• both: The scope claim is both a space delimited list and an array of strings named scope and scp:

  {
    // "sub": "...",
    // ...
    scope: ["read", "write"],
    scp: "read write",
    // ...
  }

To change this setting use the Ory CLI:

ory patch oauth2-config {project.id} \
  --replace '/strategies/jwt/scope_claim="string"'