diff --git a/docs/features/sso.mdx b/docs/features/sso.mdx index 4f50c152..6fc0e782 100644 --- a/docs/features/sso.mdx +++ b/docs/features/sso.mdx @@ -3,20 +3,20 @@ 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. +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 preset providers 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 | +| **Google** | OpenID Connect | Skipper | Preset for Google Workspace or personal Google accounts, with branded login button | +| **GitHub** | OAuth 2.0 | Skipper | Preset for GitHub personal accounts and GitHub orgs, with branded login button | +| **Okta** | OpenID Connect | Skipper | Preset for any Okta org or Okta-compatible IdP, with branded login button | | **LDAP / Active Directory** | LDAP bind + search | Admiral | Works with OpenLDAP, Active Directory, FreeIPA, and any LDAPv3 server | - **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. + **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 ship with provider-aware defaults (issuer URL, claim mapping) and a branded login button; the underlying protocol is the same. You still create the OAuth app in the provider's console and paste the Client ID and Secret either way. ## How it works diff --git a/docs/getting-started/sso-quickstart.mdx b/docs/getting-started/sso-quickstart.mdx index 3eb4d2d3..b7ced487 100644 --- a/docs/getting-started/sso-quickstart.mdx +++ b/docs/getting-started/sso-quickstart.mdx @@ -3,12 +3,25 @@ title: SSO Setup Guide description: Step-by-step instructions for connecting Sencho to your identity provider. --- -SSO can be configured via environment variables (shown below) or from the Settings UI after first boot. +SSO can be configured from the Settings UI or seeded via environment variables (shown below). - **Tier availability.** Custom OIDC is available on every tier, including Community. The Google, GitHub, and Okta one-click presets require Skipper or higher. LDAP / Active Directory requires Admiral. See [Licensing & Billing](/features/licensing#feature-breakdown) for the full breakdown. + **Tier availability.** Custom OIDC is available on every tier, including Community. The Google, GitHub, and Okta preset providers require Skipper or higher. LDAP / Active Directory requires Admiral. See [Licensing & Billing](/features/licensing#feature-breakdown) for the full breakdown. + + Settings > SSO panel showing all five provider cards with PROVIDERS and ENABLED stats in the masthead + + +## How to configure + +You can wire SSO two ways. Both reach the same database row, and you can mix and match. + +- **Environment variables** seed the SSO configuration the first time Sencho boots with that variable set. They are useful for infrastructure-as-code, fresh deployments, and disaster recovery. After a configuration row exists in the database, the database is authoritative; subsequent restarts do not re-read the env vars or overwrite changes you made in the UI. +- **Settings > SSO** in the dashboard lets admins enable, edit, save, and remove providers without restarting. Changes apply immediately. Each provider card has a **Test Connection** button that validates connectivity before you commit (LDAP bind plus search for LDAP, OIDC discovery plus token endpoint reachability for OIDC). + +If you want a guided UI walkthrough rather than the env-var path below, jump to the [SSO feature page](/features/sso#configuration). + ## Google OIDC 1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) @@ -33,7 +46,7 @@ services: - /opt/compose:/opt/compose ``` -Restart Sencho. A "Google" button will appear on the login page. +A **Google** button appears on the login page after the first boot with these variables set. To override the button label, set `SSO_OIDC_GOOGLE_DISPLAY_NAME` (and the equivalent `_DISPLAY_NAME` variable for any other provider). ## GitHub OAuth @@ -128,12 +141,20 @@ If your provider uses non-standard claim names, add claim mapping: - SSO_LDAP_DEFAULT_ROLE=viewer ``` -After starting Sencho, verify the connection in **Settings > SSO** using the **Test Connection** button. +Once Sencho is running, open **Settings > SSO**, expand the LDAP card, and click **Test Connection**. Sencho binds with the service account, runs the search filter, and reports the result inline. + + + LDAP provider card expanded showing the configuration form with example values, the Verify TLS certificate toggle, and Save and Test Connection buttons + If your LDAP server is on the Docker host (not in a container), use the host's LAN IP or `host.docker.internal` (Docker Desktop) instead of `localhost`. + + For self-signed LDAPS certificates, set `SSO_LDAP_TLS_REJECT_UNAUTHORIZED=false` (or untick **Verify TLS certificate** in the UI). Use only when you control the certificate authority. + + ## Role mapping By default, all SSO users are assigned the **Viewer** role. To grant Admin to specific users: @@ -188,6 +209,7 @@ services: - SSO_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com - SSO_LDAP_SEARCH_FILTER=(sAMAccountName={{username}}) - SSO_LDAP_ADMIN_GROUP_DN=cn=sencho-admins,ou=groups,dc=example,dc=com + # - SSO_LDAP_TLS_REJECT_UNAUTHORIZED=false # uncomment for self-signed LDAPS # Role mapping & callback - SSO_OIDC_ADMIN_CLAIM=groups - SSO_OIDC_ADMIN_CLAIM_VALUE=sencho-admins diff --git a/docs/images/sso/sso-quickstart-ldap-test.png b/docs/images/sso/sso-quickstart-ldap-test.png new file mode 100644 index 00000000..1863ad84 Binary files /dev/null and b/docs/images/sso/sso-quickstart-ldap-test.png differ diff --git a/docs/images/sso/sso-quickstart-overview.png b/docs/images/sso/sso-quickstart-overview.png new file mode 100644 index 00000000..e9c13200 Binary files /dev/null and b/docs/images/sso/sso-quickstart-overview.png differ