# Microsoft Entra ID SSO

This guide walks you through setting up SAML Single Sign-On between Microsoft Entra ID (formerly Azure Active Directory) and the platform.

## Prerequisites

- Microsoft Entra ID administrator access (or Application Administrator role)
- the platform organization administrator access
- Your the platform domain (e.g., `probo.example.com`)
- Access to your DNS settings for domain verification

## Prepare the platform Information

Before configuring Microsoft Entra ID, gather these the platform service provider details:

| Field         | Value                                                            |
| ------------- | ---------------------------------------------------------------- |
| **ACS URL**   | `https://your-probo-domain.com/api/connect/v1/saml/2.0/consume`  |
| **Entity ID** | `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata` |

Replace `your-probo-domain.com` with your actual the platform domain.

## Domain Verification

Before configuring anything else, you must verify domain ownership:

1. Log in to the platform as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **SAML**
3. Click **Verify Domain** (if no configurations exist yet, this option will be available)
4. Copy the provided TXT record value
5. Add a TXT record to your domain's DNS settings:
   ```
   Type: TXT
   Name: _probo-domain-verification.your-company.com
   Value: [Verification token from Probo]
   TTL: 300 (or your DNS provider's default)
   ```
6. Wait for DNS propagation (usually 5-15 minutes)
7. In the platform, click **Complete Verification**
8. If successful, the domain status will show as "Verified"

## Configure Microsoft Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/)
2. Go to **Identity** → **Applications** → **Enterprise applications**
3. Click **New application** → **Create your own application**
4. Enter `Probo` as the application name
5. Select **Integrate any other application you don't find in the gallery (Non-gallery)**
6. Click **Create**
7. In the application overview, go to **Single sign-on** → select **SAML**
8. In **Basic SAML Configuration**, click **Edit** and configure:

   | Field                                          | Value                                                            |
   | ---------------------------------------------- | ---------------------------------------------------------------- |
   | **Identifier (Entity ID)**                     | `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata` |
   | **Reply URL (Assertion Consumer Service URL)** | `https://your-probo-domain.com/api/connect/v1/saml/2.0/consume`  |
   | **Relay State**                                | `[SAML Configuration ID]` (optional - see note below)            |
   | **Sign on URL**                                | `https://your-probo-domain.com` (optional)                       |

   **Important**: The **Relay State** is optional but if you want to support IdP-initiated login flows, it MUST be set to your exact SAML configuration ID (not a placeholder). If set incorrectly, SSO will not work. You'll get this ID after creating the SAML configuration in the platform. You can initially leave this empty and update it later with the exact configuration ID.

9. Click **Save**
10. In **Attributes & Claims**, click **Edit** and configure the following claims:

    | Claim name  | Source attribute |
    | ----------- | ---------------- |
    | `email`     | `user.mail`      |
    | `firstName` | `user.givenname` |
    | `lastName`  | `user.surname`   |

    To add each claim:
    - Click **Add new claim**
    - Enter the claim name (e.g., `email`)
    - Set **Source** to `Attribute`
    - Select the corresponding **Source attribute**
    - Click **Save**

    Also verify that the **Unique User Identifier (Name ID)** is set to `user.userprincipalname` or `user.mail` with the format `Email address`.

11. In **SAML Certificates**, download the **Certificate (Base64)** and copy:
    - **Login URL** (this is the IdP SSO URL)
    - **Microsoft Entra Identifier** (this is the IdP Entity ID)

12. Go to **Users and groups**
13. Click **Add user/group**
14. Select users or groups that should have access to the platform
15. Click **Assign**

## Configure the platform

1. Log in to the platform as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **SAML**
3. Click **Add SAML Configuration**
4. Configure the basic settings:

   | Field                  | Value              | Notes                            |
   | ---------------------- | ------------------ | -------------------------------- |
   | **Email Domain**       | `your-company.com` | Your organization's email domain |
   | **Enforcement Policy** | `OPTIONAL`         | Recommended for initial setup    |

