Sovrain
  1. Documentation
  2. Your organization

Reference

Organization settings

Every organization-wide setting in the admin pages, with its values, default and effect.

The settings that apply to the whole organization, in the order of the admin menu. Owners and administrators can change all of them; see Roles. The settings of a single application are on Application settings.

Most settings save on their own as soon as they change. Settings marked fresh sign-in ask the admin to sign in again if the last sign-in is more than 5 minutes old; the page then shows Signed in again. The settings below are not saved yet. with Save.

Attributes

Admin › Attributes (/admin/attributes): the bank of attributes that can be set on users and sent to applications.

ItemRule
Built-in attributesid, externalId, login, email, firstName, lastName. Always present; cannot be removed. Meaning: Claims and attributes.
Name of a custom attributeA letter, then letters, digits and _; at most 64 characters; unique ignoring case; not a built-in name
DescriptionOptional, at most 256 characters; can be changed later
Value on a userAny text, no length limit
DeleteDelete attribute lists the user values and SAML mappings that are deleted with it

Delegations

Admin › Delegations (/admin/delegations), card Policy. Delegation lets one person sign in to applications as another person for a limited time. Background: About delegation.

SettingValuesDefaultNotes
Who can create delegationsOff, Admins only, Users with approval, Users freelyOffFresh sign-in to loosen. With Off, existing delegations stop working at sign-in, and Revoke all appears.
Max duration (days)1 to 36530The longest a delegation can last
Require 2FA in the delegate’s sessionon, offonThe person signing in for the owner must have completed a second step
Email the owner on every sign-in as themon, offonAt most 30 such emails per hour; then one notice that further sign-ins are not mailed
Add actor claim (OIDC act) or attribute (SAML actor) for appson, offoffSee Claims and attributes
Never share accounts of members ofGroupsOwners, AdminsMembers of these groups can never be the owner of a delegation. Fresh sign-in to remove a group.

Card Applications: Allow delegation per application, off by default; fresh sign-in to turn on. Not available for SCIM-only applications.

ItemRule
Start of a new delegationAt most 10 minutes in the past, at most 365 days ahead
Default length in the dialog7 days
ReasonOptional, under 500 characters
Approve or reject at onceAt most 500 delegations
ExpiryChecked every 60 seconds; no email is sent when a delegation simply expires

Custom domain

Admin › Custom domain (/admin/domain). Lets people sign in at the organization’s own domain instead of acme.sovrain.net. Steps: Use your own domain.

ItemRule
Domains per organization1
Host2 or more labels of 1 to 63 characters, at most 253 characters, not an IP address, not under sovrain.net
DNS record for trafficlogin.acme.example CNAME acme.sovrain.net
DNS record for the certificate_acme-challenge.login.acme.example CNAME acme._acme-delegation.sovrain.net
Proxy or CDNMust be off for both records
CertificateRequested automatically once the domain is added; renewed automatically
StatesPending DNS, Issuing certificate, Certificate failing, Ready, Active; also Not routing and Renewal at risk
Taken by another organizationRefused, unless the other organization’s claim is not primary, has no certificate and is older than 7 days

Activate makes the domain primary, once every check passes:

  • the OpenID Connect issuer, the SAML entity IDs and every URL change to the domain, so every application must be updated;
  • everyone signs in again at the new address: existing sessions are not ended and refresh tokens keep working, but a browser’s session belongs to the old address;
  • passkeys and security keys added on the old address stop working and must be added again;
  • requests to acme.sovrain.net are redirected to the domain with 307, except the sign-in, sign-out and custom-domain pages.

Removing a primary domain asks the admin to type the host.

API access

Admin › API access (/admin/api-access): every Admin API grant in the organization, with its owner, scopes, dates, the address it was requested from and its calls of the last 24 hours. Revoke stops the grant at its next call. Details: Admin API.

Signing keys

Admin › Signing keys (/admin/oidc): the OpenID Connect signing keys of the organization, shared by all its OpenID Connect applications. SAML keys are per application.

