Configure OIDC / BYO-OIDC SSO

SupaCloud offers two independent SSO paths (ADR 0031):

• Instance OIDC — the operator configures one shared IdP via environment variables. Requires the Enterprise edition.
• BYO-OIDC — an organization owner configures their own IdP in the SupaCloud UI. Requires the sso_oidc_byo entitlement on the organization’s plan.

Both paths use the same email-first discovery flow at login. They can coexist on the same instance.

Note

Proxy-mode SSO (AUTH_PROVIDER=authelia_proxy or oidc_proxy) is a separate deployment topology for operators who place a trusted upstream reverse proxy in front of SupaCloud. It is configured entirely via env vars and is not entitlement-gated. Refer to auth-authelia.md if that is your use case.

---

Part A — Instance OIDC (Enterprise, self-hosted)

Prerequisites

• Enterprise edition license active (see Apply an edition license).
• An OIDC-compliant IdP (Keycloak, Okta, Entra, Google Workspace, etc.) with a confidential client you can configure.
• The redirect URI you will register: https://<your-domain>/api/auth/oidc/callback.

Steps

1. Register a client in your IdP.

   Set the allowed redirect URI to https://<your-domain>/api/auth/oidc/callback. Note the Issuer URL, Client ID, and Client Secret.

2. Set the environment variables.

   Variable	Required	Notes
   AUTH_PROVIDER	Yes	Set to oidc
   OIDC_ISSUER_URL	Yes	IdP discovery URL (e.g. https://accounts.example.com)
   OIDC_CLIENT_ID	Yes	Client ID from your IdP
   OIDC_CLIENT_SECRET	Yes	Client secret; use OpenBao/vault in production
   OIDC_REDIRECT_URL	Recommended	Full redirect URI registered with the IdP
   OIDC_SCOPES	Optional	Space-separated; defaults to openid email profile
   OIDC_PKCE_ENABLED	Optional	true (default) or false
   OIDC_TOKEN_AUTH_METHOD	Optional	basic (default) or post

3. Restart the server.

   Instance OIDC appears in the /config auth.methods list only when the edition resolves to enterprise. A misconfigured or absent edition secret silently omits it — verify with the Feature availability panel (/api/admin/feature-availability).

4. Test the login flow.

   Navigate to https://<your-domain>/login. The email-first step should offer the OIDC button. Complete the IdP round-trip and confirm you land in the app.

Single-IdP auto-redirect

On a standalone Enterprise instance with exactly one SSO realm, SupaCloud auto-redirects unauthenticated visitors straight to the IdP — skipping the login form entirely. This is controlled by the sso.auto_redirect field in /config, derived at boot by services::auth::sso_policy.

Override the default with two env vars:

Variable	Values	Effect
SUPACLOUD_SSO_AUTOREDIRECT	on / off	Force auto-redirect on or off regardless of realm count or edition
DEFAULT_SSO_ORG	org slug	Pin a specific BYO org as the auto-redirect target

off always wins. A visitor can always reach the full method picker via /login?switch=1.

---

Part B — BYO-OIDC per organization (SaaS)

Organization owners whose plan includes the sso_oidc_byo entitlement can configure their own IdP without any operator involvement.

Prerequisites

• Organization owner or admin role.
• A plan that grants sso_oidc_byo (Enterprise plan or a workspace with that entitlement).
• An OIDC-compliant IdP with a confidential client.
• DNS write access to claim the organization’s email domain(s).

Steps

1. Open Organization Settings → SSO.

   Navigate to Settings → Organization → SSO / OIDC. If the section shows an upgrade prompt (an ‘available on a higher plan’ banner with an Upgrade CTA and a blurred preview) instead of the configuration form, your current plan does not include sso_oidc_byo.

2. Enter the IdP configuration.

   Field	Notes
   Issuer URL	IdP discovery endpoint
   Client ID	From your IdP
   Client Secret	Write-only — never shown again after saving
   PKCE	Enabled by default; disable only if the IdP does not support it
   Scopes	Default openid email profile

   Save the configuration. The server stores the client secret encrypted using the instance credential-encryption key.

3. Register and verify email domains.

   Under Domains, add each domain whose users should be routed to this IdP (e.g. example.com). For each domain:

   a. SupaCloud generates a verification token and shows the required DNS TXT record:

   supacloud-domain-verification=<token>

   b. Publish that TXT record at the root of the domain (or @). c. Click Verify in the UI (or call POST /api/v1/org/oidc/domains/{id}/verify). SupaCloud performs a DNS lookup and marks the domain verified on success.

   Caution

   Domain claims are globally unique among verified rows. If another organization has already verified a domain you need, contact support.

4. Set the redirect URI in your IdP.

   Register https://<your-domain>/api/auth/oidc/byo/<org_slug>/callback as an allowed redirect URI. The <org_slug> is your organization’s URL slug.

5. Test the login flow.

   On the shared login page, enter an email at a verified domain. SupaCloud discovers the organization via non-enumerating email-domain lookup and redirects to the BYO IdP. After a successful IdP round-trip the user lands in the app.

Remembered-realm cookie and bookmarkable entry URL

After a successful BYO callback, SupaCloud sets an sc_sso_org cookie (HttpOnly, 90-day hint). On the next visit the SSR login gate reads the cookie and issues a 307 straight to the IdP — zero clicks for returning users.

Share or bookmark https://<your-domain>/sso/<org_slug> as a direct IdP entry URL (also suitable as an IdP portal app tile).

To reset the remembered realm (shared browser, stale config), visit /api/auth/sso/forget or use /login?switch=1.

---

Management API (IaC / scripted provisioning)

BYO-OIDC can be managed declaratively via the Management API (org-owner token):

Method	Path	Effect
GET	/api/management/v1/organizations/{org_id}/oidc	Read current config
PUT	/api/management/v1/organizations/{org_id}/oidc	Upsert IdP config
DELETE	/api/management/v1/organizations/{org_id}/oidc	Remove config

See the Management API reference for request/response schemas.

---

Troubleshooting

OIDC button does not appear on the login page. Confirm AUTH_PROVIDER=oidc and that the edition resolves to enterprise (/api/admin/feature-availability). Check that OIDC_ISSUER_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET are all set and non-empty.

BYO-OIDC configuration form is replaced by an upgrade prompt in Organization Settings. The sso_oidc_byo entitlement is not granted on the active plan. Upgrade the organization’s subscription or contact the instance operator.

Domain verification fails. DNS propagation can take minutes. Re-check the TXT record with dig TXT <domain> and retry. The record must be published at the domain apex.

Auto-redirect loops after an IdP error. Navigate to /login?switch=1 to reach the full method picker and clear the sc_sso_org cookie. Then diagnose the IdP callback error in the server logs.

Login bounces back to the login form and the logs mention an unverified email. SupaCloud only accepts an email address the IdP marks as verified — the email_verified claim (in the ID token, or in a matching userinfo response) must be true. Configure your IdP to assert email_verified for the email scope; an IdP that omits the claim or sends false is rejected. This prevents a misconfigured or hostile IdP from authenticating a user as an address they do not control. Both instance OIDC and BYO-OIDC enforce this.