5. Configure the Identity Provider settings with values from Microsoft Entra ID:

   | Field               | Value                          | Notes                                    |
   | ------------------- | ------------------------------ | ---------------------------------------- |
   | **IdP Entity ID**   | `[Microsoft Entra Identifier]` | Copy from Entra ID setup                 |
   | **IdP SSO URL**     | `[Login URL]`                  | Copy from Entra ID setup                 |
   | **IdP Certificate** | `[Certificate (Base64)]`       | Paste the downloaded certificate content |

6. Configure the attribute mappings:

   | Field                    | Value           | Notes                                  |
   | ------------------------ | --------------- | -------------------------------------- |
   | **Email Attribute**      | `email`         | Maps to user email                     |
   | **First Name Attribute** | `firstName`     | Maps to user first name                |
   | **Last Name Attribute**  | `lastName`      | Maps to user last name                 |
   | **Role Attribute**       | `[Leave empty]` | Optional; map to send `OWNER`, `ADMIN`, `EMPLOYEE`, or `VIEWER` |

7. Configure user settings:

   | Field           | Value     | Notes                                             |
   | --------------- | --------- | ------------------------------------------------- |
   | **Auto Signup** | `Enabled` | Allows new users to sign up automatically via SSO |

8. Click **Save Configuration**
9. **Copy the SAML Configuration ID** that appears after saving (e.g., `saml_config_1a2b3c4d`)

## Update Entra ID Relay State

Return to Microsoft Entra ID to enable IdP-initiated login:

1. Go to your the platform enterprise application in the Entra admin center
2. Click **Single sign-on** → **Edit** Basic SAML Configuration
3. In the **Relay State** field, enter your SAML configuration ID
4. Click **Save**

## Troubleshooting

### "AADSTS75005: The request is not a valid Saml2 protocol message" Error

- **Cause**: Incorrect Reply URL or Entity ID configuration
- **Solution**: Verify that the Reply URL and Entity ID in Entra ID exactly match your the platform configuration:
  - Reply URL: `https://your-probo-domain.com/api/connect/v1/saml/2.0/consume`
  - Entity ID: `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata`

### "AADSTS50105: User not assigned to application" Error

- **Cause**: User has not been assigned to the the platform enterprise application
- **Solution**: Go to the enterprise application → **Users and groups** → assign the user or a group containing the user

### "AADSTS700016: Application not found" Error

- **Cause**: Incorrect Entity ID in the platform or application not properly configured
- **Solution**: Verify the Microsoft Entra Identifier matches the IdP Entity ID configured in the platform

### Attributes Not Mapping

- **Cause**: Claims not configured correctly in Entra ID
- **Solution**: Verify that custom claims are configured with exact names: `email`, `firstName`, `lastName`. Check under **Single sign-on** → **Attributes & Claims**

### "Invalid RelayState" Error

- **Cause**: Incorrect Relay State configuration
- **Solution**: Ensure Relay State is either empty or set to the exact SAML configuration ID from the platform

### Debugging Steps

#### Check Entra ID Sign-in Logs

1. Go to the Entra admin center → **Identity** → **Monitoring & health** → **Sign-in logs**
2. Filter by the the platform application
3. Click on a failed sign-in attempt to view error details and troubleshooting recommendations

#### Test SAML Response

1. In the the platform enterprise application, go to **Single sign-on**
2. Click **Test this application**
3. Review the SAML response for errors

## Advanced Configuration

### Custom Claims

To map additional Entra ID user attributes:

1. In the enterprise application, go to **Single sign-on** → **Attributes & Claims**
2. Click **Add new claim**
3. Map additional directory attributes as needed
4. Update the corresponding attribute mappings in the platform

### Conditional Access

Control access using Microsoft Entra ID Conditional Access policies:

1. Go to **Identity** → **Protection** → **Conditional Access**
2. Create a new policy targeting the the platform application
3. Configure conditions (location, device, risk level, etc.)
4. Set appropriate access controls (grant, block, require MFA)

### Group-Based Access

Restrict access using Entra ID groups:

1. In the enterprise application, go to **Users and groups**
2. Assign groups instead of individual users
3. Manage access by adding/removing users from the assigned groups

For detailed troubleshooting and advanced configuration options, see the [SSO Overview](/docs/product/sso/overview) guide.