Explanation
Security model
What Sovrain encrypts and what it does not, how its keys are arranged, how it handles passwords, connections and guessing, what admins are trusted with, and what has not been done yet.
An identity provider is a high-value target: whoever controls it can sign in to every connected application. This page describes how Sovrain protects what it stores and what it receives, and is plain about where that protection stops. It is meant to help you judge the risk for your organization, not to reassure you.
What is encrypted, and what is not
Each organization lives in its own database file (see Organizations and their addresses). That file is not encrypted as a whole. Most of what it holds is stored as readable data: people’s names, login names and email addresses, profile attributes, group memberships, application settings, the security history of each account and the log of emails sent. Someone who obtained a copy of the file could read all of that.
A small set of secrets is encrypted inside the file by Sovrain itself, because they are the ones that would let an attacker act as Sovrain or as a person:
- the private keys that sign OpenID Connect tokens and SAML assertions;
- the tokens Sovrain uses to provision accounts in applications over SCIM;
- the secrets behind people’s authenticator apps;
- the key used to receive an imported backup.
Other secrets are not stored in a form that can be turned back at all. Passwords are kept as bcrypt hashes with a cost of 12, backup codes as scrypt hashes, and session cookies, reset links, client secrets and similar tokens only as SHA-256 hashes of long random values. A copy of the database lets nobody sign in with them directly; a stolen password hash can still be attacked by guessing, which is what bcrypt’s cost is there to slow down.
The password manager is a separate case: its contents are encrypted in people’s browsers and the server never has the keys. Password manager security explains it.
How the keys are arranged
The encrypted secrets above sit under a short hierarchy of keys:
- a master key for the whole server, which comes from the server’s configuration when it starts and is held only in memory; the data folder keeps just a fingerprint of it, so the server refuses to start with the wrong key;
- an organization key for each organization, stored in that organization’s file, encrypted with the master key;
- data keys, one per kind of secret, stored encrypted with the organization key and used to encrypt the secrets themselves.
The arrangement means a copy of an organization’s file is not enough to recover its signing keys or SCIM tokens:
the master key is also needed, and it is not in the file. An import gives the organization a new organization key.
The master key is not kept in a hardware security module or a key management service. Whoever runs the server holds
it; on the hosted service at sovrain.net, that is us. The keys of the server’s TLS certificates are encrypted
directly with the master key.
Connections
Sovrain terminates TLS itself, in the same process that serves the pages, rather than behind a separate proxy. It uses TLS 1.2 and 1.3, gets its certificates from Let’s Encrypt, and tells browsers through HSTS to use only HTTPS for a year, including subdomains. Pages cannot be embedded in frames on other sites, which defends against tricks that overlay Sovrain’s buttons with something else.
When Sovrain itself calls out, for back-channel logout, SCIM or fetching SAML metadata, it accepts only HTTPS to public addresses and does not follow redirects. That stops an admin setting, or a crafted metadata file, from turning Sovrain into a tool for probing internal networks. Sovrain does not support client certificates.
Guessing and lockout
Sovrain does not lock accounts after wrong passwords. A lockout rule lets anyone who knows a login name lock that person out on purpose, as often as they like, which turns a security feature into a way to deny service. Instead, Sovrain limits how fast attempts can be made: sign-in attempts are counted per network address and per typed login name, wrong second-step codes are limited per account, and password resets, registrations and protocol endpoints have their own limits. The numbers are in Limits.
The trade-off is that rate limits slow guessing down rather than stopping it. They protect well against bulk attacks and badly against a weak password that is guessed early. That is why the policy on two-step sign-in matters more than the password rules. Most of these limits are held in the memory of each server, so a restart resets them; the limit on wrong second-step codes is counted from the account’s security history and survives a restart.
Sovrain’s password rules are deliberately few: at least 8 characters, at most 72 bytes, which is where bcrypt stops reading. It does not demand character classes and does not check sign-in passwords against breach lists.
What admins can do
Admins are trusted with a great deal, and it is worth knowing exactly how much before choosing them.
Any admin, not only owners, can add anyone to Admins or Owners, change every policy, delete applications and suspend or remove people, including other owners as long as one active owner remains. Any admin can also export the whole organization. The export contains the private signing keys, the SCIM tokens and the password hashes; it can be encrypted to a key you choose; every export needs the admin’s password, and an unencrypted one also an explicit confirmation, but the choice is the admin’s. Importing a backup, which replaces the whole organization, is reserved for owners.
Admins can also act as any member who is not an admin. Generate link on a user’s page shows the admin a reset link valid for 24 hours; whoever opens it signs in as that user, and when the link also resets two-step sign-in, without a second step. While delegation is on, an admin can also create a delegation for any pair of people, including one with themselves as the delegate. The person is emailed about a reset only when Email the user is on in the recovery policy (it is by default) and their address is verified.
There are also things admins cannot do. They cannot see anyone’s password or read anyone’s password manager. They cannot add a second step for someone else, only remove or reset it, and the person is emailed if Email the user is on and their address is verified. Resetting another admin’s sign-in needs an owner. And many sensitive admin actions, such as changing the two-step or recovery policy, need a sign-in from the last few minutes.
Two details often surprise people. When an admin removes a user, the account is marked as removed but its data stays in the database and in exports; only a person deleting their own account removes their profile, sign-in methods, group memberships and password manager data. Records that name them stay: the log of emails sent to them, the account’s security history and application activity (login and network address), and delegation events; the server’s deletion log keeps their email address. And there is no single log of admin changes: Sovrain keeps a security history for each account and an activity feed for each application, but no organization-wide record of who changed which setting.
Building it small
Sovrain is written in Rust, and the protocol code, such as SAML signatures, JSON Web Tokens and WebAuthn, is written as part of Sovrain rather than taken from third-party libraries; the cryptographic primitives underneath come from established libraries: aws-lc-rs on the server (also behind its TLS), the bcrypt, scrypt and Argon2 crates for the password-hashing functions aws-lc-rs lacks, and @noble and hash-wasm in the browser for the password manager. This keeps the amount of code that handles security small and readable in one place. It also means that code has been exercised by fewer people than the most widely used open-source libraries. Both are true, and you should weigh them.
What has not been done
Sovrain has had no independent security audit and no external penetration test so far. Reviews of the code have been internal. Sovrain holds no security certification. If your organization needs any of these before adopting an identity provider, Sovrain does not meet that requirement today.
Related pages
- Two-step sign-in
- Sessions and sign-out
- Roles: members, admins and owners
- Make someone an admin
- Export format
- Server configuration, for operators who run Sovrain themselves