> ## 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) SAML SSO Integration

This guide explains how to integrate Microsoft Entra ID (Azure AD) with your platform using SAML 2.0 for Single Sign-On (SSO). It provides detailed steps for configuring an enterprise application in Microsoft Entra ID.

***

## Prerequisites

Before starting, ensure you have:

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

***

## Steps to Configure Microsoft Entra ID SAML

Follow these steps to set up SAML SSO with Microsoft Entra ID.

### Step 1: Create an Enterprise Application

1. Log in to the [Microsoft Entra Admin Center](https://entra.microsoft.com/).
2. Navigate to **Enterprise applications** in the left-hand menu.
3. Click **New application**.
4. Click **Create your own application**.
5. Enter a name for your application (e.g., `Roe-AI SSO Integration`).
6. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Click **Create**.

***

### Step 2: Configure SAML Single Sign-On

1. In your new application, navigate to **Single sign-on** in the left-hand menu.
2. Select **SAML** as the single sign-on method.
3. In the **Basic SAML Configuration** section, click **Edit** and fill in:
   * **Identifier (Entity ID)**: `https://api.roe-ai.com/sso/saml/metadata/<your-organization-id>/`
   * **Reply URL (Assertion Consumer Service URL)**: `https://api.roe-ai.com/sso/saml/acs/`
4. Click **Save**.

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

***

### Step 3: Configure Attributes & Claims

1. In the **Attributes & Claims** section, click **Edit**.
2. Ensure the following claims are configured:

| Claim name                                                           | Value                                   |
| -------------------------------------------------------------------- | --------------------------------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` or `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | `user.givenname`                        |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | `user.surname`                          |

3. Click **Save** to apply changes.

> **Tip:** If your users' email addresses are stored in `userPrincipalName` rather than `mail`, use `user.userprincipalname` for the email claim.

***

### Step 4: Download the Certificate

1. In the **SAML Certificates** section, find **Certificate (Base64)**.
2. Click **Download** to download the certificate file.
3. Open the downloaded file in a text editor to get the PEM-formatted certificate.

***

### Step 5: Retrieve IdP Configuration

1. In the **Set up \[Your App Name]** section, note the following:
   * **Login URL**: This will be used as the **SAML IdP SSO URL**.
   * **Microsoft Entra Identifier**: This will be used as the **SAML IdP Entity ID**.

***

### Step 6: Assign Users and Groups

1. Navigate to **Users and groups** in the left-hand menu.
2. Click **Add user/group**.
3. Select the users or groups who should have access to the application.
4. Click **Assign**.

***

## Configuration on Your Platform

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

| Field                          | Value                                                                |
| ------------------------------ | -------------------------------------------------------------------- |
| **SAML IdP Entity ID**         | The **Microsoft Entra Identifier** from Azure.                       |
| **SAML IdP SSO URL**           | The **Login URL** from Azure.                                        |
| **SAML IdP X.509 Certificate** | The certificate downloaded in Step 4 (PEM format).                   |
| **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`      |

***

## 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 Reply URL Error**:
  * Ensure the Reply URL matches exactly: `https://api.roe-ai.com/sso/saml/acs/`
* **Certificate Errors**:
  * Verify the certificate is in PEM format (starts with `-----BEGIN CERTIFICATE-----`).
  * Ensure you downloaded the correct certificate (Base64 format).
* **User Not Found**:
  * Verify the user has been assigned to the enterprise application.
  * Check that the email claim is configured correctly.
* **Attribute Mapping Issues**:
  * Use a SAML debugging tool to inspect the claims being sent.
  * Ensure the claim names match the expected values.
* **AADSTS Errors**:
  * `AADSTS700016`: Application not found. Verify the Entity ID is correct.
  * `AADSTS50011`: Reply URL mismatch. Check the ACS URL configuration.

***

For further assistance, contact our support team.