Reference
Claims and attributes
Every claim Sovrain puts in OpenID Connect tokens and every attribute it sends in SAML assertions.
What Sovrain tells an application about a person: the claims in OpenID Connect tokens and userinfo, and the NameID and attributes in SAML assertions. The protocols themselves are on OpenID Connect and SAML.
User attributes
Claims and attributes take their values from a person’s attributes.
| Attribute | Value | Example |
|---|---|---|
id | Sovrain’s internal number of the account. Unique in the organization only. | 42 |
externalId | The public id: 22 characters, never changes. The same value as the OpenID Connect sub. | V3H7fPgwfvR2jqPjePvjHb |
login | The login name | jane |
email | The email address in lower case, only when it is verified. Empty otherwise. | jane@acme.example |
firstName | First name from the profile | Jane |
lastName | Last name from the profile | Doe |
| custom attributes | Attributes of the organization’s attribute bank, set per person by an admin | department = R&D |
Custom attribute names start with a letter, then letters, digits and _, up to 64 characters. They are added under
Admin › Attributes: see Add custom attributes.
OpenID Connect
ID token
Header: {"kid": "…", "typ": "JWT", "alg": "RS256"}. Lifetime 5 minutes.
| Claim | When | Value |
|---|---|---|
iss | always | The issuer, https://acme.sovrain.net |
sub | always | The person’s public id (externalId). The same for every application of the organization. |
aud | always | The client_id, as a string |
azp | always | The client_id |
iat, exp | always | Seconds since the epoch |
auth_time | always | When the person actually signed in to Sovrain |
sid | always | The Sovrain session. Every application signed in from the same browser session gets the same value. A delegated sign-in has its own. |
nonce | when the authorization request had one | Copied from the request. Not in ID tokens from a refresh. |
amr | when the session records its sign-in methods | See amr values |
acr | only after a second step | See acr values |
act | delegated sign-in, when the delegation policy adds the actor claim | {"sub": "<public id of the person signing in for the owner>"} |
| scope claims | when the scope is granted | See Claims by scope |
| custom claims | when the claim’s scope is granted and the value is not empty | See Custom claims |
Example, with the scopes openid profile email groups:
{
"iss": "https://acme.sovrain.net",
"sub": "V3H7fPgwfvR2jqPjePvjHb",
"aud": "TdAtCYictm7inke6XQkeED",
"azp": "TdAtCYictm7inke6XQkeED",
"iat": 1794914400,
"exp": 1794914700,
"auth_time": 1794914380,
"sid": "<44 characters>",
"nonce": "n-0S6_WzA2Mj",
"amr": ["pwd", "otp", "mfa"],
"acr": "http://schemas.openid.net/pape/policies/2007/06/multi-factor",
"preferred_username": "jane",
"name": "Jane Doe",
"given_name": "Jane",
"family_name": "Doe",
"email": "jane@acme.example",
"email_verified": true,
"groups": ["Engineering"],
"role": ["editor"]
}
ID tokens never contain at_hash, c_hash, address, phone_number, picture, locale, zoneinfo or
updated_at.
Claims by scope
The scope claims are in the ID token and in the userinfo response.
| Scope | Claim | Value |
|---|---|---|
openid | sub | Always granted |
profile | preferred_username | The login name. Always present. |
profile | name | The display name; if none, first and last name. Left out when empty. |
profile | given_name | First name. Left out when empty. |
profile | family_name | Last name. Left out when empty. |
email | email | The verified address in lower case. Left out when the address is not verified. |
email | email_verified | true. Left out when the address is not verified. |
groups | groups | Names of the person’s groups that give access to this application, sorted. Present even when empty ([]). |
groups | role | The roles of those groups’ access to this application, without duplicates, sorted. Left out when there are none. |
New applications have the scopes openid, profile and email; groups must be added to the application before
it can be requested.
amr values
amr | The person signed in with |
|---|---|
["pwd"] | A password only |
["pwd", "otp", "mfa"] | A password and a code from an authenticator app, or a backup code |
["pwd", "hwk", "mfa"] | A password and a security key, or a passkey that cannot be synced |
["pwd", "swk", "mfa"] | A password and a synced passkey (one that is backed up to a cloud account) |
amr is left out for sessions that started before Sovrain recorded sign-in methods.
acr values
acr is present only when amr contains mfa.
acr is the first of https://refeds.org/profile/mfa and http://schemas.openid.net/pape/policies/2007/06/multi-factor
that the application asked for (values in claims before acr_values), or the PAPE value when it asked for neither.
After a password alone, there is no acr.
Access token
An RS256 JWT with header typ: at+jwt (RFC 9068), meant for the userinfo endpoint. Lifetime 1 hour, or 5 minutes
for a delegated sign-in.
| Claim | Value |
|---|---|
iss | The issuer |
sub | The person’s public id |
aud | The issuer |
client_id | The application’s client_id |
iat, exp | |
jti | A random id |
scope | The granted scopes, separated by spaces |
sid | The Sovrain session |
The access token has no act, amr or auth_time. Admin API tokens have a different set: see
Admin API.
UserInfo response
sub, the scope claims and the custom claims of the token’s scopes. Never amr, acr, act or auth_time.
Logout token
Sent to back-channel logout URIs. Header typ: logout+jwt. Lifetime 2 minutes.
| Claim | Value |
|---|---|
iss | The issuer |
sub | The person’s public id |
aud | The application’s client_id |
iat, exp | |
jti | A random id |
sid | The ended Sovrain session |
events | {"http://schemas.openid.net/event/backchannel-logout": {}} |
Custom claims
An admin adds custom claims per application on the Claims tab, or with the Admin API.
| Rule | Detail |
|---|---|
| Source | A user attribute: a built-in one or one from the attribute bank |
| Claim name | A letter, then up to 63 of A-Z a-z 0-9 _ . -. Unique in the application. Not reserved. |
| Released with | profile, email or groups. The claim is sent only when that scope is granted. Never openid. |
| Value | A string. Left out when empty. From email, only a verified address. |
| Where | ID token and userinfo |
Reserved claim names
These 25 names cannot be used for custom claims:
sub, iss, aud, exp, iat, jti, nonce, azp, auth_time, amr, acr, sid, events, scope,
client_id, typ, act, name, given_name, family_name, preferred_username, email, email_verified,
groups, role.
SAML
NameID
| Setting | Values | Default |
|---|---|---|
| Source attribute | Any user attribute | email |
| Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, urn:oasis:names:tc:SAML:2.0:nameid-format:transient, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified | emailAddress |
- The value is the source attribute’s value, whatever the format. With
transientthe value is the same in every sign-in; it is not a one-time identifier. - When the source value is empty (for example
emailof a person whose address is not verified), the sign-in fails with the statusAuthnFailed. - The
NameIDPolicyof the request is ignored.
Attributes
| Attribute | When | Value |
|---|---|---|
| Mapped attributes | One per mapping on the application’s Subject & attributes tab | The user attribute’s value. Single-valued. Left out when empty. |
role | When the person’s groups give access to the application with a role | Every role, one AttributeValue each |
actor | Delegated sign-in, when the delegation policy adds the actor claim | The login name of the person signing in for the owner |
All attributes have NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" and values of type xs:string.
The name actor cannot be used for a mapping.
SAML assertions have no groups attribute. Send group membership to SAML applications as a role.
AuthnContextClassRef
| The person signed in with | AuthnContextClassRef |
|---|---|
| A password only | urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport |
| A password and a second step | The application’s Two-step sign-in signal: https://refeds.org/profile/mfa (default), http://schemas.microsoft.com/claims/multipleauthn, or urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport |
When the AuthnRequest carries a RequestedAuthnContext, the assertion carries instead the strongest requested class
that the sign-in meets (see SAML).
SCIM
SCIM provisioning uses the same attributes, with two differences: an attribute of the bank is written
user_attributes.<name>, and the externalId that Sovrain sends to an application over SCIM is the internal id,
not the public id. See SCIM.