Single Sign-On (SSO)

Configure and use SAML 2.0 and OpenID Connect SSO for enterprise authentication.

KaireonAI supports both SAML 2.0 and OpenID Connect (OIDC) for enterprise single sign-on. SSO configuration is per-tenant.

GET /api/v1/sso

Get the SSO configuration for the tenant. Sensitive fields (client secrets, SAML certificates) are redacted. Admin only.

Response — Not Configured

{ "configured": false, "provider": "none" }

Response — Configured

{
  "configured": true,
  "provider": "oidc",
  "enabled": true,
  "samlEntityId": null,
  "samlSsoUrl": null,
  "samlAcsUrl": null,
  "oidcIssuer": "https://accounts.google.com",
  "oidcClientId": "1234567890.apps.googleusercontent.com",
  "oidcScopes": "openid email profile",
  "defaultRole": "viewer",
  "allowedDomains": ["example.com"],
  "autoProvision": true,
  "enforceForAllUsers": false
}

---

POST /api/v1/sso

Configure SSO or generate an auth URL. Admin only.

Actions

configure — Save SSO configuration

{
  "action": "configure",
  "config": {
    "provider": "oidc",
    "enabled": true,
    "oidcIssuer": "https://accounts.google.com",
    "oidcClientId": "1234567890.apps.googleusercontent.com",
    "oidcClientSecret": "GOCSPX-...",
    "oidcScopes": "openid email profile",
    "defaultRole": "viewer",
    "allowedDomains": ["example.com"],
    "autoProvision": true,
    "enforceForAllUsers": false
  }
}

Response:

{ "success": true, "message": "SSO configuration updated" }

get_auth_url — Generate an OIDC authorization URL

{
  "action": "get_auth_url",
  "state": "random-state-value",
  "redirectUri": "https://app.example.com/callback"
}

Response:

{ "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=..." }

---

GET /api/v1/sso/callback

OIDC authorization code callback. This endpoint is called by the identity provider after the user authenticates. It exchanges the authorization code for tokens, verifies the ID token signature via JWKS, and provisions or logs in the user.

Query Parameters

Parameter	Type	Required	Description
code	string	Yes	Authorization code from the IdP
state	string	Yes	State parameter containing tenantId:nonce. The tenant is extracted exclusively from this parameter for security.

The state parameter is mandatory. The tenant ID is extracted only from the state parameter (format: tenantId:nonce). There is no fallback to a tenant query parameter — this prevents session fixation attacks where an attacker could redirect a user through SSO with a manipulated tenant ID.

The OIDC client_id must be configured in the SSO settings. If oidcClientId is missing, the callback will return 400 Bad Request because the token audience cannot be verified, which would allow cross-client token reuse.

Response

{
  "userId": "clx...",
  "email": "[e-mail]",
  "name": "John Smith",
  "created": false,
  "provider": "oidc"
}

---

POST /api/v1/sso/callback

SAML POST binding (Assertion Consumer Service). Receives the SAML response from the identity provider, validates the assertion, and provisions or logs in the user.

Request Body (form-encoded or JSON)

The two standard SAML POST-binding fields are required by the OASIS SAML 2.0 HTTP POST Binding spec (section 3.5.4). Your IdP will POST these form fields to the ACS endpoint:

POST /api/v1/sso/callback HTTP/1.1
Content-Type: application/x-www-form-urlencoded

SAMLResponse=<base64-encoded-assertion>&RelayState=<tenant-id>

Or as a curl example:

curl -X POST https://your-domain.kaireonai.com/api/v1/sso/callback \
  -d "SAMLResponse=$BASE64_ASSERTION" \
  -d "RelayState=$TENANT_ID"

Both fields are mandated by the OASIS SAML 2.0 HTTP POST Binding spec (§3.5.4):

• SAMLResponse — the base64-encoded SAML assertion produced by your IdP.
• RelayState — the tenant ID. Extracted exclusively from this field; there is no fallback to query parameters (prevents session-fixation attacks).

Response

{
  "userId": "clx...",
  "email": "[e-mail]",
  "name": "John Smith",
  "created": true,
  "provider": "saml"
}

Security

• OIDC ID tokens are verified using JWKS public key discovery
• Issuer, audience, and expiration are validated
• SAML assertions are signature-verified against the configured certificate
• SSO callbacks are rate limited to 30 requests/min