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

# SSO

> Wire enterprise SSO with SAML 2.0 and OIDC providers such as Okta and Azure AD. Includes JIT user provisioning and connection routing by email domain.

## Setup

Configure your identity providers when creating the KavachOS instance:

<Tabs>
  <Tab title="SAML 2.0">
    ```ts theme={"system"}
    import { createKavach } from 'kavachos';

    const kavach = await createKavach({
      database: { provider: 'sqlite', url: 'kavach.db' },
      sso: { // [!code highlight]
        saml: [ // [!code highlight]
          {
            id: 'okta', // [!code highlight]
            name: 'Okta', // [!code highlight]
            entryPoint: 'https://your-org.okta.com/app/appId/sso/saml', // [!code highlight]
            issuer: 'https://your-app.com', // [!code highlight]
            cert: process.env.OKTA_SAML_CERT, // [!code highlight]
            callbackUrl: 'https://your-app.com/api/kavach/auth/sso/saml/conn_id/acs', // [!code highlight]
          },
        ],
      }, // [!code highlight]
    });
    ```
  </Tab>

  <Tab title="OIDC">
    ```ts theme={"system"}
    import { createKavach } from 'kavachos';

    const kavach = await createKavach({
      database: { provider: 'sqlite', url: 'kavach.db' },
      sso: { // [!code highlight]
        oidc: [ // [!code highlight]
          {
            id: 'azure', // [!code highlight]
            name: 'Azure AD', // [!code highlight]
            issuer: 'https://login.microsoftonline.com/your-tenant-id/v2.0', // [!code highlight]
            clientId: process.env.AZURE_CLIENT_ID, // [!code highlight]
            clientSecret: process.env.AZURE_CLIENT_SECRET, // [!code highlight]
            callbackUrl: 'https://your-app.com/api/kavach/auth/sso/oidc/conn_id/callback', // [!code highlight]
            scopes: ['openid', 'profile', 'email'], // [!code highlight]
          },
        ],
      }, // [!code highlight]
    });
    ```
  </Tab>
</Tabs>

## SSO connections

Connections link an org to an identity provider and route by email domain.

```ts theme={"system"}
// Create a connection for an org
const connection = await kavach.sso.createConnection({ // [!code highlight]
  orgId: 'org_acme',
  providerId: 'okta',    // matches the id in your sso config // [!code highlight]
  type: 'saml',          // 'saml' | 'oidc' // [!code highlight]
  domain: 'acme.com',    // emails at this domain are routed here // [!code highlight]
});

// Look up a connection by domain (e.g., to redirect on login)
const conn = await kavach.sso.getConnectionByDomain('alice@acme.com'.split('@')[1]);

// List all connections for an org
const conns = await kavach.sso.listConnections('org_acme');

// Remove a connection
await kavach.sso.removeConnection(connection.id);
```

## JIT provisioning

When a user authenticates through SSO for the first time, KavachOS provisions their account automatically using the identity attributes from the IdP (email and display name from SAML `NameID` / OIDC `email` claim). No pre-registration is needed.

User IDs are derived deterministically from the provider and subject, so the same IdP user always maps to the same KavachOS identity.

## SAML flow

```ts theme={"system"}
// 1. Redirect the user to the IdP
const authUrl = await kavach.sso.getSamlAuthUrl(connection.id, '/dashboard');
// redirect to authUrl

// 2. Handle the ACS callback (POST from IdP)
const { user, orgId } = await kavach.sso.handleSamlResponse(
  connection.id,
  samlResponseFromFormData,
);
// user.id, user.email, user.name
```

<Note>
  SAML responses are verified against the IdP certificate. Unsigned responses are rejected.
</Note>

## OIDC flow

```ts theme={"system"}
// 1. Redirect the user to the IdP
const authUrl = await kavach.sso.getOidcAuthUrl(connection.id, stateParam);
// redirect to authUrl

// 2. Handle the callback
const { user, orgId } = await kavach.sso.handleOidcCallback(connection.id, codeFromQuery);
// user.id, user.email, user.name
```

OIDC discovery is fetched automatically from `issuer/.well-known/openid-configuration`. The `id_token` is verified using the IdP's JWKS endpoint.

## Endpoints

| Method | Path                                    | Description                    |
| ------ | --------------------------------------- | ------------------------------ |
| POST   | `/auth/sso/connections`                 | Create SSO connection          |
| GET    | `/auth/sso/connections/:orgId`          | List connections for org       |
| DELETE | `/auth/sso/connections/:id`             | Remove connection              |
| GET    | `/auth/sso/saml/:connectionId`          | Initiate SAML login (redirect) |
| POST   | `/auth/sso/saml/:connectionId/acs`      | SAML assertion consumer        |
| GET    | `/auth/sso/oidc/:connectionId`          | Initiate OIDC login (redirect) |
| GET    | `/auth/sso/oidc/:connectionId/callback` | OIDC callback                  |