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

# SAML SSO

> Requirements and setup process for Team and enterprise customers

Refero supports SAML 2.0 single sign-on (SSO) as a paid add-on for Team subscriptions and custom enterprise agreements. The add-on is priced separately from Team seats.

SSO setup is completed together with the Refero team. This page explains the requirements and general process; Refero provides workspace-specific configuration during setup.

Refero acts as the **service provider (SP)**. Your identity provider, such as Okta, Microsoft Entra ID, Google Workspace, or OneLogin, acts as the **identity provider (IdP)**.

<Note>The URLs below show their expected format. Refero will provide the complete ACS URL and Entity ID for your workspace.</Note>

## Prerequisites

* A Team subscription or custom enterprise agreement with the SSO add-on
* Admin access to your identity provider
* The company email domain to enable for SSO

## Request SSO

To discuss pricing and setup requirements, email [mike@refero.design](mailto:mike@refero.design) with:

* Your company name and expected number of Refero seats
* Your identity provider and company email domain or domains
* Your rollout expectations, preferred timeline, and any security requirements

## How setup works

1. Refero confirms the commercial terms and setup scope with your team.
2. Refero gives you the workspace-specific ACS URL and Entity ID.
3. Your IT team creates a SAML application for Refero and sends the IdP metadata to [mike@refero.design](mailto:mike@refero.design).
4. Refero enables SSO routing and JIT provisioning for your configured company domains.
5. Your team tests sign-in before rolling SSO out to the workspace.

## SAML configuration

| Setting                               | Value                                                                |
| ------------------------------------- | -------------------------------------------------------------------- |
| SP-initiated sign-in URL / Start URL  | `https://api.refero.design/auth/saml/{organization_sso_id}/init`     |
| ACS URL / Reply URL                   | `https://api.refero.design/auth/saml/{organization_sso_id}/acs`      |
| Audience URI / Entity ID / Identifier | `https://api.refero.design/auth/saml/{organization_sso_id}/metadata` |
| ACS binding                           | `HTTP-POST`                                                          |
| Signature algorithm                   | `RSA-SHA256`                                                         |
| Digest algorithm                      | `SHA256`                                                             |
| Name ID value / Unique Identifier     | User's email address                                                 |
| Name ID format                        | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`             |

`{organization_sso_id}` is a placeholder. Do not copy it as-is or reuse an ID from another workspace.

## User identifier

Refero requires an email-like identifier in the SAML assertion. Set the user's email address as the **Name ID** using the `emailAddress` format. Refero uses this email to find an existing account or create a new one.

Refero also recognizes common email attributes as fallbacks, but Name ID is the preferred configuration.

## What Refero needs from you

| Item         | Notes                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------ |
| SSO domains  | Up to eight company email domains with valid MX records, used to route sign-in to your IdP |
| IdP metadata | Metadata URL preferred; XML metadata file also works                                       |

## Provisioning

Provisioning means creating the user's Refero account and adding them to the correct workspace.

Refero uses **JIT provisioning** for SSO workspaces. After successful SAML authentication, Refero creates the account if needed and adds it to the configured Team workspace. Existing accounts are matched by email.

Control who can access Refero by assigning the SAML application only to eligible users or groups in your identity provider.

Users begin at [refero.design](https://refero.design) and enter their work email. If the email domain is configured for SSO, Refero redirects them to the identity provider.