Sovrain
  1. Documentation
  2. Your organization

Explanation

Organizations and their addresses

Why every Sovrain organization is a separate world with its own file, address and accounts, and what changes when it moves to your own domain.

An organization is the unit everything else in Sovrain hangs from: people, groups, applications, policies, signing keys and the password manager all belong to exactly one organization. This page explains how far that separation goes, why an organization’s address matters so much, and what happens when you give it your own domain.

One organization, one file

Each organization is stored in its own SQLite database file on the server of its region, with the password manager’s attachments in a folder next to it. There are no tables shared between organizations where a missing filter could show one company’s people to another: Acme’s data and another customer’s data are not even in the same file.

Several properties follow from this. Deleting an organization means deleting its file, which is what happens when the last member deletes their account: the database and its attachments go, and the address becomes free again. An export carries the organization’s people, groups, applications and settings in one bundle, and an import replaces the organization in one swap (see Restore or move your organization). And the region you choose when you create the organization is simply the server where the file lives, which is why it cannot be changed later. Regions and availability covers that side.

The address is part of the identity

When Jane created Acme she chose the organization URL acme, and Sovrain gave the organization the address https://acme.sovrain.net. That address is not just where people sign in. It is the base of everything an application learns about Sovrain:

  • the OpenID Connect issuer, https://acme.sovrain.net, which appears as iss in every token and which apps compare byte for byte;
  • the SAML identity provider entity ID of each app, such as https://acme.sovrain.net/saml/grafana;
  • the sign-in, sign-out, metadata and key addresses that apps fetch.

An application configured for Acme has these values written into its own settings. If the slug could be renamed, every connected application would stop trusting Sovrain at the same moment. That is why the slug cannot be changed after registration. The organization name cannot be changed either: it is shown on the organization’s pages and next to the codes in people’s authenticator apps, where a silent rename would confuse more than help.

The address does not carry the region. acme.sovrain.net points at whichever regional server holds Acme, so apps and people never need to know where the data lives.

Accounts live inside one organization

A Sovrain account belongs to one organization. If Anna works for two companies that both use Sovrain, she has two separate accounts, each with its own password, second step and sessions, even if both use the same email address. Signing in to one organization never signs her in to the other, and an admin of one organization has no view of the other.

This is a deliberate fit for workforce identity: the organization owns the account, decides who may have one, and removes it when the person leaves. The trade-off is that a person who belongs to several organizations manages several accounts. On sovrain.net itself, Sign in therefore first asks for the organization’s address and then sends you to that organization’s own sign-in page.

Your own domain

An organization can have one custom domain, such as login.acme.example. While the domain is only added and checked, nothing changes for anyone. When an admin activates it as the primary address, it becomes the canonical address of the organization, and everything that was derived from acme.sovrain.net is derived from it instead: the issuer becomes https://login.acme.example, and the SAML entity IDs move with it.

Sovrain does not try to hide this behind a redirect alone, because the identifiers inside tokens and assertions are not addresses that a redirect can fix. An app that still expects the old issuer refuses the new tokens. So activating a domain is a change that every connected application has to follow. People sign in again at the new address, because their browser’s session belongs to the old one; existing sessions are not ended, refresh tokens keep working and applications receive no sign-out. Visitors who still open acme.sovrain.net are redirected to the new domain, except for sign-in and the custom domain settings, which stay reachable on the old address so that an admin can still get in if the custom domain’s DNS breaks.

The practical lesson: if you want your own domain, it is cheapest to activate it before you connect many applications. The steps are in Use your own domain.

Why passkeys and security keys stop working

The one part of a domain change that people feel directly is their passkeys and security keys. These follow the WebAuthn standard, in which every key is created for one relying party ID, and for Sovrain that ID is the organization’s host name. A key made on acme.sovrain.net belongs to acme.sovrain.net and to nothing else. The browser simply will not offer it on login.acme.example.

That binding is exactly what makes these keys resistant to phishing: a look-alike site on another host cannot ask for them. The same property means Sovrain cannot carry them over to a new domain; no server-side setting can make a key answer for a host it was not made for. After the switch, Sovrain tells people which keys were added on the old host and asks them to add them again once they have signed in. Authenticator apps and backup codes do not depend on the host, so they keep working, and people who have one of those are not locked out.