docs: document multiple auth providers and the callback URL change

docsite/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
 

docsite/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