From 6b22a3ca50086c6f942504ef4b994f02b4e2f536 Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Mon, 3 Aug 2026 11:05:40 +0100 Subject: [PATCH] docs: document multiple auth providers and the callback URL change --- docs/getting-started/first-login.md | 8 +++-- docs/vantage/settings.md | 56 +++++++++++++++++++++++------ 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/docs/getting-started/first-login.md b/docs/getting-started/first-login.md index 5295131..43d5b11 100644 --- a/docs/getting-started/first-login.md +++ b/docs/getting-started/first-login.md @@ -66,9 +66,11 @@ Go to **Settings → Access**. Add members with a role: Settings and organisation management require `owner` or `admin`. -If you would rather not manage passwords, configure OIDC instead see -[Settings](../vantage/settings.md#single-sign-on-oidc). OIDC is configured per -organisation, and the client secret is stored encrypted. +If you would rather not manage passwords, configure single sign-on instead: +see [Settings](../vantage/settings.md#single-sign-on). You can add more than +one identity provider; each gets its own button on the login page, and no +buttons appear at all until at least one provider is configured. Client +secrets are stored encrypted. ## Next diff --git a/docs/vantage/settings.md b/docs/vantage/settings.md index 5a95163..54894b4 100644 --- a/docs/vantage/settings.md +++ b/docs/vantage/settings.md @@ -16,6 +16,16 @@ this instance behaves" produced two half-pages and a nav entry nobody could distinguish from Settings. The old path still redirects. ::: +:::danger Upgrading breaks existing single sign-on until you re-register the callback URL +Callback URLs are now per provider instead of one shared URL for the whole +instance. If you already had single sign-on configured, it was carried +forward automatically, but its callback URL changed and **sign-in through it +will fail until you copy the new callback URL from its settings card and +register it with your identity provider**. The migrated provider's card shows +a dismissable warning as a reminder. Password sign-in is not affected by this +change, so an administrator can always sign in locally to make the update. +::: + ## Access ### Members @@ -42,20 +52,46 @@ change would be overwritten by the next sync and would leave two writers for one password hash. Manage them from [People and roles](../hq/people-and-roles.md). ::: -### Single sign-on (OIDC) +### Single sign-on -Configured per organisation: +Add as many identity providers as you need: one instance can have several at +once, each with its own name, its own button on the login page and its own +callback URL. -| Field | | -| ------------- | ---------------------------- | -| Issuer | Your provider's issuer URL | -| Client ID | | -| Client secret | Stored AES-256-GCM encrypted | +Pick a provider from the list of presets: -Sign-in then goes `/auth/oidc/start` → your provider → `/auth/oidc/callback`. +| Preset | You provide | +| ---------------------- | ------------------------------------------- | +| Microsoft Entra ID | Directory (tenant) ID | +| Google Workspace | nothing further, the issuer is fixed | +| Okta | Your Okta org domain | +| GitHub | Client ID and client secret only | +| Other (OpenID Connect) | The issuer URL of your identity provider | -Local and OIDC users coexist. Keep at least one local owner: if the provider is -misconfigured or unreachable, a local account is the way back in. +Every provider also needs a **Client ID** and **Client secret**; the secret is +stored AES-256-GCM encrypted and never shown again after you save it. + +:::info GitHub requires a verified primary email +Vantage signs a person in by their email address. GitHub is asked for the +account's addresses and only accepts one that is **both** the account's +primary address **and** marked verified: an address GitHub has not confirmed +is not proof anyone controls it. +::: + +#### Callback URL + +Each provider gets its own callback URL, shown on its settings card with a +copy button. This is the address you register with the identity provider when +you set up the application on their side: each provider is registered +separately, even if you have several with the same identity provider. + +#### Turning off password sign-in + +You can disable local (email and password) sign-in once at least one provider +is enabled. Vantage refuses to save a change that would leave nobody able to +sign in, whether that change comes from the local login toggle or from +disabling the last enabled provider. Keep at least one option open until every +person who needs access can reach the new one. ## Monitoring