sencho/docs/features/sso.mdx

---
title: SSO & LDAP Authentication
description: Authenticate with your existing identity provider, including LDAP, Google, GitHub, Okta, and any spec-compliant OIDC provider.
---

Sencho lets your team sign in using existing identity providers instead of managing separate credentials. SSO works **alongside** password authentication; it does not replace it. SSO is available in every Sencho edition; higher tiers add turnkey presets and enterprise directory support.

## Supported providers

| Provider | Protocol | Tier | Notes |
|----------|----------|------|-------|
| **Custom OIDC** | OpenID Connect | Community | Any spec-compliant OIDC provider: Authelia, Keycloak, Authentik, Zitadel, KanIDM, Pocket ID, and more |
| **Google** | OpenID Connect | Skipper | One-click preset for Google Workspace or personal Google accounts |
| **GitHub** | OAuth 2.0 | Skipper | One-click preset for GitHub personal accounts and GitHub orgs |
| **Okta** | OpenID Connect | Skipper | One-click preset for any Okta org or Okta-compatible IdP |
| **LDAP / Active Directory** | LDAP bind + search | Admiral | Works with OpenLDAP, Active Directory, FreeIPA, and any LDAPv3 server |

<Tip>
  **Self-hosters on the Community tier** can still integrate Google, GitHub, Okta, or any other identity provider by using the Custom OIDC option pointed at the provider's discovery endpoint. The paid-tier presets add one-click configuration and provider-specific defaults; the underlying protocol is the same.
</Tip>

## How it works

### LDAP flow

1. User enters their directory username and password on the Sencho login page
2. Sencho binds to LDAP with a service account, searches for the user, then verifies their password
3. If this is their first login, a Sencho account is automatically created
4. Sencho issues a JWT and the user is logged in, identical to a password login

### OIDC / OAuth flow (Google, GitHub, Okta, Custom OIDC)

1. User clicks the provider button on the login page (e.g., "Sign in with Google")
2. Browser redirects to the identity provider for authentication
3. After granting consent, the provider redirects back to Sencho with an authorization code
4. Sencho exchanges the code for tokens, verifies the ID token, and reads user information
5. If this is their first login, a Sencho account is automatically created
6. Sencho issues a JWT and redirects to the dashboard

All OIDC flows use **PKCE** (Proof Key for Code Exchange) and a **state parameter** for CSRF protection.

## Auto-provisioning

When a user logs in via SSO for the first time, Sencho automatically creates a local account:

