> ## 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.

# OIDC Single Sign-On (SSO) Integration

> Guide to configuring OIDC SSO for your organization.

# OIDC SSO Integration

This guide explains how to configure OpenID Connect (OIDC) Single Sign-On (SSO) for your organization on our platform.

***

## Prerequisites

Before you begin, ensure you have the following:

1. **OIDC Provider Account:** Access to an OIDC provider (e.g., Microsoft Azure AD, Google, Auth0).
2. **Client Credentials:** Obtain these details from your OIDC provider:
   * Client ID
   * Client Secret
   * Authorization Endpoint
   * Token Endpoint
   * User Info Endpoint
3. **User Mapping Keys:** Determine the keys your OIDC provider uses for user details:
   * User Identifier Key (e.g., `userPrincipalName`, `email`)
   * First Name Key
   * Last Name Key

***

## Configuration Steps

### Step 1: Enable OIDC SSO

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

### Step 2: Fill in the Required Fields

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

| Field                           | Description                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **OIDC Client ID**              | Enter the client ID provided by your OIDC provider.                                                                          |
| **OIDC Client Secret**          | Enter the client secret associated with your client ID.                                                                      |
| **OIDC Authorization Endpoint** | URL for user authentication (e.g., `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize`).                   |
| **OIDC Token Endpoint**         | URL for exchanging authorization codes for tokens (e.g., `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`). |
| **OIDC User Info Endpoint**     | URL for retrieving user profile details (e.g., `https://graph.microsoft.com/v1.0/me`).                                       |

### Step 3: Configure User Mapping

Specify the user information fields returned by your OIDC provider:

| Field                        | Description                                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **OIDC User Identifier Key** | The field from the user info response that uniquely identifies a user (e.g., `userPrincipalName`, `email`). |
| **OIDC User First Name Key** | The field representing the user's first name (e.g., `givenName`).                                           |
| **OIDC User Last Name Key**  | The field representing the user's last name (e.g., `surname`).                                              |

> **Note:** If your OIDC provider uses the same key for both first and last names (e.g., `displayName`), use that key in both fields.

### Step 4: Save Changes

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

***

## 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. Authenticate through your OIDC provider.
5. Verify that:
   * You are redirected back to the application.
   * User details (e.g., name, email) are correctly displayed.

***

## Example Configuration for Microsoft Azure AD

Here’s an example configuration for Azure AD:

| Field                           | Value                                                                 |
| ------------------------------- | --------------------------------------------------------------------- |
| **OIDC Client ID**              | `<your-client-id>`                                                    |
| **OIDC Client Secret**          | `<your-client-secret>`                                                |
| **OIDC Authorization Endpoint** | `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize` |
| **OIDC Token Endpoint**         | `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`     |
| **OIDC User Info Endpoint**     | `https://graph.microsoft.com/v1.0/me`                                 |
| **OIDC User Identifier Key**    | `userPrincipalName`                                                   |
| **OIDC User First Name Key**    | `givenName`                                                           |
| **OIDC User Last Name Key**     | `surname`                                                             |

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

***

## Troubleshooting

* **Invalid Client ID/Secret:** Ensure the client ID and secret are correct.
* **Authorization Error:** Verify the authorization endpoint URL and ensure the redirect URI matches the one registered with your OIDC provider.
* **User Info Mapping Issues:** Test the user info endpoint response using a tool like Postman to confirm the keys match your configuration.

***

Need help? Contact our support team for assistance!