Configure Single Sign-On

SSO is managed by a Super Admin under Site settings → SSO: turn on the global switch first, then add providers one by one. Each provider's protocol configuration is a JSON document whose fields depend on the protocol; prepare the identity provider's callback address, client credentials, and certificate before saving.

Callback Address

The callback address you register with the identity provider is:

{BACKEND_ORIGIN}/api/v1/sso/callback/{provider_name}

BACKEND_ORIGIN is the public origin of the request itself — the domain the browser actually reached the backend through (with a reverse proxy, the forwarded external address). A :3000 port here is automatically rewritten to :8000. It is not API_BASE_URL (an internal service address) and is unaffected by FRONTEND_URL; getting it wrong causes a 404 callback or a redirect to the wrong domain.

{provider_name} must exactly match the provider name registered in Clouisle (case-sensitive). A mismatched callback address is the most common cause of SSO login failure.

Adding a Provider

In Site settings → SSO, click Add Provider. The dialog has three tabs — Basic Info / Configuration / Attribute Mapping:

Protocol Configuration

The Configuration tab is a free-form JSON editor pre-filled with a template when you pick a protocol. Field names must match the tables below; a typo is not rejected on save and only surfaces as a configuration error during login.

OAuth2 / OIDC

Login uses the authorization-code flow with PKCE (S256) and generates a nonce. Common provider endpoints:

{
  "client_id": "your-github-client-id",
  "client_secret": "your-github-client-secret",
  "authorization_url": "https://github.com/login/oauth/authorize",
  "token_url": "https://github.com/login/oauth/access_token",
  "userinfo_url": "https://api.github.com/user",
  "scopes": "read:user user:email"
}

SAML 2.0

{
  "sp_entity_id": "clouisle",
  "idp_entity_id": "https://idp.example.com/metadata",
  "sso_url": "https://idp.example.com/sso",
  "x509_cert": "MIIC...truncated...",
  "acs_url": "https://your-domain.com/api/v1/sso/callback/azure-ad"
}

strict mode is enabled, so SAML responses must pass signature validation; a large clock skew between the IdP and Clouisle fails immediately.

CAS

The CAS user identifier comes from <cas:user> in the validation response; version 3 also reads attributes from <cas:attributes> for attribute mapping.

Attribute Mapping

The Attribute Mapping tab is another JSON document that maps provider response data onto the fields Clouisle needs:

Two path styles:

• Dot path (default): {"email": "email", "username": "profile.name"} reads nested objects.
• JSONPath: starting with $, suited to arrays or filtering, e.g. {"email": "$.emails[0].value"}; the first match wins.

The default mapping when adding a provider:

{
  "email": "email",
  "username": "name",
  "avatar_url": "picture"
}

GitHub's payload differs from the OIDC standard claims, so change it to {"email": "email", "username": "login", "avatar_url": "avatar_url"}.

Testing the Connection

Test Connection in the list calls POST /api/v1/admin/sso/providers/{id}/test:

• Server-side it only builds an authorization URL locally (with a placeholder callback) to check that the required keys are present, then returns the first 100 characters of that URL.
• It never contacts the identity provider, so a wrong client secret, a mismatched callback address, or an expired certificate are all invisible to it — verify with a real login.
• A status: error response only means a key is missing or a value cannot be used to build an authorization URL.

Admin Permissions and API

General Flow

1. Enable SSO in site settings and adjust the global policies (allow password login, auto-create, require approval, match by email).
2. Add a provider: fill in the basic info and pick a protocol.
3. Enter the protocol JSON on the Configuration tab.
4. Map email, username, and avatar to provider fields on the Attribute Mapping tab.
5. After saving, add the callback address Clouisle shows to the identity provider's allowlist/redirect URIs.
6. Verify three cases in an incognito window: a new user, an existing user, and a failing callback.

User Lifecycle

Global settings and provider switches combine with OR semantics:

Newly created SSO users behave as follows:

• They have no local password (hashed_password is an empty string), so password login is impossible.
• Their email is marked verified immediately (the provider's email is trusted).
• The username comes from the mapped username; if missing, the local part of the email; if that is missing too, user_<first 8 chars of the provider user id>; duplicates get a numeric suffix.
• The role comes from the provider's default_role_id (API-only; there is no field for it in the UI), falling back to the global default role; the user is then added to the default team via default_team_id.

Common Errors

On a failed callback the backend redirects to /sso-callback?error=..., where error may be sso_provider_not_found, sso_session_expired, or sso_login_failed; a deactivated or pending-approval account yields inactive or pending_approval.

Troubleshooting

No SSO Buttons on the Login Page

1. Check that sso_enabled is true.
2. Check that the provider itself is enabled.
3. Request GET /api/v1/sso/providers directly — an empty response means the frontend renders no buttons.

Callback Errors / Stuck on the Same Page

1. Verify the callback domain and provider name match the configuration exactly.
2. Confirm the public address (from the request/reverse proxy) is reachable by the identity provider.
3. Check whether the authorization code expired (a long pause gives 6301).
4. Look at sso_login_failed entries and messages in the audit log.

Login Succeeds but Fields Are Mismapped

1. Check the path style per Attribute Mapping (dot path vs $ JSONPath).
2. Remember that a same-named raw field overrides the mapped value.
3. Non-standard providers such as GitHub need explicit mapping (login, avatar_url).

SAML Validation Fails

1. The certificate must be PEM content with the header/footer lines removed.
2. Confirm the IdP and server clocks are in sync (excessive skew invalidates the response).
3. Confirm idp_entity_id exactly matches the Entity ID in the IdP metadata.

Nobody Can Reach the Admin Console After Disabling Password Login

This is the classic SSO-only accident: confirm at least one Super Admin has an SSO connection bound before switching. If you are already locked out, set sso_allow_password_login back to true server-side and restart.

Related Documentation

• SSO API — endpoints, request bodies, and response fields
• Login & Account Security — login protection and first-time SSO login behavior
• Profile Settings — disconnecting links and anti-lockout protection
• Site Settings reference — defaults for the sso_* keys
• Environment Variables — how FRONTEND_URL, PUBLIC_API_URL, and API_V1_STR differ