Skip to main content

Custom OIDC Scopes

You can create custom Client Scopes which enable customising the responses your OIDC client receives.

These scopes can be used along other scopes. They can be enabled by default, or only on request. They can be requested with the scope parameter which is provided during the authorisation flow.

The scopes can be used to modify the following responses:

  • Access Token (when JWT formatted)
  • ID Token
  • Userinfo endpoint
  • Introspection endpoint

The Scopes can be configured to modify these responses in a variety of ways. The modifications are performed with Mappers which can have different effects.

Mapper types​

Currently the following mapper types are available:

  • Audience
  • Hardcoded claim
  • User Custom Field

Audience​

This mapper can add a value to a token's aud field. Possible original aud value is replaced with a list with given audience value appended to it.

The audience value is provided in the editor with the "Custom audience value" field.

Hardcoded claim​

This mapper can be used to add a claim with a hardcoded value.

Configure this mapper by providing "Claim name", "Claim value" and the type of value. The value is given as text. The type determines how it is rendered in the final JSON output.

  • Text - as a text value. Example: Hello word
  • Number (integer) - as an integer number. Example: 50
  • Number (decimal) - as a number with decimals: Example: 50.123
  • Boolean - as a true or false value. Example: true or false
  • JSON - As a JSON object, array, or other. Best effort conversion is attempted. Example: {"foo":"bar", "example":50.123} or ["value", "another"]

User Custom Field​

This mapper can place a value from User's Custom Fields into the token.

Configure the mapper by providing a "Claim name" and a "User Custom Field JSON path".

The Custom Field JSON path can be the name of the custom field if it is at the root level of custom fields. It can also be a deeper object, navigated with a provided JSON path string. Example: myfield or myfield.subfield. If such a custom field is found, the value is used as the claim value.

Configuring Client Scopes​

Configuration of Client scopes requires certain Trivore ID permissions:

  • CLIENT_SCOPE_VIEW - View Client Scopes in accessible namespaces
  • CLIENT_SCOPE_CREATE - Create new Client Scopes
  • CLIENT_SCOPE_MODIFY - Modify existing Client Scopes in accessible namespaces
  • CLIENT_SCOPE_REMOVE - Delete Client Scopes in accessible namespaces

Listing scopes​

Open the Client Scopes view in the Management UI. This view displays the Client Scopes configured in current namespace. You can manage the listed Scopes using the menu bar buttons.

Client Scopes list view

Editing scope​

The editor for a Scope has configuration fields for scope name, consent screen details, and Mappers.

Client Scope Editor

Mappers​

When adding a new Mapper, you must first choose the type of Mapper.

Mapper type selector

In the Mapper editor, you can configure type specific options, and which documents are modified by this scope.

Mapper editor

Enabling a Client Scope​

Client Scopes are enabled by adding them to the OIDC Client configuration.

Open the OIDC Client editor. In the Authorisation tab, in the "Scope" section, you can enable Client Scopes.

alt

When adding a Scope, you must select if the Scope is enabled by default, or only when requested with the scope parameter.

alt