Scopes, claims and roles

Request the right scopes, read the claims OneiD releases for them, and use roles from OneiD for authorisation in your application.

View as Markdown

Scopes decide what an application may ask for. Claims are the facts about the user that OneiD puts into tokens and the userinfo response. Roles are a kind of claim your application can use to decide what a user may do.

Request scopes

Send the scopes in the scope parameter of the authorisation request, separated by spaces. Include openid for every OpenID Connect sign-in.

GET /connect/authorize?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email%20roles%20orders.read
  &code_challenge=...&code_challenge_method=S256
  &state=...&nonce=... HTTP/1.1
Host: YOUR_ONEID

A client may only request scopes that an administrator allowed for it. Any other scope makes the request fail with invalid_scope. Ask your OneiD administrator which scopes your client is allowed.

There are two kinds of scope:

  • Identity scopes release claims about the user to your application.
  • API scopes grant access to an API. They appear only in the access token’s scope claim and add no claims.

Identity scopes

Scope What it releases
openid Required for OpenID Connect. Gives you an ID token with sub.
profile name, given_name, family_name, preferred_username, updated_at (a number) and idp
email email and email_verified (a boolean)
phone phone_number and phone_number_verified (a boolean)
roles role, one value per role
offline_access No claims. Asks for a refresh token; the client must also have the refresh token grant. See Refresh tokens.

Not supported OneiD has no address scope.

Where the claims go

Claim ID token Access token Userinfo
sub Always Always Always
auth_time, amr, acr Yes No No
Profile, email and phone claims When the scope is granted When the scope is granted When the scope is granted
role When roles is granted When roles is granted When roles is granted, as a JSON array

In tokens, a user with one role can have role as a single string and a user with several roles as an array. Accept both forms.

The idp claim tells you where the user signed in: local (a OneiD account), ldap (a directory) or oidc (an upstream OpenID Connect provider). See Where users come from.

ID tokens may also contain private claims whose names start with oi_. Ignore claims you do not know. The full list is in Claims.

API scopes

An administrator creates API scopes in the admin console, for example orders.read and orders.write, and allows them for the clients that call the API. OneiD has no API scopes until an administrator creates them.

Give each API its own scopes. OneiD access tokens have no aud claim, so the scope is what tells an API that a token is meant for it. See Protect an API.

Warning The scopes admin_api, admin_api_readonly and admin_console_webhooks are for OneiD’s own administration. Do not request them in your applications.

Each client either asks users for consent or does not:

  • Consent asked. OneiD shows a consent page that lists the scopes. The user can untick optional scopes. If the user ticks “remember”, OneiD does not ask again for the same set of scopes.
  • Consent not asked. Typical for your organisation’s own applications. OneiD still shows the consent page when the request contains prompt=consent.

If the user refuses consent, your application receives access_denied at the redirect URI.

Because the user can untick scopes, you may receive fewer scopes than you asked for. Read the scope field of the token response to see what was granted, and let your application work with less. For example, if email was not granted, ask the user for an email address instead of failing.

Roles

A role is a name such as OrderViewer that OneiD puts in the role claim. Roles come from one of two places, depending on the sign-in source of your OneiD deployment:

  • Assigned in OneiD. An administrator creates roles and assigns them to users in the admin console.
  • Mapped from groups. With LDAP or Active Directory, or an upstream OpenID Connect provider, OneiD turns the user’s groups into roles through a mapping your administrator configures. See Where users come from.

To receive roles, the client must be allowed the roles scope and request it.

Use roles for authorisation

  • In a web application, read role from the ID token after sign-in and store the roles in your application session.
  • In an API, read role from the access token.
  • Map OneiD role names to your own permissions in one place in your code. Do not scatter role-name checks across the code base.
  • A token keeps the roles it was issued with. When an administrator removes a role, OneiD revokes the user’s tokens in its store, so refresh tokens stop working. An API that validates access tokens locally still accepts an access token that was already issued until it expires.

OneiD has built-in administrator roles such as All and UserManager. They control OneiD’s admin console. Do not reuse them as roles in your own application; ask for application roles instead.

The claims parameter

OneiD supports the OpenID Connect claims request parameter for the id_token and userinfo members. OneiD reads the claim names. It ignores essential, value and values.

claims={"id_token":{"email":null,"preferred_username":null}}

URL-encode the JSON when you send it. OneiD only releases claims that belong to scopes the client is allowed and the user consented to; the claims parameter cannot release more. Since scope-released claims already appear in the ID token, most applications do not need this parameter.

Identify users by issuer and subject

Use iss and sub together as the key for a user in your database.

  • sub is stable and opaque. Do not parse it. Its format depends on the sign-in source: an opaque OneiD user ID for OneiD accounts, the directory account name in lower case, without the domain, for LDAP, and the provider’s own sub for an upstream OpenID Connect provider.
  • Do not use email as a key. An email address can change and can be reused.
  • Before you treat an email address as belonging to the user, check that email_verified is true.
  • iss ends with a slash: https://YOUR_ONEID/. Store it as it appears in the token.

Learn more