> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO)

> Configure and use OpenID Connect (OIDC) SSO for enterprise authentication. SAML 2.0 support is on the roadmap; the schema below documents the planned shape so existing integrations stay forward-compatible.

KaireonAI ships OpenID Connect (OIDC) for enterprise single sign-on. SAML 2.0 is on the roadmap — the schema fields below are documented for forward compatibility, and the `samlEntityId`/`samlSsoUrl`/`samlAcsUrl` fields will not yet activate a SAML flow. 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

```json theme={null}
{ "configured": false, "provider": "none" }
```

### Response — Configured

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

```json theme={null}
{ "success": true, "message": "SSO configuration updated" }
```

#### `get_auth_url` — Generate an OIDC authorization URL

```json theme={null}
{
  "action": "get_auth_url",
  "state": "random-state-value",
  "redirectUri": "https://app.example.com/callback"
}
```

**Response:**

```json theme={null}
{ "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. |

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

### Response

```json theme={null}
{
  "userId": "clx...",
  "email": "john@example.com",
  "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:

```http theme={null}
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:

```bash theme={null}
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

```json theme={null}
{
  "userId": "clx...",
  "email": "john@example.com",
  "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