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

# SSO & SCIM

> Configure enterprise single sign-on and automated user provisioning for Toktra.

Toktra supports enterprise SSO via SAML 2.0 and automated user provisioning via SCIM 2.0. This guide walks through configuring your identity provider, testing the connection, and understanding what gets synced.

## Supported identity providers

<Tabs>
  <Tab title="Okta">
    Use the **SAML 2.0** app integration in the Okta Admin Console. Okta also supports SCIM provisioning via the Toktra SCIM endpoint.
  </Tab>

  <Tab title="Azure AD">
    Use **Enterprise Applications** in the Azure portal. Azure AD supports both SAML 2.0 SSO and SCIM provisioning.
  </Tab>

  <Tab title="Google Workspace">
    Use a **SAML app** in the Google Admin Console. Google Workspace supports SAML 2.0 SSO. SCIM provisioning from Google Workspace is not currently supported — use the Toktra API or manual user management instead.
  </Tab>
</Tabs>

## SAML 2.0 SSO setup

### Step 1: Get your SP metadata

Toktra acts as the SAML Service Provider (SP). Retrieve the SP metadata XML to configure your IdP:

```
GET /v1/sso/metadata?org_id=<your-org-id>
```

The response is standard SAML 2.0 SP metadata XML. You can upload this file directly in Okta, Azure AD, or Google Workspace instead of manually entering each field.

**Key SP endpoints:**

| Endpoint                             | URL                                                     |
| ------------------------------------ | ------------------------------------------------------- |
| SP Metadata URL                      | `https://api.toktra.io/v1/sso/metadata?org_id=<org_id>` |
| ACS (Assertion Consumer Service) URL | `https://api.toktra.io/v1/sso/acs?org_id=<org_id>`      |
| SP-initiated login                   | `https://api.toktra.io/v1/sso/login?org_id=<org_id>`    |
| Single Logout (SLO)                  | `https://api.toktra.io/v1/sso/logout?org_id=<org_id>`   |

### Step 2: Configure your IdP

<Steps>
  <Step title="Create a SAML app in your IdP">
    In Okta: go to **Applications → Create App Integration → SAML 2.0**.
    In Azure AD: go to **Enterprise Applications → New application → Create your own application → Integrate any other application**.
    In Google Workspace: go to **Apps → Web and mobile apps → Add app → Add custom SAML app**.
  </Step>

  <Step title="Upload SP metadata or enter values manually">
    If your IdP supports metadata upload, paste the URL from the step above or upload the downloaded XML.

    If you must enter values manually, use:

    * **ACS URL:** `https://api.toktra.io/v1/sso/acs?org_id=<org_id>`
    * **Entity ID / Audience:** `https://api.toktra.io` (or the value in the SP metadata `entityID` attribute)
    * **Name ID format:** `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
  </Step>

  <Step title="Map attributes">
    Toktra requires the following attributes in the SAML assertion:

    | Attribute    | IdP claim   | Notes                                            |
    | ------------ | ----------- | ------------------------------------------------ |
    | `email`      | User email  | Required. Used as the user's primary identifier. |
    | `firstName`  | Given name  | Optional but recommended.                        |
    | `lastName`   | Family name | Optional but recommended.                        |
    | `department` | Department  | Optional. Used for budget scoping.               |
  </Step>

  <Step title="Save and download IdP metadata">
    Save the app in your IdP and download the IdP metadata XML (or copy the metadata URL).
  </Step>
</Steps>

### Step 3: Upload IdP metadata to Toktra

Call `POST /v1/sso/config` with the IdP metadata:

```json theme={null}
{
  "provider": "okta",
  "idp_metadata_xml": "<base64-encoded IdP metadata XML>",
  "enabled": true
}
```

Alternatively, provide the IdP metadata URL and Toktra will fetch it:

```json theme={null}
{
  "provider": "azure_ad",
  "idp_metadata_url": "https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml",
  "enabled": true
}
```

### Step 4: Test the SP-initiated login flow

<Steps>
  <Step title="Open the login URL in a browser">
    Visit `https://api.toktra.io/v1/sso/login?org_id=<org_id>&relay_state=/`. The response contains a `redirect_url` — open it to be redirected to your IdP's login page.
  </Step>

  <Step title="Authenticate with your IdP credentials">
    Complete the IdP login. The IdP posts a `SAMLResponse` to the Toktra ACS endpoint.
  </Step>

  <Step title="Verify the callback">
    On success, the ACS endpoint returns a session token and your `relay_state` destination. The user is provisioned in Toktra if they do not already exist.
  </Step>
