---
title: SAML SSO
description: "Authenticate into Tracecat with SAML SSO: configure your identity provider, map attributes, and enable single sign-on for organization-wide access."
---

## Supported identity providers

- [Okta](#okta)
- [Microsoft Entra ID](#microsoft-entra-id)
- [Authentik](#authentik)
- [Keycloak](#keycloak)

## Configuration

In your `.env` file, make sure you have the following values set.

```bash
TRACECAT__AUTH_TYPES=saml
SAML_IDP_METADATA_URL=https://<your-idp-metadata-url>
```

## Access policy

After SAML authentication succeeds, Tracecat allows organization access when at least one of the following is true:

- The user already has membership in the organization.
- The user has a pending invitation for the organization.
- The user is the first-user superadmin bootstrap account in the default organization.
- The user is a platform superadmin (owner).

Tracecat only auto-provisions SAML user accounts for:

- Pending organization invitations.
- First-user superadmin bootstrap (default organization only).

If this is a new deployment, make sure `TRACECAT__AUTH_SUPERADMIN_EMAIL` exactly matches the email claim sent by your IdP for the owner account.

## Instructions

Tracecat requires both assertions and responses to be signed.

<Info>
    If you are using a self-signed certificate for your metadata URL,
    you'll need to add the CA certificates `.pem` file as a base64-encoded string via the `SAML_CA_CERTS` environment variable.
</Info>

### Okta

<Steps>
    <Step title="Create an SAML app">
        Go to **Applications** and select **Add Application**.
        Select **SAML 2.0** and click on **Create**.
    </Step>
    <Step title="Configure SAML settings">
        - Set the **Single sign-on URL**, **Recipient URL**, and **Destination URL** to `https://<your-tracecat-instance>/auth/saml/acs`.
        - Set the **Audience Restriction** to `https://<your-tracecat-instance>`.

        ![Okta SAML](/img/self-hosting/okta-saml.png)
    </Step>
    <Step title="Configure attribute statements">
        Map `email` to `user.email`

        ![Okta attribute statements](/img/self-hosting/okta-saml-attributes.png)
    </Step>
    <Step title="Configure SAML settings in environment variables">
        Set the following environment variables in your `.env` file:
        - `SAML_IDP_METADATA_URL`: Okta metadata URL
    </Step>
    <Step title="Restart Tracecat instance">
        Restart Tracecat to apply the changes.
    </Step>
    <Step title="Test SSO configuration">
        Navigate to your Tracecat instance and click on the **Login** button.
        You should be redirected to Okta for authentication.
    </Step>
</Steps>


### Microsoft Entra ID

<Info>
    You must enable **Sign SAML response and assertion** in your Microsoft SAML app settings.
    Microsoft SAML apps only sign assertions by default.
</Info>

<Steps>
    <Step title="Create an SAML app">
        Go to **Enterprise applications** and select the **New application** button.
        Find and select the **Microsoft Entra SAML toolkit** app.
    </Step>
    <Step title="Configure SAML settings">
        - Set the **Reply URL** and **Sign on URL** to `https://<your-tracecat-instance>/auth/saml/acs`.
        - Set **Identifier** to `https://<your-tracecat-instance>/api`.
        - Set **Relay State** to `https://<your-tracecat-instance>`.
        - Make sure that **Sign SAML response and assertion** is enabled.

        ![Microsoft Entra SAML](/img/self-hosting/entra-saml.png)
    </Step>
    <Step title="Configure attribute and claims">
        Map `email` to `user.mail`
    </Step>
</Steps>

### Authentik

<Steps>
    <Step title="Create a provider">
        Go to **Providers** and select the **Create** button.
        Choose **SAML Provider** and select the **Next** button.
    </Step>
    <Step title="Configure the provider">
        - Enter a name and choose an authorization flow
        - Set the **ACS URL** to `https://<your-tracecat-instance>/auth/saml/acs`.
        - Set the **Audience** to `https://<your-tracecat-instance>/api`.

        ![Authentik Provider](/img/self-hosting/authentik-provider.png)
    </Step>
    <Step title="Configure assertion signing">
        - Expand the **Advanced protocol settings** section.
        - Select a **Signing Certificate** and ensure **Sign assertions** is enabled.

        ![Authentik Provider](/img/self-hosting/authentik-assertion-signing.png)
    </Step>
    <Step title="Configure property mapping">
        - Select **authentik default SAML Mapping: Name** in **Selected User Property Mappings**.
        - Click the **&lt;** button to deselect it.
        - Select the **Finish** button.

        ![Authentik Provider](/img/self-hosting/authentik-property-mapping.png)
    </Step>
    <Step title="Create an application">
        Go to **Applications** and select the **Create** button.
        Fill in the details as desired.
    </Step>
    <Step title="Find metadata URL">
        - Select the provider you created previously.
        - Select the **Metadata** tab.
        - Select the **Copy download URL** button.
    </Step>
    <Step title="Configure SAML settings in environment variables">
        Set the following environment variables in your `.env` file:
        - `SAML_IDP_METADATA_URL`: Metadata download URL
    </Step>
    <Step title="Restart Tracecat instance">
        Restart Tracecat to apply the changes.
    </Step>
    <Step title="Test SSO configuration">
        Navigate to your Tracecat instance and click on the **Login** button.
        You should be redirected to Authentik for authentication.
    </Step>
</Steps>

### Keycloak

<Steps>
    <Step title="Create a client">
        - Go to **Clients** and select the **Create client** button.
        - Set the **Client type** to **SAML**.
        - Set the **Client ID** to `https://<your-tracecat-instance>/api` and select the **Next** button.

        ![Keycloak Client General Settings](/img/self-hosting/keycloak-client-general.png)
    </Step>
    <Step title="Configure a client">
        - Set the **Valid redirect URIs** to `https://<your-tracecat-instance>/auth/saml/acs`.
        - Set the **Master SAML Processing URL** to `https://<your-tracecat-instance>/auth/saml/acs` and select the **Save** button.

        ![Keycloak Client Login Settings](/img/self-hosting/keycloak-client-login.png)
    </Step>
    <Step title="Configure document signing">
        - In **Settings** tab scroll down to **Signature and Encryption** section.
        - Ensure **Sign documents** is enabled.

        ![Keycloak Document Signing](/img/self-hosting/keycloak-document-signing.png)
    </Step>
    <Step title="Disable client signing">
        - Open **Keys** tab and look into **Signing keys config** section.
        - Ensure **Client signature required** is disabled.

        ![Keycloak Client Signing](/img/self-hosting/keycloak-client-signing.png)
    </Step>
    <Step title="Configure property mapping">
        - Open **Client scopes** tab and click on client scope `https://<your-tracecat-instance>/api-dedicated`.
        - Create new **User Property** mapper for **email** attribute and click **Save**.

        ![Keycloak Property Mapping](/img/self-hosting/keycloak-email-mapper.png)
    </Step>
    <Step title="Find metadata URL">
        - Go to **Realm Settings** ➤ **General** ➤ **Endpoints**.
        - Copy the **SAML 2.0 Identity Provider Metadata** link.

        ![Keycloak Property Mapping](/img/self-hosting/keycloak-metadata-url.png)
    </Step>
    <Step title="Configure SAML settings in environment variables">
        Set the following environment variables in your `.env` file:
        - `SAML_IDP_METADATA_URL`: Metadata download URL
    </Step>
    <Step title="Restart Tracecat instance">
        Restart Tracecat to apply the changes.
    </Step>
    <Step title="Test SSO configuration">
        Navigate to your Tracecat instance and click on the **Login** button.
        You should be redirected to Keycloak for authentication.
    </Step>
</Steps>

## Environment variables

If you know what you're doing, you can configure the SAML configuration via environment variables in the Tracecat `api` service:

### Protocol configuration
- `SAML_ALLOW_UNSOLICITED`: Whether to allow unsolicited SAML responses (default: `false`)
- `SAML_ACCEPTED_TIME_DIFF`: Time difference in seconds for SAML authentication (default: `3`)
- `SAML_AUTHN_REQUESTS_SIGNED`: Whether to require signed SAML authentication requests (default: `false`)
- `SAML_SIGNED_ASSERTIONS`: Whether to require signed SAML assertions (default: `true`)
- `SAML_SIGNED_RESPONSES`: Whether to require signed SAML responses (default: `true`)

### SSL transport configuration
- `SAML_VERIFY_SSL_ENTITY`: Whether to verify SSL certificates for general SAML entity operations (default: `true`)
- `SAML_VERIFY_SSL_METADATA`: Whether to verify SSL certificates when fetching metadata (default: `true`)
- `SAML_CA_CERTS`: Base64 encoded CA certificates for SSL/TLS transport layer validation

### SAML protocol configuration
- `SAML_METADATA_CERT`: Base64 encoded certificate for SAML metadata document signature verification
