Sovrain
  1. Documentation
  2. Self-hosting

Reference

Server configuration

Environment variables, profiles, ports, data directory, TLS, regions and fixed values of a Sovrain server.

How a Sovrain server is configured. This matters only to people who run Sovrain themselves; organizations on sovrain.net change nothing here. Steps: Run Sovrain with Docker.

The server reads its configuration from environment variables at start. A variable set to an empty value counts as not set. With the profiles qa and prod, the server refuses to start when a required value is missing and names it.

Profiles

SPRING_PROFILES_ACTIVE is a comma-separated list. Only local, qa and prod have an effect.

nonelocalqaprod
PurposeDevelopmentDevelopment with developer pagesStagingProduction
HTTPS with automatic certificatesno, plain HTTPno, plain HTTPyes, ClouDNS onlyyes, ClouDNS or OVH
Secure cookiesnonoyesyes
IDP_MEK, IDP_CSRF_SECRET, SMTPbuilt-in defaultsbuilt-in defaultsrequiredrequired
Developer pages, diagnosticsnoyesnono
Loopback addresses for back-channel logout and SCIMnoyesnono
Data directory default~/.idp~/.idp/data/data
Mailwritten to the log, without the bodywritten to the log, with the bodysentsent

There is no profile for running behind a reverse proxy that terminates TLS: qa and prod always run their own HTTPS listener with certificates from ACME.

Environment variables

Core

VariableDefaultNotes
SPRING_PROFILES_ACTIVEnoneSee Profiles
SERVER_PORT8080Plain HTTP listener
IDP_DATABASE_DIRECTORY/data in qa and prod, ~/.idp otherwiseData directory. HOME must be set when it is not.
IDP_MEKbuilt-in development key; required in qa and prodMaster encryption key: Base64 of 32 bytes. The data directory is tied to it by the file mek-fingerprint; a different key refuses to start. Sovrain has no way to re-encrypt the data under another key.
IDP_CSRF_SECRETrandom at each start; required in qa and prodKey for CSRF tokens and signed markers
IDP_BASE_URLhttp://idp.localhost:8080; ignored in qa; required in prodThe landing address, for example https://sovrain.net. Organizations are at https://<slug>.<host>.
IDP_PREFIXemptyText before every browser tab title, for example [TEST]. At most 20 characters.
IDP_RATE_LIMIT_TRUST_PROXYfalsetrue: rate limits use the first X-Forwarded-For address as the client. Set it only behind a proxy that overwrites that header.
RUST_LOGinfoLog filter

Mail

VariableDefaultNotes
IDP_SMTP_HOSTnone; required in qa and prodMail relay
IDP_SMTP_USERNAMEnone; required in qa and prod
IDP_SMTP_PASSWORDnone; required in qa and prod
IDP_SMTP_PORT465
IDP_SMTP_SSLtruetrue: TLS from the start of the connection (implicit TLS). false: plain SMTP without any TLS; STARTTLS is not used.
IDP_MAIL_FROMthe SMTP user name in qa and prod; noreply@sovrain.local otherwiseSender address

Mail is sent with a 5-second connect timeout and 20 seconds for the whole message. Each email is sent while the request that caused it waits, except delegation notices, which are queued. When the relay cannot be reached or does not answer in time, sending fails at once for the next 30 seconds; a relay that refuses an email does not start this pause. A failed email does not undo the action that caused it. Which emails are sent and their limits: Emails. Steps: Configure outgoing mail.

TLS and DNS

Certificates come from an ACME server with the DNS-01 challenge, through the API of a DNS provider.

VariableDefaultNotes
IDP_TLS_ACME_DIRECTORYLet’s Encrypt productionACME directory URL
IDP_TLS_DNS_PROVIDERcloudnscloudns or ovh. Always cloudns in qa.
IDP_TLS_DNS_ZONEempty in prod (the landing host)The DNS zone that holds the landing and region hosts
IDP_TLS_DNS_SETTLE_DELAY60sWait before the challenge is answered; whole seconds with s
IDP_TLS_DNS_SERVERnot set<ip>:<port> of a DNS server to ask instead of the normal resolvers. For test setups.
IDP_TLS_CLOUDNS_ENDPOINThttps://api.cloudns.net
IDP_TLS_CLOUDNS_AUTH_KINDSUB_AUTH_IDSUB_AUTH_ID or AUTH_ID
IDP_TLS_CLOUDNS_AUTH_ID, IDP_TLS_CLOUDNS_PASSWORDnoneRequired when the provider is cloudns
IDP_TLS_OVH_ENDPOINThttps://eu.api.ovh.com/1.0
IDP_TLS_OVH_APP_KEY, IDP_TLS_OVH_APP_SECRET, IDP_TLS_OVH_CONSUMER_KEYnoneRequired when the provider is ovh

The credentials of the chosen provider must not be empty, or the server does not start.

Steps: Set up TLS with DNS.

Nodes and regions

VariableDefaultNotes
IDP_NODE_PEERS_FILE/etc/paas/peersThe list of nodes; see Peers file
IDP_NODE_REGIONlocalThis node’s region, used only when there is no peers file
IDP_NODE_LANDINGtrueWhether this node is the landing node, used only when there is no peers file
PAAS_APP, PAAS_NODEemptyThe node’s identity in the peers file

Registration

VariableDefaultRangeNotes
IDP_REGISTRATION_POW_MEMORY_MIB328 to 4096Memory of the proof of work the browser solves when an organization is registered (Argon2id)
IDP_REGISTRATION_POW_ZERO_BITS101 to 32Difficulty
IDP_REGISTRATION_POW_TTL20m5m to 20mHow long a challenge is valid, in whole minutes