</Steps>

<Note>
  SP-initiated login is the recommended flow. IdP-initiated login (where the user clicks a tile in the IdP portal) is also supported but the `relay_state` will default to `/`.
</Note>

## SCIM 2.0 provisioning

SCIM automates user and group lifecycle management: when you add, update, or deactivate a user in your IdP, the change is reflected in Toktra automatically.

Toktra's SCIM 2.0 endpoint is fully RFC 7643/7644 compliant and supports the following operations:

| Resource | Supported operations                     |
| -------- | ---------------------------------------- |
| Users    | Create, Read, Update (PUT/PATCH), Delete |
| Groups   | Create, Read                             |

### Step 1: Get a SCIM Bearer token

Generate a SCIM Bearer token from the Toktra dashboard:

1. Go to **Settings → SSO / SCIM** (`SSOConfigPage` at `/settings/sso`).
2. Click **Generate SCIM Token**.
3. Copy the token — it will not be shown again.

<Warning>
  Treat the SCIM Bearer token like a password. Anyone with this token can provision and deprovision users in your Toktra organization.
</Warning>

### Step 2: Configure SCIM in your IdP

<Tabs>
  <Tab title="Okta">
    In the Okta app you created for SAML, go to **Provisioning → Configure API Integration**:

    * **Base URL:** `https://api.toktra.io/v1/scim/v2`
    * **API Token:** paste the Bearer token from step 1
    * Click **Test API Credentials** to verify the connection.

    Under **Provisioning To App**, enable:

    * Create Users
    * Update User Attributes
    * Deactivate Users
  </Tab>

  <Tab title="Azure AD">
    In your Enterprise Application, go to **Provisioning → Automatic**:

    * **Tenant URL:** `https://api.toktra.io/v1/scim/v2`
    * **Secret Token:** paste the Bearer token from step 1
    * Click **Test Connection** to verify.

    Set **Provisioning Mode** to **Automatic** and configure the attribute mapping to match the SCIM schema.
  </Tab>
</Tabs>

### What SCIM syncs

| What                 | How                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User creation        | When you assign the Toktra app to a user in your IdP, SCIM creates the user in Toktra.                                                                              |
| User updates         | Profile changes (name, email, department) in the IdP are synced to Toktra.                                                                                          |
| User deactivation    | Deactivating a user in the IdP sets `active: false` in Toktra. Combined with the Okta `user.lifecycle.deactivate` webhook, this also triggers the lockout pipeline. |
| Groups / departments | SCIM Groups map to Toktra departments, enabling department-level budget enforcement to work automatically as your org chart changes.                                |

### Step 3: Test the connection

After saving the SCIM configuration in your IdP, trigger a test provisioning event:

1. Assign a test user to the Toktra app in your IdP.
2. Verify the user appears in Toktra under **Users**.
3. Update the test user's display name in the IdP and confirm the change syncs within the IdP's provisioning interval (typically 40 minutes for Okta; near-real-time for Azure AD with on-demand provisioning).

<Tip>
  Use the SCIM discovery endpoints to validate your configuration:

  * `GET /v1/scim/v2/ServiceProviderConfig` — lists supported SCIM features
  * `GET /v1/scim/v2/ResourceTypes` — lists supported resource types (User, Group)
  * `GET /v1/scim/v2/Schemas` — lists the SCIM schemas with attribute definitions
</Tip>

## Rotating credentials

To rotate the SCIM Bearer token, generate a new one from **Settings → SSO / SCIM** and update the token in your IdP immediately. The old token is invalidated as soon as the new one is generated.

To rotate the SAML signing certificate, update the SP certificate in both Toktra (`SAML_CERT_PATH` / `SAML_KEY_PATH`) and the IdP app configuration. SAML certificate rotation requires a brief maintenance window to keep both sides in sync.