- **Username** is derived from their identity provider profile (display name, email prefix, or login handle)
- **Role** is assigned based on [role mapping](#role-mapping); defaults to Viewer if no mapping matches
- **Password** is set to an unusable placeholder. SSO users cannot log in with a password
- **Seat limits** from your license apply. If admin seats are full, the user is downgraded to Viewer. If all seats are full, login is denied with a clear error message.

On subsequent logins, the existing account is reused. The user's **email** and **role** are synced from the identity provider on every login. If a user is added to your admin group, they will be promoted to Admin on their next login. If removed, they will be demoted to their default role. Seat limits are respected: if admin seats are full, the promotion is deferred until a seat opens up.

## Role mapping

### LDAP group mapping

Set the **Admin Group DN** to a group in your directory. Members of that group get the Admin role; everyone else gets the default role (Viewer).

Example: If your admin group is `cn=sencho-admins,ou=groups,dc=example,dc=com`, set that as the Admin Group DN. Users who are a `member` of that group will be provisioned as Admin.

### OIDC claim mapping

For OIDC providers, configure two fields:

| Field | Description | Example |
|-------|-------------|---------|
| **Admin Claim** | The JWT claim name that contains role information | `groups` |
| **Admin Claim Value** | The value within that claim that grants Admin | `sencho-admins` |

If the user's ID token contains a `groups` claim with the value `sencho-admins`, they get Admin. Otherwise, they get the default role.

<Note>
  Not all providers include a `groups` claim by default. You may need to configure custom claims in your identity provider's admin console.
</Note>

## Configuration

SSO can be configured two ways:

1. **Settings UI** - Go to **Settings > SSO** in the Sencho dashboard. Enable providers, enter credentials, and test connections from the UI. Changes take effect immediately without restarting.
2. **Environment variables** - Set `SSO_*` variables in your Docker Compose file. These seed the database on first boot. After that, the database configuration is authoritative.

### Via Settings UI

Admins can manage SSO providers in **Settings > SSO**. Each provider is displayed as a collapsible card with:

- An **enable/disable** toggle and an **Active** badge when enabled
- Provider-specific configuration fields (expand the card to configure)
- A **Save** button to persist changes
- A **Test Connection** button to verify connectivity before saving
- A **Remove** button to delete an existing provider configuration

<Frame>
  <img src="/images/sso/sso-settings.png" alt="SSO settings panel showing all five identity providers" />
</Frame>

Expand a provider card to configure it. The LDAP configuration form includes:

| Field | Description |
|-------|-------------|
| **Server URL** | LDAP server URL (e.g., `ldap://ldap.example.com:389` or `ldaps://...` for TLS) |
| **Bind DN** | Service account DN used to search the directory |
| **Bind Password** | Service account password |
| **Search Base** | Base DN for user searches (e.g., `ou=users,dc=example,dc=com`) |
| **Search Filter** | LDAP filter template using `{{username}}` as placeholder |
| **Admin Group DN** | DN of the group whose members receive the Admin role |
| **Default Role** | Role assigned to users not in the admin group (Viewer or Admin) |
| **Verify TLS certificate** | Toggle to enable or disable TLS certificate verification |

<Frame>
  <img src="/images/sso/sso-settings-ldap.png" alt="LDAP configuration form with server URL, bind DN, search base, and role mapping" />
</Frame>

OIDC providers (Google, GitHub, Okta) share a common configuration form:

| Field | Description |
|-------|-------------|
| **Issuer URL** | (Okta and Custom OIDC) Your provider's OIDC issuer URL |
| **Client ID** | OAuth client ID from your identity provider |
| **Client Secret** | OAuth client secret |
| **Admin Claim** | JWT claim name inspected for role mapping (e.g., `groups`) |
| **Admin Claim Value** | Value within the claim that grants Admin (e.g., `sencho-admins`) |
| **Scopes** | Space-separated OAuth scopes (default: `openid email profile`). Customize if your provider requires additional scopes for group claims. |
| **Default Role** | Role assigned when no claim mapping matches (Viewer or Admin) |

<Frame>
  <img src="/images/sso/sso-settings-oidc.png" alt="Google OIDC configuration form with client ID, client secret, and role claim mapping" />
</Frame>

### Custom OIDC configuration

The **Custom OIDC** provider has additional fields beyond the standard OIDC configuration:

| Field | Description |
|-------|-------------|
| **Display Name** | Label shown on the login button (e.g., "Corporate SSO") |
| **Issuer URL** | Base URL of the OIDC discovery endpoint (without `/.well-known/openid-configuration`) |
| **User ID Claim** | Claim name for the unique user identifier (default: `sub`) |
| **Username Claim** | Claim name for the display name (default: `preferred_username`) |
| **Email Claim** | Claim name for the email address (default: `email`) |

The claim mapping fields let you tell Sencho which token claims correspond to user identity fields. Most spec-compliant providers use the standard claim names, so you can leave these blank unless your provider uses non-standard names.

<Frame>
  <img src="/images/sso/sso-settings-custom-oidc.png" alt="Custom OIDC configuration form with discovery URL, claim mapping, and role settings" />
</Frame>

### Via environment variables

Environment variables are useful for initial deployment or infrastructure-as-code workflows. They seed the SSO configuration on first startup. After that, changes made in the Settings UI take precedence.

## SSO environment variables reference

### LDAP

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_LDAP_ENABLED` | `false` | Enable LDAP authentication |
| `SSO_LDAP_DISPLAY_NAME` | `LDAP` | Label shown on the login button (e.g., "Corporate AD") |
| `SSO_LDAP_URL` | - | LDAP server URL (e.g., `ldap://ldap.example.com:389` or `ldaps://ldap.example.com:636`) |
| `SSO_LDAP_BIND_DN` | - | Service account DN for searching users |
| `SSO_LDAP_BIND_PASSWORD` | - | Service account password (encrypted at rest in the database) |
| `SSO_LDAP_SEARCH_BASE` | - | Base DN for user searches (e.g., `ou=users,dc=example,dc=com`) |
| `SSO_LDAP_SEARCH_FILTER` | `(uid={{username}})` | LDAP filter template. Use `(sAMAccountName={{username}})` for Active Directory |
| `SSO_LDAP_ADMIN_GROUP_DN` | - | DN of the group whose members receive the Admin role |
| `SSO_LDAP_DEFAULT_ROLE` | `viewer` | Role assigned to LDAP users not in the admin group |
| `SSO_LDAP_TLS_REJECT_UNAUTHORIZED` | `true` | Whether to verify the LDAP server's TLS certificate |

### Google OIDC

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_OIDC_GOOGLE_ENABLED` | `false` | Enable Google SSO |
| `SSO_OIDC_GOOGLE_CLIENT_ID` | - | OAuth client ID from Google Cloud Console |
| `SSO_OIDC_GOOGLE_CLIENT_SECRET` | - | OAuth client secret (encrypted at rest) |

### GitHub OAuth

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_OIDC_GITHUB_ENABLED` | `false` | Enable GitHub SSO |
| `SSO_OIDC_GITHUB_CLIENT_ID` | - | OAuth app client ID from GitHub Developer Settings |
| `SSO_OIDC_GITHUB_CLIENT_SECRET` | - | OAuth app client secret (encrypted at rest) |

### Okta OIDC

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_OIDC_OKTA_ENABLED` | `false` | Enable Okta SSO |
| `SSO_OIDC_OKTA_ISSUER_URL` | - | Okta issuer URL (e.g., `https://dev-123456.okta.com`) |
| `SSO_OIDC_OKTA_CLIENT_ID` | - | Okta application client ID |
| `SSO_OIDC_OKTA_CLIENT_SECRET` | - | Okta client secret (encrypted at rest) |

### Custom OIDC

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_OIDC_CUSTOM_ENABLED` | `false` | Enable the custom OIDC provider |
| `SSO_OIDC_CUSTOM_DISPLAY_NAME` | `Custom OIDC` | Label shown on the login button |
| `SSO_OIDC_CUSTOM_ISSUER_URL` | - | OIDC issuer URL (the base of the discovery endpoint) |
| `SSO_OIDC_CUSTOM_CLIENT_ID` | - | OAuth client ID from your identity provider |
| `SSO_OIDC_CUSTOM_CLIENT_SECRET` | - | OAuth client secret (encrypted at rest) |
| `SSO_OIDC_CUSTOM_SCOPES` | `openid email profile` | Space-separated OAuth scopes |
| `SSO_OIDC_CUSTOM_ID_CLAIM` | `sub` | Token claim for the unique user identifier |
| `SSO_OIDC_CUSTOM_USERNAME_CLAIM` | `preferred_username` | Token claim for the display name |
| `SSO_OIDC_CUSTOM_EMAIL_CLAIM` | `email` | Token claim for the email address |

### General

| Variable | Default | Description |
|----------|---------|-------------|
| `SSO_OIDC_ADMIN_CLAIM` | `groups` | JWT claim name inspected for Admin role mapping |
| `SSO_OIDC_ADMIN_CLAIM_VALUE` | `sencho-admins` | Value in the admin claim that maps to the Admin role |
| `SSO_DEFAULT_ROLE` | `viewer` | Default role for all SSO users when no mapping matches |
| `SSO_CALLBACK_URL` | auto-detect | External base URL for OAuth callback URLs (see below) |

## Reverse proxy and callback URLs

<Warning>
  If Sencho is behind a reverse proxy (nginx, Traefik, Caddy), you **must** set `SSO_CALLBACK_URL` to your external URL. Otherwise, OAuth callbacks will fail.
</Warning>

Set `SSO_CALLBACK_URL` to the URL users access Sencho from, for example, `https://sencho.example.com`. Sencho uses this to construct the OAuth redirect URI that your identity provider calls back to.

If not set, Sencho auto-detects the URL from the request's `Host` header and protocol, which works for direct access but fails behind proxies that rewrite the host.

## Provider-specific setup examples

### Keycloak

1. Create a new client in your Keycloak realm (Client type: **OpenID Connect**)
2. Set **Valid redirect URIs** to `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback`
3. Enable **Client authentication** (confidential access type) and copy the client secret from the Credentials tab
4. The Issuer URL is your realm URL: `https://keycloak.example.com/realms/myrealm`
5. Keycloak uses standard claim names by default, so you can leave claim mapping blank

### Authentik

1. Create a new OAuth2/OpenID Provider in Authentik
2. Set the redirect URI to `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback`
3. Copy the Client ID and Client Secret
4. The Issuer URL is `https://authentik.example.com/application/o/<slug>/`
5. Default claims work. For group-based admin mapping, configure a `groups` scope in Authentik

### Authelia

1. Add an OpenID Connect client to your Authelia configuration
2. Set `redirect_uris` to include `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback`
3. The Issuer URL is your Authelia domain: `https://auth.example.com`
4. Authelia uses standard OIDC claims

### Zitadel

1. Create a new Web application in your Zitadel project
2. Add `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback` as a redirect URI
3. The Issuer URL is your Zitadel instance URL: `https://zitadel.example.com`
4. Copy the Client ID and Client Secret from the application settings

### KanIDM

1. Create a new OAuth2 client in KanIDM
2. Set the redirect URI and copy the client credentials
3. The Issuer URL is your KanIDM domain: `https://kanidm.example.com/oauth2/openid/<client_id>`
4. KanIDM may use `name` instead of `preferred_username` for the username claim. Set **Username Claim** to `name` if usernames are not being mapped correctly.

### Pocket ID

1. Create a new OIDC client in Pocket ID
2. Set the callback URL to `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback`
3. The Issuer URL is your Pocket ID instance URL
4. Copy the Client ID and Secret from the client configuration

## Security

- **PKCE** - All OIDC flows use `code_challenge_method=S256` to prevent authorization code interception
- **State parameter** - A cryptographic random value protects against CSRF attacks on the OAuth callback
- **Encrypted secrets** - LDAP bind passwords and OIDC client secrets are encrypted at rest
- **No local password** - SSO users are created with an unusable password hash. They cannot bypass SSO by using the password login form
- **Admin-only configuration** - Only administrators can enable or configure SSO providers

## Troubleshooting

### Discovery URL errors

If the **Test Connection** button returns an error like "Discovery failed" or a network timeout:

- Verify the Issuer URL is reachable from the Sencho container (not just your browser)
- Confirm the URL does not include `/.well-known/openid-configuration`, just the base issuer URL
- For providers behind a corporate firewall, ensure the Sencho container's DNS can resolve the hostname
- Check that HTTPS certificates are valid. Self-signed certificates may require additional container configuration

### Issuer mismatch

If login fails with an issuer validation error, the `issuer` value in the provider's discovery document does not match what Sencho expects. This commonly happens when:

- The Issuer URL has a trailing slash mismatch (e.g., `https://auth.example.com` vs `https://auth.example.com/`)
- The provider is accessed via a different hostname than it advertises in its discovery document

Fix: set the Issuer URL to exactly match the `issuer` field returned by your provider's `/.well-known/openid-configuration` endpoint.

### Claim mapping not working

If users are created with incorrect usernames or missing emails:

- Enable **Developer Mode** (Settings > Developer Mode toggle) to see the raw claims Sencho receives from the provider in the server logs
- Check your provider's documentation for which claims it includes in the ID token and userinfo response
- Verify that the scopes you configured include the necessary permissions (some providers require explicit `profile` or `email` scopes)
- Set the appropriate claim names in the Custom OIDC claim mapping fields

### Redirect URI mismatch

If the provider returns an "invalid redirect URI" error during login:

- The callback URL configured in your identity provider must exactly match: `https://sencho.example.com/api/auth/sso/oidc/oidc_custom/callback`
- If Sencho is behind a reverse proxy, set `SSO_CALLBACK_URL` to your external URL
- Some providers are strict about trailing slashes and HTTP vs HTTPS

### SSO buttons not appearing on login page

- Verify the provider is **enabled** (toggle on) in Settings > SSO
- Check that the provider configuration was saved successfully
- The login page fetches enabled providers on load. Hard refresh the page if changes were just made.

For common SSO issues (LDAP connection errors, OAuth callback mismatches), see the [Troubleshooting](/operations/troubleshooting#ldap-connection-refused) page.

## Combining SSO with two-factor authentication

SSO and [two-factor authentication](/features/two-factor-authentication) can coexist. By default, users who have 2FA enrolled skip the TOTP challenge when they sign in through SSO, since the identity provider has already authenticated them. Users who want stricter sign-in can opt in to requiring 2FA on SSO from their Account & Security screen.