> ## 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 (OIDC)

> Configure OpenID Connect (OIDC) Single Sign-On (SSO) for the Resistant Documents Web UI.

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

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

## When to choose OIDC vs SAML

OIDC is a modern identity protocol built on OAuth 2.0 and is a good fit when your organization prefers OIDC applications and OAuth-based governance.

**Key difference vs SAML:** OIDC requires **direct HTTPS back-channel communication** between Resistant AI’s identity service and your Identity Provider (IdP), because the authorization code is exchanged at your IdP token endpoint.

***

## Supported OIDC configuration

* Flow: **Authorization Code**
* Client authentication: **client secret** or **private key / certificate** (depending on IdP capabilities)
* Required scopes: `openid`, `email`, `profile`

***

## OIDC login flow (high level)

1. User opens the Web UI and is redirected to your IdP for authentication.
2. Your IdP authenticates the user and redirects back with an **authorization code**.
3. Resistant AI exchanges the code at your IdP **token endpoint** (server-to-server) to obtain tokens.
4. Resistant AI validates the ID token and establishes the user session.

***

## Testing vs Production

Testing and production Web UI tenants are separate.

* You typically configure **two OIDC applications** in your IdP: one for Testing and one for Production.
* Users must be assigned/provisioned separately for each environment (depending on your IdP model).

***

## Information required from your team

To set up OIDC, provide:

* Confirmation that OIDC SSO is desired and feasible in your environment
* Your IdP platform/type (e.g., Entra ID, Okta, Ping, etc.)
* OpenID Provider (OP) metadata as:
  * metadata URL (preferred), or
  * metadata file, or
  * a document containing the endpoints

Metadata must include at least:

* Issuer
* Authorization endpoint
* Token endpoint
* JWKS URI

### OIDC client details

* Client ID
* Client secret **or** public key/certificate (shared securely)

***

## Redirect (callback) URI

When registering the OIDC application in your IdP, configure the Redirect URI:

```text theme={null}
https://eu.id.resistant.ai/oauth2/v1/authorize/callback
```

***

## Required user attributes

The following attributes must be available via the **ID token** and/or **UserInfo** response:

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

### Role mapping: `documents_roles`

Provide `documents_roles` as a list 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:**

```json theme={null}
{
  "documents_roles": [
    "tenant1_RO",
    "tenant2_RW",
    "tenant3_ADMIN"
  ]
}
```

A user can have different roles across multiple tenants.

### Admin role configuration

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

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>

***

## Provisioning behavior (JIT)

By default, users can be provisioned using **Just-In-Time (JIT)** provisioning:

* Users are created on first login
* User profile attributes may be updated on subsequent logins when values change

***

## Setup phases

### Phase A — Register OIDC application in your IdP

Create a new OIDC web application in your IdP and configure:

* Redirect URI
* Requested scopes (`openid`, `email`, `profile`)
* Client authentication method (secret or key/certificate)

### Phase B — Provide configuration to Resistant AI

Send Resistant AI:

* Client ID
* Client secret or key/certificate (secure channel)
* OP metadata (URL or file)

### Phase C — Finalization and testing

Customer + Resistant AI validate:

* authentication flow
* attribute mapping
* user access to the Web UI

***

## Next steps

* If you prefer SAML, see [SSO setup (SAML 2.0)](./sso-saml).
* If you use Microsoft Entra ID with SAML, see [SSO setup (Entra ID)](./sso-entra-id).