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

# Microsoft Entra ID (Azure AD) OIDC SSO Integration

This guide explains how to integrate Microsoft Entra ID (Azure AD) with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It also provides detailed steps for customers to obtain the necessary configuration data from their Microsoft Entra ID tenant.

***

## Prerequisites

Before starting, ensure you have:

1. Access to the **Microsoft Entra Admin Center** with permissions to register applications.
2. A valid Microsoft Entra ID tenant.
3. Admin credentials for your organization’s Microsoft Entra ID tenant.

***

## Steps for Customers to Obtain Configuration Data

Follow these steps to retrieve the required information from Microsoft Entra ID.

### Step 1: Register an Application in Microsoft Entra ID

1. Log in to the [Microsoft Entra Admin Center](https://entra.microsoft.com/).
2. Navigate to **App registrations** in the left-hand menu.
3. Click **New registration** and fill out the following details:
   * **Name**: Enter a name for your application (e.g., `Roe-AI SSO Integration App`).
   * **Supported account types**: Choose one of the following:
     * **Accounts in this organizational directory only** (Single tenant).
     * **Accounts in any organizational directory** (Multitenant).
   * **Redirect URI**: Under **Web**, enter the URL of Roe-AI callback endpoint `https://app.roe-ai.com/sso/callback`.
4. Click **Register** to create the application.

***

### Step 2: Retrieve the Client ID and Tenant ID

1. After registration, you’ll be redirected to the application overview page.
2. Note the **Application (client) ID** and **Directory (tenant) ID** from this page. These will be used as the **OIDC Client ID** and **Tenant ID**, respectively.

***

### Step 3: Generate a Client Secret

1. In the application overview, navigate to **Certificates & secrets** in the left-hand menu.
2. Under **Client secrets**, click **New client secret**.
3. Add a description (e.g., `Platform SSO Secret`) and set an expiration period (e.g., 1 year).
4. Click **Add**. Once created, copy the **Value** of the client secret. This will be used as the **OIDC Client Secret**.
   > **Note:** You won’t be able to view this secret again, so copy and store it securely.

***

### Step 4: Configure API Permissions

1. Navigate to **API permissions** in the left-hand menu.
2. Click **Add a permission** and choose **Microsoft Graph**.
3. Select the following permissions:
   * **Delegated Permissions**:
     * `openid`
     * `profile`
     * `email`
     * `offline_access`
   * **Optional**: Add `User.Read` if you need to access additional user details.
4. Click **Add permissions**.
5. Click **Grant admin consent for \[your tenant name]** to grant the necessary permissions.

***

### Step 5: Collect Endpoint URLs

1. Go to the **Endpoints** tab in the Microsoft Entra Admin Center.
2. Note the following endpoint URLs:
   * **Authorization Endpoint**: Copy the URL labeled **OAuth 2.0 authorization endpoint (v2)**.
   * **Token Endpoint**: Copy the URL labeled **OAuth 2.0 token endpoint (v2)**.
   * **User Info Endpoint**: Use `https://graph.microsoft.com/v1.0/me` to fetch user details.

***

## Configuration on Your Platform

Once you’ve collected the necessary information from Microsoft Entra ID, configure it on your platform as follows:

| Field                           | Value                                                                  |
| ------------------------------- | ---------------------------------------------------------------------- |
| **OIDC Client ID**              | The **Application (client) ID** retrieved from the Azure portal.       |
| **OIDC Client Secret**          | The **Client secret** value generated in Step 3.                       |
| **OIDC Authorization Endpoint** | The **OAuth 2.0 authorization endpoint (v2)** URL retrieved in Step 5. |
| **OIDC Token Endpoint**         | The **OAuth 2.0 token endpoint (v2)** URL retrieved in Step 5.         |
| **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`                                                              |

***

## 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 through Microsoft Entra ID.
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**:
  * Ensure the Client ID and Client Secret are entered correctly.
* **Authorization Errors**:
  * Verify the redirect URI matches the one registered in Microsoft Entra ID.
* **User Info Mapping Issues**:
  * Use a tool like Postman to test the User Info Endpoint (`https://graph.microsoft.com/v1.0/me`) and validate the keys.

***

For further assistance, contact our support team.