Skip to content

Single Sign On (OIDC)

Jump to bottom
itsDNNS edited this page Apr 30, 2026 · 3 revisions

Single Sign-On (OIDC)

Tribu supports OpenID Connect, so you can delegate authentication to an existing identity provider such as Authentik, Zitadel, Keycloak, or any other standards-compliant OIDC provider.

Use this page for the SSO feature itself. For the main deployment flow, reverse proxy examples, backups, and phone sync, use the Self-Hosting Guide.

What this feature does

  • adds a dedicated Admin > Single Sign-On section
  • supports OIDC discovery instead of provider-specific hardcoding
  • includes presets for Authentik, Zitadel, Keycloak, and a Generic fallback
  • can show an SSO button on the login page once the provider is fully configured
  • can optionally disable password login after SSO is ready
  • supports invitation-based onboarding through SSO
  • links returning users by (issuer, subject) and can also match an existing Tribu account by verified email

1. Create an OIDC client at your provider

Register Tribu as a confidential OIDC client and use these values:

  • Redirect URI / Callback URL: https://<your-tribu-domain>/auth/oidc/callback
  • Grant type: Authorization Code
  • PKCE: enabled with S256
  • Scopes: openid profile email

The email and email_verified claims are important because Tribu only links an existing account when the identity provider marks the email as verified.

Provider-specific issuer hints

Provider Issuer URL shape Notes
Authentik https://auth.example.com/application/o/tribu/ Copy the provider's OpenID Configuration Issuer value. The trailing slash matters.
Zitadel https://<instance>.zitadel.cloud Use a Web application with PKCE enabled.
Keycloak https://keycloak.example.com/realms/<realm> Use a confidential OIDC client in the realm that owns your users. Tribu can fall back to client_secret_basic if the token endpoint requires it.
Generic https://idp.example.com Any OIDC-compatible provider exposing /.well-known/openid-configuration.

2. Enable SSO in Tribu

Sign in as an admin and open Admin > Single Sign-On.

Fill in these fields:

  • Provider preset: helps with placeholders and the default login button label
  • Issuer URL
  • Client ID
  • Client secret
  • Scopes: usually openid profile email
  • Allow new accounts via SSO: needed if invite links should create new accounts through SSO
  • Disable password login: optional and only enforced once SSO is actually ready

Use Test discovery before saving if you want to confirm that the issuer URL is reachable and returns a valid discovery document.

3. Login and onboarding behavior

Existing users

If a returning user already has a linked OIDC identity, Tribu signs them in through that identity.

If no linked identity exists yet, Tribu can still match an existing Tribu account by email, but only when the identity provider returns:

  • the same email address
  • email_verified=true

Unverified emails are rejected for linking.

New users through invitation links

If Allow new accounts via SSO is enabled, invite links can carry a new family member through the entire onboarding flow without setting a local password first.

Typical flow:

  1. Admin creates an invitation in Admin > Invitations
  2. New user opens the invitation link
  3. User clicks Continue with SSO
  4. Tribu carries the invite token through the OIDC flow
  5. After the callback, Tribu creates the new account, applies the invitation preset, and signs the user in

Password fallback and recovery

Password login stays available until the admin explicitly disables it.

Even when Disable password login is turned on, Tribu only enforces that lock once OIDC is fully configured and ready. This prevents accidental admin lockout during setup.

4. Reverse proxy requirement

Keep /auth/oidc/* going through the frontend, not directly to the backend.

Why this matters:

  • the registered callback URL is /auth/oidc/callback
  • Tribu's frontend rewrites /auth/oidc/* to the backend
  • sending those routes directly to the backend in a split proxy setup can break the callback contract

If you use the official reverse-proxy examples from the self-hosting guide, you do not need extra OIDC-specific rules.

5. Secret storage model

The OIDC client secret is stored in Tribu's system_settings table as plaintext.

That follows the same trust model as JWT_SECRET in your .env file:

  • secure the host
  • secure the database volume
  • prefer encrypted storage if your threat model requires it
  • rotate the secret by clearing and re-entering it in the admin UI

6. Troubleshooting

The SSO button does not appear

Check all of the following:

  • OIDC is enabled in Admin > Single Sign-On
  • issuer URL, client ID, and client secret are set
  • discovery succeeds
  • the login page is reloaded after saving

Password login disappeared too early

That should only happen when both conditions are true:

  • SSO is ready
  • Disable password login is enabled

If SSO is not ready yet, the password form should remain visible.

Existing user was not linked

Common causes:

  • email address differs between Tribu and the IdP
  • the IdP did not return email_verified=true
  • the provider is not actually returning the email scope/claim

Invite signup did not create a new account

Check:

  • Allow new accounts via SSO is enabled
  • the invite token is still valid
  • the provider returned a verified email

Provider setup checklists

Authentik

Tribu field Authentik value
Provider preset Authentik
Issuer URL OpenID Configuration Issuer from the provider page
Client ID Application client ID
Client secret Application client secret
Redirect URI https://<your-tribu-domain>/auth/oidc/callback

Keep the trailing slash in the issuer if Authentik shows one.

Zitadel

Tribu field Zitadel value
Provider preset Zitadel
Issuer URL Zitadel instance URL
Client ID Web application client ID
Client secret Web application secret
Redirect URI https://<your-tribu-domain>/auth/oidc/callback

Use a Web application and enable PKCE.

Keycloak

Tribu field Keycloak value
Provider preset Keycloak
Issuer URL https://keycloak.example.com/realms/<realm>
Client ID Confidential client ID
Client secret Client secret
Redirect URI https://<your-tribu-domain>/auth/oidc/callback

Before disabling password login

  • Discovery test succeeds.
  • You can log in through SSO in a private browser window.
  • Your identity provider returns email and email_verified=true.
  • At least one admin can still access Tribu.
  • You understand how to re-enable password login if the IdP is unavailable.

Common errors

Symptom Likely cause
SSO button missing OIDC not enabled, discovery failed, or required fields are missing
Callback mismatch Redirect URI in IdP does not exactly match /auth/oidc/callback
Existing user not linked Email differs or IdP did not return email_verified=true
Password login still visible Password login is not disabled, or SSO is not fully ready
Invite signup fails Invite expired, SSO account creation disabled, or email not verified

Related docs

Clone this wiki locally