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

# SSO setup (SAML 2.0)

> Configure SAML 2.0 Single Sign-On (SSO) for the Resistant Documents Web UI.

This guide explains how to enable **Single Sign-On (SSO)** for the Resistant Documents **Web UI** using **SAML 2.0**.

<Note>
  Web UI SSO is for human users accessing the hosted UI and is separate from Documents API authentication.
</Note>

## Why use SSO

SSO helps you:

* use your existing IdP policies (MFA, conditional access)
* centralize user lifecycle management (joiner/mover/leaver)
* optionally map Web UI roles via attributes

***

## Required user attributes

Your IdP must provide these attributes:

* `email` (business email; used as the username)
* `firstName`
* `lastName`
* `documents_roles` (role mapping per tenant)

### Role mapping: `documents_roles`

Provide `documents_roles` as an array of strings of tenant-scoped role values.

**Available roles:**

* `<tenant_id>_RO` → **Viewer** (read-only access to analysis results)
* `<tenant_id>_RW` → **Analyst** (upload documents and review results)
* `<tenant_id>_ADMIN` → **Admin** (manage users, roles, and access)

**Example:**

```text theme={null}
tenant1_RO
tenant2_RW
tenant3_ADMIN
```

A user can have different roles across multiple tenants.

<Note>
  In SAML, this is typically sent as a **multi-valued attribute** (same attribute name, multiple values).
</Note>

### Admin role configuration

To grant a user the **Admin** role, include `<tenant_id>_ADMIN` in the `documents_roles` attribute.

Admins can access the **Admin Settings** section to view the user list. User provisioning, role assignment, and lifecycle management remain controlled by your IdP.

<Note>
  For details on what admins can and cannot do in SSO-managed tenants, see [Admin settings (SSO-managed tenants)](./sso-admin-settings).
</Note>

***

## Testing vs Production

Testing and production Web UI tenants are separate.

* You typically configure **two SAML applications** in your IdP: one for Testing and one for Production.
* Users must be assigned/provisioned separately for each environment.

***

## High-level setup process (SAML 2.0)

### 1) Configuration exchange (from Resistant AI)

Resistant AI provides the Service Provider (SP) details, typically:

* **Entity ID**
* **ACS URL**
* SP metadata XML (for easier import)

### 2) Configure your IdP

Create a new SAML application in your IdP and configure it using the provided SP values.

### 3) Provide IdP metadata (to Resistant AI)

Send Resistant AI your IdP metadata (preferably the metadata XML), or at minimum:

* IdP Entity ID / Issuer
* SSO URL
* IdP signing certificate (public X.509)

### 4) Testing and validation

Customer + Resistant AI validate:

* SSO flow (login redirect and callback)
* SAML assertion signature / validity
* required attribute mapping
* role mapping (if used)

### 5) Rollout

After validation, roll out SSO to users.

***

## Next steps

* If you use Microsoft Entra ID, see [SSO setup (Entra ID)](./sso-entra-id).
* If you prefer OIDC, see [SSO setup (OIDC)](./sso-oidc).