> For the complete documentation index, see [llms.txt](https://docs.datasaur.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasaur.ai/integrations/saml.md).

# SAML

Datasaur supports SAML as an authentication method. SAML requires an Identity Provider (IdP) to function correctly. Each team workspace can have its own SAML setup.

## Pre-requisites

To enable SAML for authentication, you must first [claim your domain](/integrations/domain-claim.md). This step verifies that you own the domain and prevents unauthorized parties from accessing or inviting users without permission.

## Terminologies

1. IdP = Identity provider such as Okta, Microsoft Entra ID, etc.
2. SP = Service provider. In this case, it's Datasaur.

## Scope

Users invited to a workspace with SAML enabled can sign in using SAML automatically.

If a user belongs to multiple workspaces with different SAML configurations, Datasaur uses the **Company ID** to determine which IdP should be used during authentication.

## How to integrate

To integrate your IdP with Datasaur, enable SAML in your workspace settings.

1. Go to **Settings** **> SAML & SCIM**.
2. Click **Enable SAML 2.0**. Keep the form open until setup is complete.
3. In your IdP console, connect it to Datasaur using:

   * SP Sign-in URL.
   * SP Issuer.

   Refer to the IdP-specific guides ([Okta](/integrations/saml/okta.md), [Microsoft Entra ID](/integrations/saml/microsoft-entra-id.md)) for detailed setup steps.
4. After configuring your IdP, fill in the following fields in Datasaur:
   * Identity provider sign in URL.
   * Identity provider issuer.
   * Public certificate.
5. You may also complete any additional IdP-specific configuration as required.

### SAML integration form

#### Values to fill in IdP

* **SP Sign-in URL**: This is the Datasaur endpoint where SAML responses are posted. You will need to provide this URL to your IdP during setup.
* **SP Issuer**: The default value is `datasaur`, but you can customize it to your preferences. This value must match the one you set in your IdP.

#### Values to fill in Datasaur

* **Company ID**: A unique identifier to help Datasaur distinguish between multiple IdPs. This attribute will be asked to users when signing in using SAML so that Datasaur can connect to the appropriate IdP.
* **Identity provider sign in URL**: This URL will be requested by Datasaur to perform SAML authentication.
* **Identity provider issuer**: This value will be used to determine which IdP Datasaur should look into when receiving the SAML response.
* **Public certificate**: Used by Datasaur to validate the signature of incoming SAML responses.

## Authentication

### Sign in

1. Click the **SAML** button on the sign in page.
2. Enter the **correct Company ID**. If you are unsure, check with your admin. This ID is set during the SAML integration setup.
3. Continue authentication through your IdP.

### Sign up

If this is your first time signing in with your IdP account, you need to register first. Go to the **Sign up** page and select the **SAML** option. After successful registration, you will be automatically added to the SAML-enabled workspace.

## Provisioning through custom attributes

Datasaur supports role assignment using custom SAML attributes included in the SAML response. This feature is optional and helps manage multiple workspaces from a single Identity Provider app without using SCIM.

There are [four available Workspace roles](/workspace-management/role-and-permission.md#workspace-role): Admin, Supervisor, Reviewer, and Labeler.

To enable this, your IdP must send a `roles` attribute containing an array of values in the following format:

```
<yourCompanyId>_<UPPERCASE_ROLE>
```

### Example

For example, if:

* `company-a` is the Company ID for Workspace A.
* `company-b` is the Company ID for Workspace B.

And a user should be:

* **Admin** in Workspace A.
* **Reviewer** in Workspace B.

Then the `roles` attribute should be:

```
...
<saml2:Attribute
  Name="roles"
  NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
>
  <saml2:AttributeValue
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="xs:string"
  >
    company-a_ADMIN
  </saml2:AttributeValue>
  <saml2:AttributeValue
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="xs:string"
  >
    company-b_REVIEWER
  </saml2:AttributeValue>
</saml2:Attribute>
...
```

The processing of custom attributes only occurs when the `roles` attribute is defined.

* **If there is no match** (the input company ID is not found in any of the roles), the authentication process will fail.
* If a specific user has been invited to a workspace but the **custom attribute is missing**, the user won't be able to authenticate but will still exist in the workspace.
* **If at least one match is found** (the Company ID is found in one of the roles), authentication will succeed, and the following side effects will occur:
  * The user will be automatically registered if they do not already exist.
  * The user will be automatically added to the workspace (not just invited via email) if they are not yet a member.
  * The user’s role will be automatically synchronized if it differs from the role defined in the custom attribute.