# 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.

Source: https://oltinid.com/docs/guides/scopes-claims-roles/ · Section: Guides · All OneiD documentation: https://oltinid.com/llms.txt

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.

```http
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](https://oltinid.com/docs/guides/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](https://oltinid.com/docs/sign-in-sources/overview/).

ID tokens may also contain private claims whose names start with `oi_`. Ignore claims you do not know. The full list is in [Claims](https://oltinid.com/docs/reference/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](https://oltinid.com/docs/guides/protect-an-api/#use-one-scope-per-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.

## Consent and granted scopes

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](https://oltinid.com/docs/sign-in-sources/overview/#from-groups-to-roles).

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`.

```text
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

- [Claims](https://oltinid.com/docs/reference/claims/)
- [Tokens](https://oltinid.com/docs/reference/tokens/)
- [Protect an API (validate access tokens)](https://oltinid.com/docs/guides/protect-an-api/)
- [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/)