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 type | Signs people in | Provisions accounts | Tabs |
|---|
| SAML 2.0 (SSO) (default) | SAML 2.0 | optional: Add SCIM provisioning to this app | App identity, Service Provider, Identity Provider, Subject & attributes, Sign-out, Access & diagnostics, Danger zone |
| OpenID Connect (SSO) | OpenID Connect | no | App identity, Relying Party (RP), Claims, Sign-out, Access & diagnostics, Danger zone |
| Standalone SCIM (provisioning only) | no | yes | App 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
| Control | Effect |
|---|
| Disable / Enable | A disabled application refuses every sign-in, and people signed in to it through a delegation are signed out. No confirmation. |
App identity
| Field | Rule | Default |
|---|
| Application name | Not blank. Shown to members on their home page. | set on creation |
| Slug | 2 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 |
| Description | Free text | empty |
| Application type | SAML 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 app | SAML only. Unticking deletes the SCIM setup, after a confirmation; accounts already in the application stay. | off, unless chosen on creation |
| App launcher URL | OpenID 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
| Card | Setting | Default | Notes |
|---|
| Two-step sign-in | Require two-step sign-in | off | Applies whatever the organization’s policy. Not available for standalone SCIM. |
| Group access | Groups, each with an optional role | none | Only 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)
| Card | Setting | Default | Notes |
|---|
| Redirect URIs | List of URIs | none | Matched exactly. Sign-in is refused while the list is empty. Rules: Redirect URI rules. |
| Client registration | Client ID | random | 22 characters; never changes |
| Client registration | Client secret | none | Generate shows a 44-character secret once; Sovrain keeps only a hash. Rotate replaces it; the old secret stops working at once. |
| Client registration | Client type | CONFIDENTIAL | CONFIDENTIAL or PUBLIC. Switching discards the secret. Switching to PUBLIC turns Require PKCE on for good. |
| Our endpoints | Discovery URL, Issuer, Authorization, Token, Userinfo, JWKS, Sign-out | | Read-only, with copy buttons |
| Scopes & options | Scopes | openid, profile, email | openid is always on. groups is off. |
| Scopes & options | Ask the user for consent before the first sign-in | off | |
| Scopes & options | Require PKCE | on | Always on for public clients |
| Scopes & options | Allow refresh tokens | off | Refresh 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
| Setting | Default | Notes |
|---|
| Enable sign-out for this application | on | Off: the application gets no logout calls, and its sign-out requests are treated as coming from no known application |
| Back-channel logout URI | empty | https on a public address |
| Front-channel logout URI | empty | Redirect URI rules |
| Post-logout redirect URIs | none | Redirect 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
| Control | Effect |
|---|
| Test sign-in | Signs a sample ID token and checks it against the published keys |
| Test sign-out | Checks that the back-channel logout URI answers |
| Consent | How many people have allowed the application |
| Revoke for everyone | Deletes every consent and refresh token of the application, closes its sessions and sends back-channel logout. No confirmation. |
| Activity | The last 20 sign-in events; events are kept 90 days |
SAML
Service Provider
| Card | Setting | Default | Notes |
|---|
| Metadata source | Import metadata… from Metadata URL, Upload XML file or Paste XML | Managed manually | At most 2 MiB. What is read: SAML › Service provider metadata. Refresh fetches the URL again. |
| Metadata source | Auto-refresh from this URL daily | off | At 04:00 UTC |
| Endpoints & identity | Entity ID | urn:idp:app:<slug> | The service provider’s entity ID; must be changed. Unique in the organization. |
| Endpoints & identity | Require signed AuthnRequest from the SP | on | While on, sign-in needs an SP certificate under SP trust certificates |
| Endpoints & identity | Allow IdP-initiated SSO | off | |
| App launcher | App launcher URL | empty | Empty: the tile on the home page starts IdP-initiated sign-in, when allowed |
| App launcher | Default RelayState | empty | At most 80 bytes. Sent with IdP-initiated sign-in. |
| ACS URLs | Endpoints, each Index, Binding, Location | none | Index 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 certificates | Certificates, each Use (SIGNING, ENCRYPTION, SIGNING_ENCRYPTION), Note (optional), Certificate (PEM) | none | Used 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
| Card | Setting | Default | Notes |
|---|
| IdP metadata | Metadata URL, Identity provider entity ID, Identity provider single sign-on URL | | Read-only. Values: SAML › Entity ID and endpoints. Download XML saves the metadata. |
| Signing keys | Keys, each with an algorithm and a state | one active RSA-2048 · SHA-256 key | Generate 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 signed | Assertion, Response, Both | Assertion | |
| Two-step sign-in signal (AuthnContextClassRef) | REFEDS MFA, Microsoft, Password only | REFEDS MFA | The 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
| Card | Setting | Default | Notes |
|---|
| Subject (NameID) | Source attribute | email | Any user attribute. email is sent only when verified; an empty value fails the sign-in. |
| Subject (NameID) | Format | emailAddress | emailAddress, persistent, transient, unspecified. The value is the same whatever the format. |
| Attribute mapping | User attribute → SAML attribute name | none | actor is reserved. The group role is sent as role without a mapping. |
Sign-out
Card Single Logout:
| Setting | Default | Notes |
|---|
| Enable Single Logout for this application | off | Needs an SP SLO URL |
| SP SLO URL | empty | An absolute http or https URL. Filled in by a metadata import. |
| Binding | | HTTP_REDIRECT or HTTP_POST |
| Sign LogoutRequest | on | |
| Sign LogoutResponse | on | |
| Require signed LogoutRequest | on | |
| Require signed LogoutResponse | on | |
Access & diagnostics, SAML only
| Card | Setting | Default | Notes |
|---|
| Encryption | What to encrypt | off | ASSERTION, NAMEID or ATTRIBUTES. Needs an RSA certificate with the use ENCRYPTION or SIGNING_ENCRYPTION. |
| Encryption | Key transport | RSA-OAEP SHA-256 | RSA-OAEP SHA-256 (recommended) or SHA-1 (legacy) |
| Encryption | Data encryption | AES-256-GCM | AES-128-GCM, AES-192-GCM, AES-256-GCM, AES-128-CBC, AES-256-CBC (CBC is legacy) |
| Test SSO & recent activity | Run test SSO, Test logout | | Tests 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
| Setting | Default | Notes |
|---|
| Enable SCIM provisioning for this application | off | While off, nothing is sent to the application |
| SCIM base URL | empty | https on a public address |
| Bearer token | empty | Stored encrypted and never shown again. At most 8192 characters. |
| Test connection | | Runs discovery |
| Test with user… | | Creates a temporary user in the application, reads it back and deletes it |
Options
| Setting | Default | Notes |
|---|
| Create users | on | Looks the user up by userName first and updates a match |
| Update user attributes | on | |
| Deactivate users | on | Applies 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 behavior | Set active=false | Set active=false (the account is kept but disabled) or Send DELETE (the account is removed, when the application supports it) |
Attribute mapping
| Setting | Default | Notes |
|---|
| userName source | email | email (verified only), login, id, externalId |
| User attribute → SCIM attribute | email → emails[type eq "work"].value, firstName → name.givenName, lastName → name.familyName | At 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
| Setting | Default | Notes |
|---|
| Who | Selected groups and users | Or Everyone in this organization. Separate from who may sign in. |
| Groups | none | Up 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. |
| Users | none | Up 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.
| Control | Effect |
|---|
| Reconcile now | Runs a reconciliation |
| Retry all failing | Queues every failed and rejected job again |
| Retry now, Cancel | Per 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 user | Shows the state of one person at the application |