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

# ADFS OIDC SSO Integration Guide

This guide explains how to integrate **Active Directory Federation Services (ADFS)** with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It includes detailed instructions for retrieving the required configuration data from ADFS.

***

## Prerequisites

Before starting, ensure you have:

1. **Access to the ADFS Management Console** with admin permissions.
2. An SSL certificate installed and configured for your ADFS server.

***

## Steps for Customers to Obtain Configuration Data

Follow these steps to set up ADFS and retrieve the necessary information for integration.

### Step 1: Create a New Application Group in ADFS

1. Open the **ADFS Management Console** on your ADFS server.
2. In the left-hand menu, expand **ADFS** > **Application Groups**.
3. Right-click **Application Groups** and select **Add Application Group**.
4. Enter a name for your application group (e.g., `Your Platform SSO`) and choose **Server application accessing a web API**.
5. Click **Next**.

***

### Step 2: Configure the Server Application

1. On the **Server application** page:
   * **Client Identifier**: Enter a unique identifier (e.g., `your-platform-client-id`).
   * Click **Add Application** and enter the Roe-AI **Redirect URI** `https://app.roe-ai.com/sso/callback`.
2. Click **Next**.

***

### Step 3: Configure the Web API

1. On the **Web API** page:
   * Leave the **Identifier** field as the default value (e.g., `https://<adfs-server>/adfs/services/trust`).
   * Click **Next**.

***

### Step 4: Generate a Client Secret

1. On the **Client Secret** page:
   * Click **Generate a shared secret** and copy the generated value. This will be used as the **OIDC Client Secret**.
   * Click **Next**.

***

### Step 5: Configure Application Permissions

1. On the **Configure Application Permissions** page:
   * Ensure the default permission **openid** is enabled.
   * Add any additional permissions required by your platform (e.g., `email`, `profile`).
   * Click **Next**.

***

### Step 6: Collect the ADFS Endpoints

1. Open the **ADFS Federation Metadata XML** by navigating to `https://<adfs-server>/FederationMetadata/2007-06/FederationMetadata.xml`.
2. Extract the following URLs from the metadata:
   * **Authorization Endpoint**: `https://<adfs-server>/adfs/oauth2/authorize`
   * **Token Endpoint**: `https://<adfs-server>/adfs/oauth2/token`
   * **User Info Endpoint**: Add `/userinfo` to the base ADFS server URL (e.g., `https://<adfs-server>/adfs/oauth2/userinfo`).

Replace `<adfs-server>` with the URL of your ADFS server.

***

## Configuration on Your Platform

Once you’ve collected the necessary information from ADFS, configure your platform as follows:

| Field                           | Value                                         |
| ------------------------------- | --------------------------------------------- |
| **OIDC Client ID**              | The **Client Identifier** configured in ADFS. |
| **OIDC Client Secret**          | The **Client Secret** generated in Step 4.    |
| **OIDC Authorization Endpoint** | `https://<adfs-server>/adfs/oauth2/authorize` |
| **OIDC Token Endpoint**         | `https://<adfs-server>/adfs/oauth2/token`     |
| **OIDC User Info Endpoint**     | `https://<adfs-server>/adfs/oauth2/userinfo`  |
| **OIDC User Identifier Key**    | `sub`                                         |
| **OIDC User First Name Key**    | `given_name`                                  |
| **OIDC User Last Name Key**     | `family_name`                                 |

***

## Testing the Integration

1. Log out of your account on the platform.
2. Go to the login page and select **Sign in with SSO**.
3. Authenticate via ADFS.
4. Verify that:
   * You are redirected back to the platform.
   * Your user details (e.g., name, email) are displayed correctly.

***

## Troubleshooting

* **Invalid Client ID/Secret**:
  * Verify the Client ID and Client Secret are entered correctly in your platform.
* **Authorization Errors**:
  * Ensure the Redirect URI matches the one configured in ADFS.
* **User Info Mapping Issues**:
  * Use a tool like Postman to test the User Info Endpoint (`https://<adfs-server>/adfs/oauth2/userinfo`) and validate the keys.

***

For further assistance, contact our support team.