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

# SAML SSO

> Configure SAML 2.0 single sign-on for your organization.

Truthlocks supports native SAML 2.0 single sign-on so your team can authenticate through your existing identity provider (IdP). When SAML is configured, users are automatically routed to your IdP during login.

<Info>
  SAML SSO is available on the **Business** plan and above.
</Info>

## How it works

<Steps>
  <Step title="Configure your IdP">
    Register Truthlocks as a service provider (SP) in your identity provider.
    You need the SP Entity ID and Assertion Consumer Service (ACS) URL from the
    setup screen.
  </Step>

  <Step title="Add connection in Truthlocks">
    In the console, go to **Settings > SSO** and create a new SAML connection.
    Enter your IdP metadata URL or manually provide the IdP entity ID, SSO URL,
    and signing certificate.
  </Step>

  <Step title="Users sign in via IdP">
    Once active, users who visit the console login page are redirected to your
    IdP. After authenticating, they are returned to Truthlocks with a session.
  </Step>
</Steps>

## Service provider details

Provide these values to your IdP when registering Truthlocks:

| Field         | Value                                                    |
| ------------- | -------------------------------------------------------- |
| SP Entity ID  | `urn:truthlocks:<your_tenant_id>`                        |
| ACS URL       | `https://console.truthlocks.com/api/auth/saml/acs`       |
| NameID format | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
| Binding       | HTTP-POST                                                |

## IdP configuration fields

When creating a SAML connection in the console, you can configure your IdP in two ways:

### Option A: metadata URL

Provide your IdP metadata URL and Truthlocks automatically fetches the entity ID, SSO URL, and signing certificate.

### Option B: manual configuration

| Field           | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| IdP Entity ID   | Your identity provider's unique identifier                  |
| IdP SSO URL     | The URL where Truthlocks sends SAML authentication requests |
| IdP Certificate | The X.509 signing certificate from your IdP (PEM format)    |

## Creating a connection via the API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "SAML",
    "idp_metadata_url": "https://idp.example.com/metadata",
    "role_mapping_mode": "GROUPS"
  }'
```

If you prefer manual configuration, omit `idp_metadata_url` and provide `idp_entity_id`, `idp_sso_url`, and `idp_certificate` instead.

## Role mapping

Truthlocks maps IdP group assertions to internal roles during sign-in. Two modes are available:

| Mode     | Behavior                                                                                    |
| -------- | ------------------------------------------------------------------------------------------- |
| `STATIC` | All SAML users receive a fixed default role (e.g., `viewer`)                                |
| `GROUPS` | IdP group names are mapped to Truthlocks roles (`admin`, `editor`, `auditor`) automatically |

Set the mode when creating or updating the SSO connection.

## User provisioning

When a user authenticates via SAML for the first time, Truthlocks automatically creates their account using attributes from the SAML assertion (email, first name, last name). This is called just-in-time (JIT) provisioning.

For bulk user sync and deprovisioning, use [SCIM provisioning](/security/scim).

## Session details

* Sessions last **12 hours** after SAML login.
* Session cookies are `HttpOnly` and `SameSite=Lax`.
* A 2-minute clock skew tolerance is applied when validating SAML assertions.

## Testing a connection

After creating a SAML connection, test it before enabling for all users:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/test \
  -H "Authorization: Bearer <admin_token>"
```

This validates that Truthlocks can reach your IdP and parse the metadata correctly.

## Disabling SSO

To revert to standard email/password authentication:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/disable \
  -H "Authorization: Bearer <admin_token>"
```

## Related

* [SCIM provisioning](/security/scim) — Automate user and group sync from your IdP.
* [RBAC & permissions](/security/rbac) — Understand the roles that SAML users are mapped to.
* [Authentication](/security/auth) — API key and JWT authentication methods.