Request ids

VariableDefaultNotes
IDP_ACCESS_RAY_ID_PREFIXrid-Prefix of the id given to each request in the access log
IDP_ACCESS_RAY_ID_HASH_LENGTH6
IDP_ACCESS_RAY_ID_RANDOM_LENGTH10The whole id must fit in 64 characters

Password manager storage

VariableDefaultNotes
IDP_VAULT_BLOBS_BLOB_LIMITabout 8 MiBLargest encrypted file the server stores (an 8 MiB attachment plus its encryption overhead). Bytes, or with B, KB, MB, GB. 1 KB to 256 MB. The browser refuses attachments over 8 MiB whatever this is, so a higher value does not allow larger attachments.
IDP_VAULT_BLOBS_ORG_QUOTA1GBAttachment storage per organization
IDP_VAULT_BLOBS_UNREFERENCED_GRACEP1DHow long an attachment nobody refers to is kept: P1D, PT12H, or a number with ms, s, m, h, d; at most 30 days

These three are read when first needed, not at start: a wrong value makes attachment requests fail, not the start.

Fixed values

ItemValue
HTTPS port8443
ACME account contactSet in the code
Password hashingbcrypt, cost 12
Backup code hashingscrypt, N = 2^14
Open organizations kept in memory256, each closed after 30 minutes unused

Ports

PortProtocolUse
8080 (SERVER_PORT)HTTPHealth check /ready and the internal paths between nodes (/internal/*). Not meant to be published.
8443HTTPSEverything else. Published as 443.

There is no listener on port 80.

ItemValue
TLS versions1.2 and 1.3
ALPNh2, http/1.1
Client certificatesNot supported
HSTSmax-age=31536000; includeSubDomains, on the HTTPS listener
TLS handshake timeout10 seconds
Time for the first byte and the request head20 seconds; also closes idle keep-alive connections
HTTP/2 pingEvery 20 seconds; the connection closes after 20 more seconds of silence
Graceful shutdown30 seconds

GET /ready on port 8080:

ProfileAnswer
none, local200 with {"ready":true}
qa, prod200 once the certificate is loaded or while the first certificate is being requested, 503 once that request has failed. The body has ready, nodeCertificate (the certificate is loaded), issuing (a request is in progress) and, after a failure, error.

Certificates

ItemValue
Names*.<landing host> on every node; also the bare landing host on the landing node
KeyECDSA P-256, stored encrypted under the master key
Challenge recordTXT _acme-challenge.<landing host>, TTL 60 seconds
DNS checkThe zone’s own nameservers are asked until they serve the record: 24 tries, 5 seconds apart, 3-second DNS timeout. Then IDP_TLS_DNS_SETTLE_DELAY passes before the challenge is answered.
RenewalWhen less than 30 days are left; checked every 6 hours
Retry after a failureAfter 5 minutes, then at doubling intervals up to 1 hour
Storagenode.sqlite on the data volume, so a restart does not request a new certificate
Custom domainsOne certificate per organization’s custom domain, requested and renewed the same way. The organization’s admin points _acme-challenge.<their domain> as a CNAME to <slug>._acme-delegation.<landing host>, and Sovrain answers the challenge there, in your zone.

Data directory

PathContent
orgs/<slug>.dbOne SQLite database per organization
orgs/<slug>.db.blobs/The organization’s password manager attachments (encrypted)
orgs/<slug>.db.pre-importThe database before the last import (one generation)
orgs/<slug>.scim, orgs/<slug>.delegationsEmpty markers: the organization uses provisioning or delegation
node.sqliteCustom-domain index, certificates, ACME account, reserved organization addresses
mek-fingerprintTies the directory to IDP_MEK
user-deletions.logOne line for each account deleted by its owner (mode 0600)

The SQLite files are not encrypted. Secrets inside them are: SAML and OpenID Connect private keys, SCIM tokens, authenticator secrets, the import key and TLS keys are encrypted under keys derived from IDP_MEK.

Steps: Back up the data volume, Restore a node from a backup.

Schema updates

ItemBehavior
node.sqliteUpdated at start, before the node serves anything. If the update fails, the node does not start.
Organization databasesEach is updated the first time it is opened after the start, by a request or a background job. One whose update fails cannot be opened; the others keep working.
Changed historyA database that records a schema change this version has with different content is refused.
LockOne process updates a database at a time. Another waits up to 30 seconds, then fails with the changelog lock stayed taken for 30 s, held by ….
Going backSchema changes are not undone. An older version is not made to run on a database a newer version has changed.

Steps: Upgrade Sovrain.

Peers file

Each line describes one node:

<app> <node> <mesh-ip> <tags>
RuleDetail
Region tagExactly one region:<name> per node; <name> matches [a-z][a-z0-9]{0,15}
Landing tagAt most one node carries landing; a node refuses to start when two do. With none, no node offers registration.
HostsLanding node: <base>. Region node: <region>.<base>. Organization: <slug>.<base>, whatever its region.
RegistrationOnly on the landing node. It reserves the address, creates <slug>.<base> CNAME <region>.<base> (TTL 300 seconds, waits up to 90 seconds for it to resolve) and asks the region node to create the organization.
Internal paths/internal/* answer 404 to any address that is not a known node
CapacityOne node per region; no failover between nodes. Why: About running Sovrain yourself

Steps: Add a region.