Sovrain
  1. Documentation
  2. Identity provider

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.

AttributeValueExample
idSovrain’s internal number of the account. Unique in the organization only.42
externalIdThe public id: 22 characters, never changes. The same value as the OpenID Connect sub.V3H7fPgwfvR2jqPjePvjHb
loginThe login namejane
emailThe email address in lower case, only when it is verified. Empty otherwise.jane@acme.example
firstNameFirst name from the profileJane
lastNameLast name from the profileDoe
custom attributesAttributes of the organization’s attribute bank, set per person by an admindepartment = 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.

ClaimWhenValue
issalwaysThe issuer, https://acme.sovrain.net
subalwaysThe person’s public id (externalId). The same for every application of the organization.
audalwaysThe client_id, as a string
azpalwaysThe client_id
iat, expalwaysSeconds since the epoch
auth_timealwaysWhen the person actually signed in to Sovrain
sidalwaysThe Sovrain session. Every application signed in from the same browser session gets the same value. A delegated sign-in has its own.
noncewhen the authorization request had oneCopied from the request. Not in ID tokens from a refresh.
amrwhen the session records its sign-in methodsSee amr values
acronly after a second stepSee acr values
actdelegated sign-in, when the delegation policy adds the actor claim{"sub": "<public id of the person signing in for the owner>"}
scope claimswhen the scope is grantedSee Claims by scope
custom claimswhen the claim’s scope is granted and the value is not emptySee 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.

ScopeClaimValue
openidsubAlways granted
profilepreferred_usernameThe login name. Always present.
profilenameThe display name; if none, first and last name. Left out when empty.
profilegiven_nameFirst name. Left out when empty.
profilefamily_nameLast name. Left out when empty.
emailemailThe verified address in lower case. Left out when the address is not verified.
emailemail_verifiedtrue. Left out when the address is not verified.
groupsgroupsNames of the person’s groups that give access to this application, sorted. Present even when empty ([]).
groupsroleThe 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

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

ClaimValue
issThe issuer
subThe person’s public id
audThe issuer
client_idThe application’s client_id
iat, exp
jtiA random id
scopeThe granted scopes, separated by spaces
sidThe 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.

ClaimValue
issThe issuer
subThe person’s public id
audThe application’s client_id
iat, exp
jtiA random id
sidThe 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.

RuleDetail
SourceA user attribute: a built-in one or one from the attribute bank
Claim nameA letter, then up to 63 of A-Z a-z 0-9 _ . -. Unique in the application. Not reserved.
Released withprofile, email or groups. The claim is sent only when that scope is granted. Never openid.
ValueA string. Left out when empty. From email, only a verified address.
WhereID 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

SettingValuesDefault
Source attributeAny user attributeemail
Formaturn: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:unspecifiedemailAddress
  • The value is the source attribute’s value, whatever the format. With transient the value is the same in every sign-in; it is not a one-time identifier.
  • When the source value is empty (for example email of a person whose address is not verified), the sign-in fails with the status AuthnFailed.
  • The NameIDPolicy of the request is ignored.

Attributes

AttributeWhenValue
Mapped attributesOne per mapping on the application’s Subject & attributes tabThe user attribute’s value. Single-valued. Left out when empty.
roleWhen the person’s groups give access to the application with a roleEvery role, one AttributeValue each
actorDelegated sign-in, when the delegation policy adds the actor claimThe 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 withAuthnContextClassRef
A password onlyurn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
A password and a second stepThe 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.