ItemValue
AlgorithmRS256, RSA-2048
ActionsGenerate next key, then Promote or Discard the staged key; Retire the active key
Staged keysOne at a time
After replacementThe old key stays published for 65 minutes
RotationManual only; keys do not expire

Steps: Rotate signing keys.

Two-step sign-in

Admin › Two-step sign-in (/admin/security). Who must add a second step to sign in. Every change needs a fresh sign-in. Background: About two-step sign-in.

SettingValuesDefault
PolicyNobody, Groups only, Admins + groups, EveryoneGroups only
Time to set it upNone, 3 days, 7 days, 14 days, 30 days7 days
PolicyMust add a second step
NobodyNobody, unless an application requires it; anyone may
Groups onlyMembers of the groups below; everyone else may, unless an application requires it
Admins + groupsOwners, administrators and members of the groups below; everyone else may, unless an application requires it
EveryoneEveryone
  • Groups that require it lists the groups whose Require two-step sign-in switch is on (in the group’s Details). The switch counts only for Groups only and Admins + groups.
  • Time to set it up counts from the first time a person is asked. Until then the person can choose Skip for now; a skip lasts until the next sign-in. With None there is no skip.
  • After the time is up, the person cannot sign in or use the Admin API without setting up a second step.
  • An application with Require two-step sign-in asks for a second step whatever the policy, without Skip for now.
  • The page refuses a change that would lock out the admin making it.

The methods: Two-step methods.

Account recovery

Admin › Account recovery (/admin/account-recovery). What people can do when they lose their password or their second step. Every change needs a fresh sign-in.

CardSettingValuesDefaultNotes
Forgotten passwordLet users reset their password by emailon, offonA single-use link goes to the account’s verified email. Accounts without one are reset by an administrator.
Forgotten passwordAsk for the second factor during the reseton, offonAccounts with two-step sign-in complete it after opening the link. A link an admin sends always asks.
Forgotten passwordLink expires after15, 30 or 60 min30 minAlso the lifetime of the link that resets two-step sign-in by email. A new link cancels the previous one.
Lost two-step sign-inEmail as a backup factoron, offoffA person who knows the password and has a verified email can reset two-step sign-in with a link, in the same browser, and set up an authenticator app again
Lost two-step sign-inEmail administrators when it happenson, offonEmails every active owner and administrator with a verified email
After a resetEnd the account’s other sessionson, offonSigns out every other browser and revokes refresh tokens
After a resetEmail the useron, offon“Your password was changed” or “Your two-step sign-in was reset”
  • Card Who can do what shows the result for each kind of account (Email and two-step, Email only, Two-step only, Neither) and each case (Forgot password, Lost two-step sign-in, Lost both).
  • A person who has lost both the password and every second step needs an administrator.
  • A reset link an admin creates on a user’s page is valid for 24 hours, whatever Link expires after says.

Branding

Admin › Branding (/admin/branding).

SettingRuleDefault
Application name1 to 40 characters, no control characters. Shown in the header, on sign-in pages and in emails.Sovrain
Title prefix0 to 40 characters. Shown in the browser tab before the page name. Empty: the page name only.Sovrain
App icon, light and darkPNG or SVG, at most 128 KB; 128×128 works best. An SVG must not contain DOCTYPE or ENTITY.none
Header colour, light#rrggbb#ffffff
Text colour, light#rrggbb#171717
Header colour, dark#rrggbb#0a0a0a
Text colour, dark#rrggbb#fafafa

Reset to default restores the defaults and removes the icons.

Backup

Admin › Backup (/admin/backup): export and import of the whole organization. Any admin can export; only owners can import. The file and what it contains: Export format.

Fixed settings

These apply to every organization and cannot be changed:

ItemValue
Session lengthFixed; see Limits
PasswordAt least 8 characters, at most 72 bytes; no other rules
Login name3 to 32 characters from a-z 0-9 . _ - (stored in lower case); people invited by email have their address, up to 254 characters, as typed
Account lockoutNone; repeated attempts are slowed by rate limits
Organization nameSet at registration; no setting changes it. An import takes the name from the backup.
Organization addressSet at registration; cannot be changed
Data regionSet at registration; cannot be changed

More: Limits.