How to register a scope — Versola Docs
/docs
Pre-1.00.7.5versola.ioGitHub
RUEN

How to register a scope

Create a scope and its claims in the Versola admin console, then grant it to a client

A scope is a named bundle of claims that a client can request about a user. This page creates one in the admin console and grants it to a client. You need a tenant. For the fields and rules, see Scope.

Prerequisites

  • A tenant, selected in the tenant switcher of the console.
  • The claims the scope should release, each with a short description for the consent screen.

1. Open Scopes

Open Scopes under the tenant. The page is titled OAuth Scopes. Each card shows the description and the scope ID. Expand a card to see its claims.

Scopes of the selected tenant, with a search by ID
OAuth Scopes page listing scopes.
The openid scope expanded: it releases the sub claim
Scope expanded to show its claims.

2. Start a new scope

Press + Create Scope.

Create New Scope: scope ID, description and claims
Empty Create New Scope form.

3. Fill in the scope

  1. Scope ID: lowercase letters, digits and underscores, starting with a letter, for example payments_export. Colons, dots and hyphens are rejected, so payments:export is not a valid scope ID. You cannot change the ID later.
  2. Description: the text the user sees on the consent screen. The tabs under the field, en and ru here, are the languages active in Locales on System settings. English is required.
  3. Optional claims. Type a Claim ID, the name of the user claim to release, such as email. Add its description, then press Add Claim. Repeat for each claim. Claim IDs follow the same character rules as scope IDs.
Scope ID and description filled in; no claims added yet
Create New Scope form filled in.

4. Create the scope

Press Create Scope. The scope appears in the list. If an ID or claim does not meet the rules, the Central API rejects the save and the console shows the error.

5. Grant it to a client

A scope does nothing until a client may request it. Open the client, press Edit in its Scopes section, and switch the scope on. See Client. A service app has no scopes, so use permissions for it.

Edit or delete a scope

Press the pencil on a card to change the description or the claims. The ID cannot change. The cross deletes the scope after a confirmation. Clients keep the ID in their scope lists, but it no longer releases any claim, so remove it from them too.

Next steps