Configure Single Sign-On
Configure OIDC, OAuth2, SAML 2.0, or CAS login connections
SSO connections are managed by a super administrator in Site settings > SSO. The fields for each connection depend on the protocol; prepare the identity provider's callback address, client credentials, and certificates/metadata before saving.
Callback Address
The callback address format is {API_BASE_URL}/api/v1/sso/callback/{provider_name}. The provider_name must match the name set in Clouisle; a mismatched callback address is the most common cause of SSO login failure.
Protocol Fields
OAuth2 / OIDC
| Field | Required | Description |
|---|---|---|
client_id | Yes | Client ID from the provider |
client_secret | Yes | Client Secret from the provider |
authorization_url | Yes | Provider authorization endpoint |
token_url | Yes | Token exchange endpoint |
userinfo_url | Yes | User info endpoint |
scopes | No | Space-separated scopes (default openid email profile) |
Common provider endpoints: GitHub uses https://github.com/login/oauth/authorize / …/login/oauth/access_token / https://api.github.com/user; Google uses https://accounts.google.com/o/oauth2/v2/auth / https://oauth2.googleapis.com/token / https://openidconnect.googleapis.com/v1/userinfo.
SAML 2.0
| Field | Required | Description |
|---|---|---|
sp_entity_id | Yes | Service Provider Entity ID (your Clouisle instance identifier) |
idp_entity_id | Yes | Identity Provider Entity ID |
sso_url | Yes | IdP Single Sign-On URL |
x509_cert | Yes | IdP X.509 certificate (PEM, without header/footer) |
acs_url | Yes | Assertion Consumer Service URL ({API_BASE_URL}/api/v1/sso/callback/{provider_name}) |
slo_url | No | SP Single Logout URL |
idp_slo_url | No | IdP Single Logout URL |
name_id_format | No | NameID format (default urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) |
CAS
| Field | Required | Description |
|---|---|---|
server_url | Yes | CAS server base URL |
service_url | Yes | Service URL for CAS validation |
version | No | CAS protocol version 1/2/3 (default 3) |
Attribute Mapping
Attribute mapping maps provider user fields to Clouisle user fields: email, username, avatar_url. Use dot paths for simple nested objects:
{
"email": "email",
"username": "profile.name",
"avatar_url": "profile.picture"
}For complex structures (arrays, filters), use JSONPath expressions starting with $; when multiple values match, the first is used.
Admin Permissions and API
Listing providers requires admin:sso:read; creating, updating, deleting, testing providers, and disconnecting user SSO connections require admin:sso:update (the Admin role only has admin:sso:read by default; admin:sso:update is limited to Super Admin). The public endpoint GET /api/v1/sso/providers returns the enabled providers (for rendering login buttons).
GET /api/v1/sso/admin/providers
POST /api/v1/sso/admin/providers
PUT /api/v1/sso/admin/providers/{provider_id}
DELETE /api/v1/sso/admin/providers/{provider_id}
POST /api/v1/sso/admin/providers/{provider_id}/testGeneral Flow
- Enable SSO.
- Select the protocol and fill in the provider name, display name, and button text.
- Configure the client ID, client secret, Issuer/authorization endpoint, Token endpoint, user info mapping, or SAML metadata.
- Set the auto-creation, email matching, and approval policies.
- After saving, copy the callback address shown by Clouisle to the identity provider.
- In an incognito window, test new users, existing users, and failed callbacks.
User Lifecycle
- When Auto-create is on, the first SSO login can create a user.
- When Match by email is on, the SSO email can link to an existing account.
- When Approval required is on, new accounts remain pending approval.
- When Allow password login is off, the site enters SSO-only mode.
Common Errors
SSO_INVALID_CONFIGURATION (6304) means the configuration is missing or malformed; SSO_AUTHENTICATION_FAILED (6303) means the identity provider rejected the request or callback validation failed; expired sessions return 6301. Start by checking the Issuer, callback URL, clock, certificates, and email mapping.
How is this guide?