# Claims

> Look up every claim OneiD issues, where it appears, which scope releases it, and how to use the claims request parameter.

Source: https://oltinid.com/docs/reference/claims/ · Section: Reference · All OneiD documentation: https://oltinid.com/llms.txt

A claim is a piece of information about the user or the token, such as `sub` or `email`. Which claims your application receives depends on the scopes the client is allowed, the scopes it requests and what the user consents to. This page lists every claim and where it appears.

## All claims

| Claim | Type | In ID token | In access token | In userinfo | Released by | Description |
|---|---|---|---|---|---|---|
| `iss` | string | Yes | Yes | No | Always | The issuer, `https://YOUR_ONEID/`, with the trailing slash. |
| `sub` | string | Yes | Yes | Yes | Always | The user's identifier. For the client credentials grant, the client ID. See [sub formats](#sub-formats). |
| `aud` | string | Yes | No | No | Always | Your client ID. Access tokens have no `aud`. |
| `exp` | number | Yes | Yes | No | Always | Expiry time, in seconds since the Unix epoch. |
| `iat` | number | Yes | Yes | No | Always | Issue time, in seconds since the Unix epoch. |
| `nonce` | string | Yes | No | No | The `nonce` request parameter | Copied from the authorisation request. |
| `auth_time` | number | Yes | No | No | Always | When the user last signed in, in seconds since the Unix epoch. |
| `amr` | array of strings | Yes | No | No | Always | How the user signed in. See [amr values](#amr-values). |
| `acr` | string | Yes | No | No | Always | The authentication level, derived from `amr`. See [acr values](#acr-values). |
| `scope` | string | No | Yes | No | Always | The granted scopes, separated by spaces. |
| `client_id` | string | No | Yes | No | Always | The client the access token was issued to. |
| `name` | string | Yes | Yes | Yes | `profile` | The user's full name. In a client credentials token, the client's display name. |
| `given_name` | string | Yes | Yes | Yes | `profile` | First name. |
| `family_name` | string | Yes | Yes | Yes | `profile` | Last name. |
| `preferred_username` | string | Yes | Yes | Yes | `profile` | The user name. Do not use it as a key. |
| `updated_at` | number | Yes | Yes | Yes | `profile` | When the user's profile was last updated, in seconds since the Unix epoch. |
| `idp` | string | Yes | Yes | Yes | `profile` | Where the user signed in. See [idp values](#idp-values). |
| `email` | string | Yes | Yes | Yes | `email` | Email address. Do not use it as a key. |
| `email_verified` | boolean | Yes | Yes | Yes | `email` | Whether the email address is verified. |
| `phone_number` | string | Yes | Yes | Yes | `phone` | Phone number. |
| `phone_number_verified` | boolean | Yes | Yes | Yes | `phone` | Whether the phone number is verified. |
| `role` | string or array of strings | Yes | Yes | Yes | `roles` | One value per role. In userinfo always a JSON array. In a JWT, accept both a single string and an array. |

Scope-released claims appear only when the user has a value. Tokens may contain other claims, such as private claims whose names start with `oi_`; ignore claims you do not recognise.

There is no `address` scope and no `address` claim. There is no `sid` claim.

API scopes that your administrator creates, such as `orders.read`, appear in the access token's `scope` claim only. They add no claims.

`offline_access` asks for a refresh token. It releases no claims.

## amr values

`amr` (authentication methods references) is a JSON array in the ID token.

| Value | Meaning |
|---|---|
| `pwd` | The user signed in with a password at OneiD (OneiD account or LDAP directory). |
| `mfa` | The user also entered an authenticator-app code. Appears together with `pwd`: `["pwd", "mfa"]`. |
| `external` | The user signed in at an upstream OpenID Connect provider: `["external"]`. |

## acr values

`acr` (authentication context class reference) is derived from `amr`.

| Value | When |
|---|---|
| `urn:oltin:ac:pwd` | Password sign-in without MFA. |
| `urn:oltin:ac:mfa` | Password sign-in with MFA. |
| `urn:oltin:ac:external` | Sign-in at an upstream OpenID Connect provider. |

> **Warning:** OneiD does not enforce `acr_values`. Asking for `urn:oltin:ac:mfa` does not force MFA. To require MFA, check `acr` or `amr` in the ID token in your application, and ask your OneiD administrator to make MFA mandatory for the users concerned.

When users sign in at an upstream OpenID Connect provider, that provider's own MFA applies. OneiD does not add its own code on top, and the ID token shows `external`.

## idp values

`idp` is released with the `profile` scope.

| Value | Where the user signed in |
|---|---|
| `local` | A OneiD account. |
| `ldap` | An LDAP or Active Directory directory connected to OneiD. |
| `oidc` | An upstream OpenID Connect provider, such as Okta. |

## sub formats

Treat `sub` as opaque and stable. Identify a user by the pair `iss` + `sub`, never by `email` or `preferred_username`.

| Sign-in source | `sub` value |
|---|---|
| OneiD account | An opaque OneiD user ID. |
| LDAP or Active Directory | The directory account name in lower case, without the domain. |
| Upstream OpenID Connect provider | The upstream provider's `sub`, unchanged. |
| Client credentials grant | The client ID. |

Each OneiD deployment has one sign-in source. See [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/).

## The claims request parameter

OneiD supports the OpenID Connect `claims` request parameter for the `id_token` and `userinfo` members.

- OneiD reads the claim names you list.
- `essential`, `value` and `values` are ignored.
- A claim is released only when it lies within a scope the client is allowed and the user consented to. The `claims` parameter never releases more than the scopes allow.

> **Tip:** In most cases you do not need the `claims` parameter. Request the scope instead; its claims go to the ID token, the access token and userinfo.

Example `claims` value:

```json
{
  "id_token": {
    "email": null,
    "preferred_username": null
  },
  "userinfo": {
    "phone_number": null
  }
}
```

Send it URL-encoded as a parameter of the authorisation request, together with the scopes that cover the claims:

```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%20phone&state=Xk3fQ9vLp2&nonce=n-7Hq2Lw81&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&claims=%7B%22id_token%22%3A%7B%22email%22%3Anull%2C%22preferred_username%22%3Anull%7D%2C%22userinfo%22%3A%7B%22phone_number%22%3Anull%7D%7D HTTP/1.1
Host: YOUR_ONEID
```

## Learn more

- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles/)
- [Tokens](https://oltinid.com/docs/reference/tokens/)
- [Endpoints](https://oltinid.com/docs/reference/endpoints/)