Sovrain
  1. Documentation
  2. Self-hosting

Explanation

Running Sovrain yourself

How a Sovrain installation of your own is put together, and why it has one node per region, one master key, certificates only through your DNS provider and no reverse proxy.

When you run Sovrain yourself, a few things work differently from what you may know from other servers: a region is one machine, the master key cannot be replaced, certificates come only through your DNS provider and nothing may stand in front of the HTTPS port. This page explains how an installation is put together and why it has these limits. The steps are in the how-to guides, and every setting is in Server configuration.

What the same design means for the people who sign in is described in About regions and availability. That page is written for the hosted service at sovrain.net, but what it says about one server per region and about restarts holds for your installation too.

The landing node and the region nodes

An installation has one address of its own, the landing host, such as sso.example.com. Every organization gets an address one level below it: acme.sso.example.com. Behind these addresses run one or more nodes. Each node serves one region and keeps the data of that region’s organizations on its own volume, one SQLite database per organization. A node also has an address of its own, the region host, such as eu.sso.example.com. A region host is never an organization’s address, which is why no organization can take a region’s name.

One node is also the landing node. It serves the landing host: the registration form, and the sign-in page that asks people for their organization’s address. It also keeps the list of organization addresses that are taken in every region, so that no address is given out twice. It holds no data of organizations in other regions.

When Jane registers Acme in region us, the landing node reserves acme, adds acme.sso.example.com to your DNS zone as a CNAME to us.sso.example.com, and asks the us node over the private network to create the organization. From then on, Acme’s traffic goes straight to the us node; the landing node is not in the way.

This explains what happens when a node is down. Without the landing node, nobody can register and the landing host does not answer, but organizations in every other region keep working, because their addresses point at their own nodes. Without the us node, Acme is unavailable and registration in us fails. The landing node then keeps the address it reserved, because it cannot tell whether the organization was created, and frees it in a later pass once it can ask the us node again.

The nodes learn about each other from the peers file, which lists every node with its private address, its region and whether it is the landing node. A node reads the file again each time it needs it, so a new region appears without a restart. At most one node is the landing node; with none, no node offers registration. Calls between nodes travel over plain HTTP on the private network, and a node accepts them only from the addresses in the peers file. That is why the private network must deliver them with their addresses unchanged.

One node per region, and no failover

Each region is served by exactly one node, and nothing stands in for it. An organization’s database is a file on that node’s volume. There is no shared storage, no database server that a second node could also reach, and no copying of data between nodes, so a second node would have nothing to take over with. Sovrain refuses a peers file in which two nodes serve the same region.

The consequences follow from that:

  • While a node restarts, for an upgrade or after a failure, its organizations are unavailable. Plan upgrades for a quiet time.
  • A second region adds a location and room for more organizations, not redundancy.
  • An organization cannot move to another region, because that would mean moving its file to another node.
  • If a node’s server is lost, the backup of its volume is the way back. See Restore a node from a backup.

The design is simple on purpose: one file per organization on one node is easy to back up, to restore and to keep in one place. The price is that each node is a single point of failure for its region.

One master key

Every secret a node stores is encrypted under keys that hang off one master key, IDP_MEK. Each organization has its own key, wrapped under the master key, and that key protects the organization’s signing keys, SCIM tokens and authenticator secrets. The node’s TLS keys are wrapped under the master key too. Sovrain keeps the master key only in memory. On the volume there is only its fingerprint, which the node writes on its first start and compares on every later start, so a node started with another key stops at once instead of failing later at the first secret it cannot open.

Sovrain has no way to change the master key. No command and no setting re-encrypts the data under a new key, so the key you create on the first day protects the node’s data for as long as that data exists. Two things follow:

  • If you lose the key, you lose every organization on the node, and a backup does not help, because the backup is encrypted under the same key.
  • A key that leaks cannot be replaced. On its own it opens nothing, but together with the volume or a backup of it, it opens every secret. Keep the key and the backups in different places.

Each node pins its own volume to the key it started with, so the nodes of an installation may have different keys. Giving every node the same key only means you have one key to keep safe instead of several.

Without a profile and in the local profile, Sovrain uses a development key written in its source code. That is why data stored that way is protected by nothing of yours, and why those profiles are only for trying Sovrain out, as in Try Sovrain on your computer.

HTTPS inside Sovrain, through your DNS

A node with the qa or prod profile terminates TLS itself and gets its certificates itself, from Let’s Encrypt with the ACME DNS-01 challenge. To answer that challenge it writes records into your DNS zone through the API of your DNS provider, and it uses the same access for more than its own certificate:

  • One certificate for every organization address. The certificate for *.sso.example.com covers every organization, including those registered tomorrow. Let’s Encrypt issues a certificate for such a wildcard name only through a DNS challenge.
  • An address for every new organization. At registration the landing node adds the organization’s CNAME to the zone.
  • Certificates for organizations’ own domains. When Acme uses login.acme.example, Acme’s admin points _acme-challenge.login.acme.example at a name in your zone, and the node answers the challenge there. Sovrain never needs access to Acme’s DNS.

The challenges that work without DNS access, HTTP-01 and TLS-ALPN-01, cannot do the first of these, and a certificate you bring yourself could not cover the organizations’ own domains, which appear while Sovrain runs. So Sovrain has no other way to get certificates. It talks to the DNS provider’s API directly, and it supports two providers, ClouDNS and OVH.

For the same reason there is no profile for running behind a reverse proxy that terminates TLS. The qa and prod profiles always open their own HTTPS listener, and no setting turns it off. The node gets certificates while it runs, for names that appear while it runs; a proxy in front of it would have to hold the same certificates and keep them current. The node also takes each client’s address from the connection itself, for rate limits, unless you set IDP_RATE_LIMIT_TRUST_PROXY. Port 443 must therefore reach the container unchanged.

Only the profiles without TLS, none and local, serve plain HTTP, and they are meant for development.