Claims

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

View as Markdown

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.
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.
acr string Yes No No Always The authentication level, derived from amr. See 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.
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.

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:

{
  "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:

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