How-to guide
Use your own domain
Serve sign-in from a domain your organization owns, such as login.acme.example, and switch your applications over to it.
This guide moves your organization’s sign-in from https://acme.sovrain.net to a domain you own, for example
https://login.acme.example. Sovrain issues and renews the HTTPS certificate for it.
An organization can have one custom domain.
Before you start
You need access to the DNS settings of the domain.
Activating the domain changes your organization’s identity. Read this before step 4:
- the OpenID Connect issuer and every SAML entity ID change to the new domain, so every connected application stops working until it uses the new values;
- passkeys and security keys stop working. People who have no authenticator app cannot finish signing in until they use a backup code, recover by email if your organization allows it, or you reset their two-step sign-in. Only then can they add their keys again. See Set up account recovery and Reset someone’s two-step sign-in;
- password manager passkeys and remembered browsers stop working too, and the dialog does not count them. People unlock with their password manager password or recovery key; see Unlock the vault with a passkey;
- everyone signs in again at the new address. Existing sessions are not ended, and refresh tokens keep working.
Plan the switch for a quiet moment and have access to every application’s SSO settings at hand.
1. Add the domain
- On your home page, under Administration, select Open admin, then select Custom domain in the admin menu.
- In Domain, type the host name, for example
login.acme.example. Use a subdomain you control. IP addresses and addresses undersovrain.netare not allowed. - Select Continue.
Adding the domain changes nothing for your people yet: they keep signing in at acme.sovrain.net.
2. Create the DNS records
Sovrain shows Add two records at your DNS provider: two CNAME records, each with a Name and a Target to copy.
- At your DNS provider, create both CNAME records exactly as shown:
- the first, for the host itself, sends sign-in traffic to Sovrain;
- the second,
_acme-challengefollowed by your host, lets Sovrain get the HTTPS certificate.
- Turn off any proxy or CDN for both records. They must point straight at the target.
- Back in Sovrain, select I’ve added the records.
Keep both records for as long as you use the domain: the second one is needed again at every certificate renewal.
3. Wait for the checks
Sovrain shows Checking followed by your host, with a list of checks. It checks again every 15 seconds; select Check now to check at once. DNS changes can take a while to appear.
When every check passes, the title changes to your host followed by is verified, and the domain is Ready.
4. Activate the domain
- Select Activate….
- Read the dialog. It shows the old and new OIDC issuer and SAML entity ID, which applications need updating, and how many people will have to add their passkeys and security keys again.
- Select Activate.
The domain is now Active. acme.sovrain.net redirects to it, except the pages you need to recover from a broken
domain.
5. Update your applications
Under Endpoints, Sovrain lists the new values: OIDC issuer, OIDC discovery and SAML entity ID.
- In every OpenID Connect application, replace the issuer or discovery URL. The client ID, secret and redirect URIs stay the same.
- In every SAML application, replace the identity provider’s entity ID, single sign-on URL and metadata URL. The easiest way is to give the application the metadata again from its Identity Provider tab.
Tell your people to add their passkeys and security keys again, under Profile & settings, Security, once they are signed in (see Before you start): Add a security key or passkey.
If the domain stops working
Under Endpoints, Recovery gives an address on acme.sovrain.net, for example
https://acme.sovrain.net/admin/domain. It works even when your own domain is down. Note it somewhere safe. From
there you can remove the domain.
The overview also warns with Not routing when the host no longer points at Sovrain, and with Renewal at risk
when the certificate cannot be renewed, usually because the _acme-challenge record is gone.
If you want to stop using the domain
- On the Custom domain page, under Danger zone, select Remove domain….
- For an active domain, type the host name to confirm, then confirm.
Every address goes back to acme.sovrain.net, including the OIDC issuer and SAML entity IDs. Applications need
their old settings again, everyone signs in again, and passkeys and security keys stop working again, with the same
effects as described in Before you start.
To abandon a domain before activating it, select Cancel setup while it is being checked, or Remove followed by the host name once it is ready. Nothing changes for your people.
If you want a different domain
While a domain is still being set up, select ← Use another domain. Once it is active, remove it first, then add the new one.