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

# SAML

> SAML authentication setup

Configure Onyx with SAML authentication.

This guide will walk you through the setup process for Okta. Other identity providers will have a similar process.
Please contact us if you need help with a different identity provider.

<Warning>
  SAML authentication requires building Onyx images from source!

  See details in the [Docker Compose guide](/deployment/getting_started/quickstart#launch-with-docker-compose).
</Warning>

## Guide

<Steps>
  <Step title="Create Okta Application">
    Navigate to the Okta **Admin Console** → **Applications** → **Create App Integration**.

    <img className="rounded-image" src="https://mintcdn.com/danswer/bNCAyv_0mlX0VYMw/assets/deployment/oidc_create_integration.png?fit=max&auto=format&n=bNCAyv_0mlX0VYMw&q=85&s=7f3d2daa77956a1e8d40bbd6e46267f9" alt="Okta Create Integration Page" width="2544" height="822" data-path="assets/deployment/oidc_create_integration.png" />
  </Step>

  <Step title="Configure Okta Application">
    Select **SAML 2.0**.

    **Name** your application `Onyx` and upload the Onyx logo.

    <Tip>
      If you are white-labeling Onyx, you can freely name your application and upload your own logo.
    </Tip>

    Add a **Sign sign-on URL**

    ```
    https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
    ```

    Add an **Audience URI (SP Entity ID)**

    ```
    https://YOUR_ONYX_DOMAIN.com/metadata
    ```

    Add an **Attribute Statement** where **Name** is `email` and **Value** is `user.email`.

    <img className="rounded-image" src="https://mintcdn.com/danswer/bNCAyv_0mlX0VYMw/assets/deployment/saml_config.png?fit=max&auto=format&n=bNCAyv_0mlX0VYMw&q=85&s=4fe75973dc9708700ca4e15c0c717498" alt="Okta Configure SAML Application Page" width="2606" height="1996" data-path="assets/deployment/saml_config.png" />
  </Step>

  <Step title="Assign Users to Application">
    Create the application and navigate to the **Assignments** tab to assign users.
  </Step>

  <Step title="Configure Onyx for SAML">
    Navigate to `onyx/backend/ee/onyx/configs/saml_config` and copy the template settings file.

    ```bash theme={null}
    cd onyx/backend/ee/onyx/configs/saml_config
    cp template_settings.yaml settings.yaml
    ```

    Edit the `settings.yaml` file with the following values:

    <AccordionGroup>
      <Accordion title="idp: entityId">
        Go to the **Sign On** tab of your application in Okta, copy the **Metadata URL**,
        and paste it into your browser. You should see XML like:

        ```XML theme={null}
        <md:EntityDescriptor
            xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
            entityID="http://www.okta.com/exkngircrvOYQyNg35d7">
        ...
        </md:EntityDescriptor>
        ```

        Copy the `entityID` value and paste it into `idp: entityId` in `settings.yaml`.
      </Accordion>

      <Accordion title="idp: x509cert">
        In the XML from the previous step, find the `ds:X509Certificate` element.

        ```XML theme={null}
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        [Some certificate value here]
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        ```

        Copy the certificate value and paste it into `idp: x509cert` in `settings.yaml`.
      </Accordion>

      <Accordion title="idp: singleSignOnService: url">
        Go to the **General** tab of your application in Okta and copy the **Embed Link**.
      </Accordion>

      <Accordion title="sp: entityId">
        This is the same as the **Audience URI (SP Entity ID)** you added to the Okta application.

        ```
        https://YOUR_ONYX_DOMAIN.com/metadata
        ```
      </Accordion>

      <Accordion title="sp: assertionConsumerService: url">
        This is the same as the **Sign sign-on URL** you added to the Okta application.

        ```
        https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
        ```
      </Accordion>

      <Accordion title="sp: x509cert">
        Generate a self-signed certificate:

        ```bash theme={null}
        openssl genrsa -out sp-private-key.pem 2048
        openssl req -new -x509 -key sp-private-key.pem -out sp-cert.pem -days 730 -subj "/CN=<YOUR_DOMAIN e.g. saml.onyx.dev>"
        awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' sp-cert.pem
        ```

        Copy the certificate value and paste it into `sp: x509cert` in `settings.yaml`.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Set Onyx Environment Variables">
    Set the following environment variables in your `.env` or `values.yaml` file (Docker and Kubernetes, respectively).

    ```bash .env theme={null}
    AUTH_TYPE=saml
    ```

    <Note>
      If you're using Docker but don't have a `.env` file,
      copy `onyx/deployment/docker_compose/env.prod.template` to a new `.env` file in the same directory.
    </Note>

    ```bash values.yaml theme={null}
    configMap:
      AUTH_TYPE: saml
    ```
  </Step>
</Steps>