Sovrain
  1. Documentation
  2. Identity provider
  3. For admins

Reference

Application settings

Every setting of an OpenID Connect, SAML and SCIM application, tab by tab, with its default.

The settings of one application under Admin › Applications, tab by tab. Fields save on their own a moment after they change, with no save button, except on the SCIM Attribute mapping and Scope tabs: there nothing changes until Save changes… and Apply. Lists such as redirect URIs or group access change at once with their own add and remove buttons. The same settings in the API: Applications, OpenID Connect clients, SAML configuration, SCIM provisioning.

Application types

Application typeSigns people inProvisions accountsTabs
SAML 2.0 (SSO) (default)SAML 2.0optional: Add SCIM provisioning to this appApp identity, Service Provider, Identity Provider, Subject & attributes, Sign-out, Access & diagnostics, Danger zone
OpenID Connect (SSO)OpenID ConnectnoApp identity, Relying Party (RP), Claims, Sign-out, Access & diagnostics, Danger zone
Standalone SCIM (provisioning only)noyesApp identity, Connection, Options, Attribute mapping, Scope, Activity, Danger zone

A SAML application with SCIM provisioning has a switch SSO / Provisioning that shows the SCIM tabs. SAML and standalone SCIM can be switched into each other; an OpenID Connect application keeps its type. There are no application templates or catalogue: every application is set up by hand.

Every application

ControlEffect
Disable / EnableA disabled application refuses every sign-in, and people signed in to it through a delegation are signed out. No confirmation.

App identity

FieldRuleDefault
Application nameNot blank. Shown to members on their home page.set on creation
Slug2 to 63 characters from a-z 0-9 -, starting and ending with a letter or digit, unique in the organization, not a reserved word. Used in the application’s URLs.set on creation
DescriptionFree textempty
Application typeSAML and standalone SCIM only. Switching from SAML to standalone SCIM deletes the SAML setup for good, after a confirmation.set on creation
SCIM provisioning for this appSAML only. Unticking deletes the SCIM setup, after a confirmation; accounts already in the application stay.off, unless chosen on creation
App launcher URLOpenID Connect only (SAML: on the Service Provider tab). Not checked. Without it, an OpenID Connect application has no tile on the home page.empty

Access & diagnostics

CardSettingDefaultNotes
Two-step sign-inRequire two-step sign-inoffApplies whatever the organization’s policy. Not available for standalone SCIM.
Group accessGroups, each with an optional rolenoneOnly members of these groups can sign in. The role is sent as the role claim (OpenID Connect, only with the groups scope) or attribute (SAML). The role is free text.

Delegation for the application is allowed under Admin › Delegations, card Applications; see Organization settings.

Danger zone

Delete application deletes the application and ends delegations to it. No confirmation.

OpenID Connect

Relying Party (RP)

CardSettingDefaultNotes
Redirect URIsList of URIsnoneMatched exactly. Sign-in is refused while the list is empty. Rules: Redirect URI rules.
Client registrationClient IDrandom22 characters; never changes
Client registrationClient secretnoneGenerate shows a 44-character secret once; Sovrain keeps only a hash. Rotate replaces it; the old secret stops working at once.
Client registrationClient typeCONFIDENTIALCONFIDENTIAL or PUBLIC. Switching discards the secret. Switching to PUBLIC turns Require PKCE on for good.
Our endpointsDiscovery URL, Issuer, Authorization, Token, Userinfo, JWKS, Sign-outRead-only, with copy buttons
Scopes & optionsScopesopenid, profile, emailopenid is always on. groups is off.
Scopes & optionsAsk the user for consent before the first sign-inoff
Scopes & optionsRequire PKCEonAlways on for public clients
Scopes & optionsAllow refresh tokensoffRefresh tokens last as long as the Sovrain session

Claims

Claim mapping: custom claims, each a user attribute, a claim name and the scope it is Sent with (profile, email or groups). None by default. Rules: Custom claims.

Sign-out

SettingDefaultNotes
Enable sign-out for this applicationonOff: the application gets no logout calls, and its sign-out requests are treated as coming from no known application
Back-channel logout URIemptyhttps on a public address
Front-channel logout URIemptyRedirect URI rules
Post-logout redirect URIsnoneRedirect URI rules. Without one, people land on the organization’s home page after signing out.

How sign-out works: OpenID Connect › Sign-out.

Access & diagnostics, OpenID Connect only

ControlEffect
Test sign-inSigns a sample ID token and checks it against the published keys
Test sign-outChecks that the back-channel logout URI answers
ConsentHow many people have allowed the application
Revoke for everyoneDeletes every consent and refresh token of the application, closes its sessions and sends back-channel logout. No confirmation.
ActivityThe last 20 sign-in events; events are kept 90 days

SAML

Service Provider

CardSettingDefaultNotes
Metadata sourceImport metadata… from Metadata URL, Upload XML file or Paste XMLManaged manuallyAt most 2 MiB. What is read: SAML › Service provider metadata. Refresh fetches the URL again.
Metadata sourceAuto-refresh from this URL dailyoffAt 04:00 UTC
Endpoints & identityEntity IDurn:idp:app:<slug>The service provider’s entity ID; must be changed. Unique in the organization.
Endpoints & identityRequire signed AuthnRequest from the SPonWhile on, sign-in needs an SP certificate under SP trust certificates
Endpoints & identityAllow IdP-initiated SSOoff
App launcherApp launcher URLemptyEmpty: the tile on the home page starts IdP-initiated sign-in, when allowed
App launcherDefault RelayStateemptyAt most 80 bytes. Sent with IdP-initiated sign-in.
ACS URLsEndpoints, each Index, Binding, LocationnoneIndex unique. Choose the binding HTTP-POST and make an HTTP-POST endpoint the default: IdP-initiated sign-in posts to the default (or first) endpoint whatever its binding. One endpoint can be the default.
SP trust certificatesCertificates, each Use (SIGNING, ENCRYPTION, SIGNING_ENCRYPTION), Note (optional), Certificate (PEM)noneUsed to check the service provider’s signatures and to encrypt. A certificate that disappears from refreshed metadata is no longer trusted at once and is deleted after 7 days unless kept with Keep.

