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

# SAML Single Sign-On (SSO) Integration

> Guide to configuring SAML SSO for your organization.

# SAML SSO Integration

This guide explains how to configure Security Assertion Markup Language (SAML) Single Sign-On (SSO) for your organization on our platform.

***

## Prerequisites

Before you begin, ensure you have the following:

1. **SAML Identity Provider (IdP) Account:** Access to a SAML 2.0 compatible identity provider (e.g., Microsoft Entra ID, Okta, ADFS).
2. **IdP Configuration Details:** Obtain these details from your identity provider:
   * IdP Entity ID
   * IdP SSO URL (Single Sign-On Service URL)
   * IdP X.509 Certificate (PEM format)
3. **Attribute Mapping:** Determine which SAML attributes your IdP uses for user details:
   * User Identifier (email attribute)
   * First Name attribute
   * Last Name attribute

***

## Service Provider (SP) Information

When configuring your identity provider, you'll need the following information about Roe AI:

| Field                                    | Value                                                              |
| ---------------------------------------- | ------------------------------------------------------------------ |
| **SP Entity ID**                         | `https://api.roe-ai.com/sso/saml/metadata/<your-organization-id>/` |
| **Assertion Consumer Service (ACS) URL** | `https://api.roe-ai.com/sso/saml/acs/`                             |
| **SP Metadata URL**                      | `https://api.roe-ai.com/sso/saml/metadata/<your-organization-id>/` |

> **Note:** Replace `<your-organization-id>` with your actual organization ID from the Roe AI platform.

***

## Configuration Steps

### Step 1: Enable SAML SSO

1. Go to **Organization Single Sign-On (SSO)** settings in the application.
2. Toggle SSO to **Enabled**.
3. Select **SAML** as the SSO protocol.

### Step 2: Fill in the Required Fields

Fill out the following fields using information from your identity provider:

| Field                          | Description                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **SAML IdP Entity ID**         | The unique identifier for your identity provider (e.g., `https://sts.windows.net/<tenant-id>/`).              |
| **SAML IdP SSO URL**           | The URL where authentication requests are sent (e.g., `https://login.microsoftonline.com/<tenant-id>/saml2`). |
| **SAML IdP X.509 Certificate** | The public certificate from your IdP used to verify SAML responses (PEM format).                              |

### Step 3: Configure Optional Settings

| Field                      | Description                                                                                                      | Default        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
| **SAML SP Entity ID**      | Custom Service Provider Entity ID. If not set, defaults to the metadata URL.                                     | Auto-generated |
| **NameID Format**          | The format for the NameID in SAML assertions. Options: `emailAddress`, `persistent`, `transient`, `unspecified`. | `emailAddress` |
| **Want Assertions Signed** | Require the IdP to sign SAML assertions.                                                                         | `True`         |
| **Want Response Signed**   | Require the IdP to sign the entire SAML response.                                                                | `False`        |

### Step 4: Configure Attribute Mapping

Specify the SAML attribute names returned by your identity provider:

| Field                        | Description                                        | Default      |
| ---------------------------- | -------------------------------------------------- | ------------ |
| **SAML User Identifier Key** | The attribute containing the user's email address. | `email`      |
| **SAML User First Name Key** | The attribute containing the user's first name.    | `first_name` |
| **SAML User Last Name Key**  | The attribute containing the user's last name.     | `last_name`  |

> **Note:** Our platform supports common attribute name variations automatically. For example, for email, we check: `email`, `emailAddress`, `Email`, `mail`, and standard SAML/LDAP URIs.

### Step 5: Save Changes

Click the **Save Changes** button to store your configuration. The SAML SSO login will be enabled for your organization.

***

## Supported Attribute Names

Our platform automatically maps common attribute name variations:

### Email Attributes

* `email`, `emailAddress`, `Email`, `EmailAddress`, `mail`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
* `urn:oid:0.9.2342.19200300.100.1.3`

### First Name Attributes

* `first_name`, `firstName`, `givenName`, `given_name`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
* `urn:oid:2.5.4.42`

### Last Name Attributes

* `last_name`, `lastName`, `surname`, `sn`, `family_name`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
* `urn:oid:2.5.4.4`

***

## Testing the Integration

1. Log out of your account.
2. Click **Sign In** on the login page.
3. Select the **Sign in with SSO** option.
4. Enter your organization's email domain or identifier.
5. Authenticate through your SAML identity provider.
6. Verify that:
   * You are redirected back to the application.
   * User details (e.g., name, email) are correctly displayed.

***

## Example Configuration for Microsoft Entra ID

Here's an example configuration for Microsoft Entra ID (Azure AD):

| Field                          | Value                                                                |
| ------------------------------ | -------------------------------------------------------------------- |
| **SAML IdP Entity ID**         | `https://sts.windows.net/<tenant-id>/`                               |
| **SAML IdP SSO URL**           | `https://login.microsoftonline.com/<tenant-id>/saml2`                |
| **SAML IdP X.509 Certificate** | (Download from Azure AD SAML configuration)                          |
| **SAML User Identifier Key**   | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| **SAML User First Name Key**   | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    |
| **SAML User Last Name Key**    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      |

Replace `<tenant-id>` with your Azure AD tenant ID.

***

## Troubleshooting

* **Invalid IdP Certificate:** Ensure the certificate is in PEM format and includes the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` headers.
* **Signature Validation Error:** Verify that "Want Assertions Signed" matches your IdP's signing configuration.
* **User Not Found:** Check that the user identifier attribute contains a valid email address.
* **Attribute Mapping Issues:** Use your IdP's SAML tracer or test tool to inspect the actual attribute names being sent in the SAML response.
* **Clock Skew Errors:** Ensure the server time on both the IdP and SP are synchronized. Our platform allows up to 2 minutes of clock skew.

***

Need help? Contact our support team for assistance!