Sign in with your identity provider

People sign in to Sail with the work accounts they already have. Sail connects to your identity provider over OpenID Connect, and never stores passwords. Multi-factor sign-in, password rules and account lockout all stay in your provider, where you already manage them.

Register Sail in your provider

Create a new app in your identity provider with these settings:

Setting	Value
Type	OpenID Connect, web application, with a client secret
Redirect URI	`https://sail.example.com/api/v1/auth/callback`, using your Sail address
Scopes	`openid`, `email`, `profile`, and `offline_access` if your provider offers it

The setup wizard shows the exact redirect URI, with a Copy redirect URI button.

From the new app, note three things for Sail: the Issuer URL, the Client ID and the Client secret.

Sail gives you two rules. Use either or both.

Rule	Use it when	Example
Allowed email domains	Everyone with a company email should get Sail.	`northwind.com, northwind.co.uk`
Required group	Only some people should get Sail, such as during a pilot.	`sail-users`

With both set, people need to match both. With neither set, only owners can sign in, so a missing rule never opens Sail to everyone in your provider.

Accounts are created the first time someone signs in. There’s nothing to invite or import.

Enter the details

In the setup wizard: the first step, Sign-in provider, asks for each of these. See First setup.

For a scripted install, set them before the first start:

SAIL_OIDC_ISSUER=https://login.example.com/realms/northwind
SAIL_OIDC_CLIENT_ID=sail
SAIL_OIDC_ALLOWED_DOMAINS=northwind.com
SAIL_OIDC_REQUIRED_GROUP=sail-users

Put the client secret in a file, never in .env, and start with the identity Compose file:

printf %s '<client secret>' > secrets/oidc-client-secret
docker compose -f compose.yaml -f compose.identity.yaml up -d

Settings from the environment show as read-only in the wizard, which then starts at Owner account.

Sync teams from groups

If your provider sends group membership, Sail can keep teams in step with it. Finance in your directory becomes Finance in Sail, and people join and leave as their groups change.

Make your provider put groups in the ID token, in a claim called groups. In Keycloak, add a group membership mapper. In other providers, look for a “groups claim” setting on the app.
In Sail, go to Admin → Teams → Create team.
Tick Sync members from a provider group, and type the group exactly as it appears in the token.

Members update at each person’s next sign-in, or within the hour.

Some providers send group IDs rather than names, and some don’t send groups at all. Check a real ID token to see what yours sends. If groups arrive in a claim with a different name, such as roles, set SAIL_OIDC_GROUPS_CLAIM to that name.

Claim	Used for
`iss` and `sub`	Who the person is. Sail never identifies people by email, so changing an email doesn’t create a new account.
`email`	Showing who someone is, and the allowed-domains rule. An email your provider marks as unverified doesn’t pass the rule.
`name`	The name shown in Sail
`groups`	The required-group rule and team sync
`job_title`, `department`	The first things Sail remembers about someone, if memory is on

Sessions and removal

Sessions are kept on the server and sent as a secure, HTTP-only cookie. Your provider’s tokens never reach the browser.
People must sign in again after 12 hours idle, or 7 days at most. Change both in Policies.
Every hour, Sail re-checks each person with your provider. If the provider refuses, or someone no longer matches your rules, their sessions end. The audit log records it.
If your provider is down, Sail waits instead of signing people out. Only new sign-ins are blocked.

Common problems

What you see	What to check
“Checking the provider” fails in the wizard	The issuer URL must be the base address, with no `/.well-known/…` on the end. Sail must be able to reach it over HTTPS.
The provider says the redirect URI doesn’t match	It must be exactly `https://<your Sail address>/api/v1/auth/callback`.
Someone is turned away after signing in	Their email domain or group doesn’t match your rules. Check the groups in their ID token.
A provider on your private network can’t be reached	Add its host to `SAIL_OUTBOUND_ALLOW`. If it uses a private certificate authority, set `SSL_CERT_FILE` (see Configuration).
Everyone is locked out	Run `docker compose exec sail sail admin recover` for a one-time owner link.

SAML isn’t supported directly. If your provider only speaks SAML, put a broker in front, such as Keycloak or Entra ID.