Identity Provider

CardSettingDefaultNotes
IdP metadataMetadata URL, Identity provider entity ID, Identity provider single sign-on URLRead-only. Values: SAML › Entity ID and endpoints. Download XML saves the metadata.
Signing keysKeys, each with an algorithm and a stateone active RSA-2048 · SHA-256 keyGenerate next key with RSA-2048 · SHA-256 or SHA-512, ECDSA-P256 · SHA-256, ECDSA-P384 · SHA-384 or ECDSA-P521 · SHA-512; then Promote, Discard or Deactivate. RSA-2048 · SHA-1 is listed but always fails; choose another algorithm. No confirmations.
What gets signedAssertion, Response, BothAssertion
Two-step sign-in signal (AuthnContextClassRef)REFEDS MFA, Microsoft, Password onlyREFEDS MFAThe value sent after a second step: https://refeds.org/profile/mfa, http://schemas.microsoft.com/claims/multipleauthn, or urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Subject & attributes

CardSettingDefaultNotes
Subject (NameID)Source attributeemailAny user attribute. email is sent only when verified; an empty value fails the sign-in.
Subject (NameID)FormatemailAddressemailAddress, persistent, transient, unspecified. The value is the same whatever the format.
Attribute mappingUser attribute → SAML attribute namenoneactor is reserved. The group role is sent as role without a mapping.

Sign-out

Card Single Logout:

SettingDefaultNotes
Enable Single Logout for this applicationoffNeeds an SP SLO URL
SP SLO URLemptyAn absolute http or https URL. Filled in by a metadata import.
BindingHTTP_REDIRECT or HTTP_POST
Sign LogoutRequeston
Sign LogoutResponseon
Require signed LogoutRequeston
Require signed LogoutResponseon

Access & diagnostics, SAML only

CardSettingDefaultNotes
EncryptionWhat to encryptoffASSERTION, NAMEID or ATTRIBUTES. Needs an RSA certificate with the use ENCRYPTION or SIGNING_ENCRYPTION.
EncryptionKey transportRSA-OAEP SHA-256RSA-OAEP SHA-256 (recommended) or SHA-1 (legacy)
EncryptionData encryptionAES-256-GCMAES-128-GCM, AES-192-GCM, AES-256-GCM, AES-128-CBC, AES-256-CBC (CBC is legacy)
Test SSO & recent activityRun test SSO, Test logoutTests in Sovrain; the result shows the time taken or the reason. The table lists the last 20 events, kept 90 days.

SCIM provisioning

For standalone SCIM applications, and SAML applications with SCIM provisioning. How provisioning behaves: SCIM. Until a connection test passes, the tabs after Connection are locked.

Connection

SettingDefaultNotes
Enable SCIM provisioning for this applicationoffWhile off, nothing is sent to the application
SCIM base URLemptyhttps on a public address
Bearer tokenemptyStored encrypted and never shown again. At most 8192 characters.
Test connectionRuns discovery
Test with user…Creates a temporary user in the application, reads it back and deletes it

Options

SettingDefaultNotes
Create usersonLooks the user up by userName first and updates a match
Update user attributeson
Deactivate usersonApplies when a user is suspended or removed in Sovrain or leaves the scope. Off: users are neither deactivated nor deleted, except by Remove or Force sync… on drift.
Deprovisioning behaviorSet active=falseSet active=false (the account is kept but disabled) or Send DELETE (the account is removed, when the application supports it)

Attribute mapping

SettingDefaultNotes
userName sourceemailemail (verified only), login, id, externalId
User attribute → SCIM attributeemail → emails[type eq "work"].value, firstName → name.givenName, lastName → name.familyNameAt most 200. Rules: SCIM › Attribute mapping.

Save changes… shows how many accounts change, then Apply queues the changes; they wait 3 minutes before they are sent.

Scope

SettingDefaultNotes
WhoSelected groups and usersOr Everyone in this organization. Separate from who may sign in.
GroupsnoneUp to 5000. Each Group+members or Members only, and for Group+members a Group name in SP: an existing group of the application or a new name, at most 255 characters.
UsersnoneUp to 5000, besides the groups

Save changes… shows the effect, then Apply queues it. Discard changes drops unsaved changes.

Activity

Shows the last reconciliation, the users in scope, the groups synced and the jobs, refreshed every 3 seconds.

ControlEffect
Reconcile nowRuns a reconciliation
Retry all failingQueues every failed and rejected job again
Retry now, CancelPer job. Cancel holds the job for 5 minutes.
Remove (drift)Removes one account or group that Sovrain does not manage from the application: the account is deactivated or deleted as set in Deprovisioning behavior, the group is deleted. After a confirmation and a 3-minute wait
Force sync…Does the same for every account and group that Sovrain does not manage, after a confirmation and a 3-minute wait
Look up a userShows the state of one person at the application