Single Sign-On (SSO)

Let your team sign in to tela with their existing company accounts. tela supports per-organization OIDC SSO — connect any standard OpenID Connect identity provider (Microsoft Entra ID, Okta, Google Workspace, Auth0, Keycloak, …) to an organization, and members sign in with one click instead of a separate password.

[!NOTE] SSO is additive — a new front door, not a replacement. Accounts, organizations, and space access work exactly as before; once your provider confirms who someone is, tela runs the same provisioning it uses for email sign-up.

Two kinds of federated sign-in

tela has two distinct features people often conflate. This guide is about the first.

How it works

When someone enters their work email at the login screen, tela matches the email domain to an organization that has an SSO connection, shows a Sign in with SSO button, and hands off to that org's identity provider. (On the org's own [[Custom domains|custom domain]] the org is already known, so the button shows up-front with no email prompt.)

sequenceDiagram
  participant U as User
  participant T as tela
  participant I as Your IdP
  U->>T: Enter work email at /login
  T-->>U: "Sign in with SSO" (matched by email domain)
  U->>I: Redirected to IdP (OIDC authorize + nonce)
  I-->>U: Authenticate & consent
  I->>T: Redirect back with auth code
  T->>I: Exchange code, verify ID token
  T-->>U: Linked or provisioned — session set

After the provider confirms the identity, tela resolves the account in three steps:

1. Known identity — this provider account has signed in before → that user.
2. Auto-link — the asserted email matches an existing tela account and the email's domain belongs to this org → the provider identity is attached to that account (no duplicate).
3. Create — otherwise a fresh account is provisioned with the IdP-asserted email (stored pre-verified) and no usable password.

[!IMPORTANT] An org's identity provider is only trusted to auto-link accounts in its own mapped email domains. That's why mapping your domain to the org (Step 3) is required — it's both how the SSO button is discovered and the guard that lets the IdP link only its own users.

Before you start

[!IMPORTANT] SSO is an Enterprise feature. On telawiki.com the organization must be on the Enterprise plan; on a self-hosted instance it requires an Enterprise license key (Settings → License). See [[Plans & billing]]. Without the entitlement, the connection can't be saved and the Sign in with SSO button won't appear.

• You are an instance admin (SSO configuration is instance-admin only).
• The organization exists in tela with its members.
• You can administer an OIDC identity provider for your company.
• You know the email domain(s) your team uses (e.g. acme.com).

Step 1 — Register an application with your identity provider

Create an OIDC application (sometimes called an "app registration", "client", or "integration") in your provider. The one value tela needs you to register on the provider side is the redirect URI:

https://<your-tela-host>/api/auth/sso/org/callback

On the hosted instance that's https://telawiki.com/api/auth/sso/org/callback. This single org callback serves every organization — the org identity travels in a signed state parameter — so you register it once per provider, regardless of how many orgs you connect.

From the provider you'll collect three things: an issuer URL, a client ID, and a client secret.

:::tabs

Microsoft Entra ID

1. Entra admin center → Identity → Applications → App registrations → New registration.
2. Supported account types: Accounts in this organizational directory only (single tenant).
3. Redirect URI → platform Web → https://<your-tela-host>/api/auth/sso/org/callback.
4. From Overview, copy the Application (client) ID and the Directory (tenant) ID.
5. Certificates & secrets → New client secret → copy the secret Value (shown once).
6. Token configuration → Add optional claim → ID → email. Entra v2.0 does not always emit an email claim by default; adding it here avoids the most common failure.
7. Your issuer is https://login.microsoftonline.com/<tenant-id>/v2.0 (tenant-specific, not common).

[!WARNING] If you skip step 6, users whose directory mail attribute isn't set will be rejected with "your account has no usable email address." tela requires the email claim.

Okta

1. Admin → Applications → Create App Integration → OIDC → Web Application.
2. Sign-in redirect URI → https://<your-tela-host>/api/auth/sso/org/callback.
3. Assign the app to the users/groups who should have access.
4. Copy the Client ID and Client secret.
5. Your issuer is your Okta authorization server, e.g. https://<your-org>.okta.com or https://<your-org>.okta.com/oauth2/default.

Okta emits a verified email claim by default — no extra claim configuration needed.

Google Workspace

1. In Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID → Web application.
2. Authorized redirect URI → https://<your-tela-host>/api/auth/sso/org/callback.
3. Copy the Client ID and Client secret.
4. Your issuer is https://accounts.google.com.

Google's issuer is shared across all Google accounts — scoping to your company happens through the org domain mapping (Step 3), which restricts auto-linking to your domain.

Generic OIDC

Any provider that supports OpenID Connect discovery works (Auth0, Keycloak, JumpCloud, Ping, …):

1. Create a Web / confidential client using the authorization code flow.
2. Register the redirect URI https://<your-tela-host>/api/auth/sso/org/callback.
3. Ensure the openid, email, and profile scopes are allowed.
4. Use the provider's issuer URL — it must serve <issuer>/.well-known/openid-configuration. :::

Step 2 — Configure the connection in tela

As an instance admin, go to Settings → Organizations, click Manage on the org, switch to the Single sign-on tab, and fill in:

Click Save connection. tela runs OIDC discovery against the issuer the moment you save, so a wrong issuer or tenant ID is rejected immediately rather than failing at first login.

[!TIP] Keep Require SSO off until you've confirmed a successful sign-in. With it off, password login still works as a fallback, so a misconfiguration can't lock anyone out.

Step 3 — Map your email domain to the organization

In Settings → Organizations, use the Auto-join domains section to map your company's email domain(s) (e.g. acme.com) to this org. (The org's Single sign-on tab lists the mapped domains read-only, so you can confirm them at a glance.) This is required — without it the Sign in with SSO button won't appear (it's resolved by email domain), and a returning user with an existing tela account won't be auto-linked (the IdP is only trusted for its mapped domains), so they'd get a duplicate account or an error.

Step 4 — Test it

1. Sign out and go to /login.
2. Enter an email at your mapped domain (you@acme.com).
3. Click Sign in with SSO → you're sent to your provider → authenticate → you land back in tela, signed in.

If your existing tela account uses that same email, the provider identity links to it. Otherwise a new SSO account is provisioned.

Enforcing SSO

Once SSO works, turn on Require SSO in the org's Single sign-on tab. After that, password login is refused (403) for any account whose email domain belongs to the org — those users must use the SSO button.

[!NOTE] Instance admins are exempt from enforcement, so a broken SSO connection can never lock the operator out of the instance.

Troubleshooting

Failed sign-ins bounce back to /login with an error. The message points at the step that broke:

A note on SAML

tela speaks OIDC, not SAML, directly. If you have a SAML-only identity provider, run a broker such as Dex that talks SAML upstream and presents tela a standard OIDC issuer — tela connects to the broker exactly like any other OIDC provider.

See also: [[Administration]] · [[Custom domains]] · [[Self-Hosting]] (for instance-wide social login)