# Connect Microsoft Entra ID as your IdP

## Overview

This guide walks you through configuring **Microsoft Entra ID** as an OIDC Identity Provider for Barndoor. Once complete, your users will be able to sign in to Barndoor with their Entra ID credentials and their group memberships will flow through for automatic role mapping.

### Prerequisites

* Admin access to your Barndoor account
* Admin access to a Microsoft Entra ID tenant (Global Administrator or Application Administrator role)
* Your Entra **Tenant ID** handy (find it on the Entra Overview page)

## Part 1 — Configure the application in Entra

### Step 1: Create the Enterprise App

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity** → **Applications** → **Enterprise Apps**, then click **+ New application**, then click **+ Create your own application**.
2. **Input Name**: Anything you'd like (e.g. `Barndoor.ai`)
3. **App Type**: Choose the non-gallery option
4. **Click `Create`**.

### Step 2: Add the email claim to the ID token

1. From your new app registration's left nav, click **Token configuration** → **+ Add optional claim**.
2. Token type: **ID** (this is the one that matters for Barndoor)
3. Check the **email** claim and click **Add**.

### Step 3: Add the groups claim

1. Still on **Token configuration**, click **+ Add groups claim**.
2. Choose which groups to include:
   - **Security groups** or **All groups** — simple, includes every group the user is in.
   - **Groups assigned to the application** — recommended for larger tenants; only sends groups that have been explicitly assigned to the Barndoor app. This keeps the token small and limits exposure.
3. Set the group identifier to `sAMAccountName` under **ID**, **Access**, and **SAML** sub-sections.

### Step 4: Edit the manifest (two changes the UI can't make)

1. From the left nav, click **Manifest**. Use Ctrl/Cmd-F to find the `optionalClaims` block.
2. Find the `email` entry **under `idToken`** and set `essential` to `true`:
   ```json
   {
     "name": "email",
     "source": null,
     "essential": true,
     "additionalProperties": []
   }
   ```
3. Find each groups entry and add `cloud_displayname` to `additionalProperties` in **all three** of `idToken`, `accessToken`, and `saml2Token`:
   ```json
   {
     "name": "groups",
     "source": null,
     "essential": false,
     "additionalProperties": [
       "sam_account_name",
       "cloud_displayname"
     ]
   }
   ```

### Step 5: Grant API permissions

1. From the left nav, click **API permissions** → **+ Add a permission** → **Microsoft Graph** → **Delegated permissions**.
2. Tick the following four scopes:
   - `email`
   - `offline_access`
   - `openid`
   - `profile`
3. Click **Add permissions**.

### Step 6: Create a client secret

1. Go to **Certificates & secrets** → **Client secrets** tab → **+ New client secret**.
2. **Description**: e.g. `Barndoor SSO`
3. **Expires**: Max the value (`24 months` at time of writing). Entra requires an expiration.
4. Click **Add**.

### Step 7: Collect the remaining values

1. Go back to **Overview**. Copy the **Application (client) ID**. Also note your **Directory (tenant) ID**.
2. Still on **Overview**, click **Endpoints** in the top bar. A side panel opens with a list of URLs. Copy **OpenID Connect metadata document**.
3. Open the URL in a new browser tab and copy the value for `issuer`.

## Part 2 — Configure the IdP in Barndoor

### Step 8: Open the Barndoor IdP setup form

1. In Barndoor, go to **Identity Provider** and start the **Set up single sign-on (SSO)** flow.
2. **Display name**: Whatever you'd like (e.g. `Entra — Acme Corp`)
3. **Client ID**: The Application (client) ID from Entra Overview.
4. **Client Secret**: The secret **Value** you copied.

### Step 9: Set the Issuer URL to trigger OIDC discovery

1. Paste the Issuer URL from Step 7 into the **Issuer URL** field.
2. Click **Save connection**.

### Step 10: Register the Redirect URI back in Entra

1. On the Barndoor SSO setup page, click the copy icon next to the **Redirect URI**.
2. Back in your Entra app registration, click **Authentication** in the left nav → **+ Add a platform** → **Web**.
3. Paste the Redirect URI and click **Configure**.

### Step 11: Test SSO end-to-end

1. Back in Barndoor's IdP setup, click **Test SSO**. Authenticate.
2. Validate that your identity contains the `groups` claim configured in earlier steps.

### Step 12 (optional): Map Entra groups to Barndoor roles

Once SSO works, you can map Entra groups to Barndoor's Admin role using the standard role-mapping flow.

## Part 3 — SCIM provisioning

### Step 13: Configure SCIM Provisioning

1. In the Barndoor Platform, navigate to the Identity Provider page and go to the section labeled SCIM Provisioning.
2. Click `Configure SCIM Provisioning`. Choose an authentication method.
3. The SCIM Provisioning card will show relevant endpoints needed to set up SCIM provisioning in Entra.
4. In the [Microsoft Entra admin center](https://entra.microsoft.com), select your Enterprise and click **provisioning** in the sidebar, then click **+ New Configuration**. Fill in the required fields based on your authentication method.

## Part 4 — Roll out SSO enforcement

### What changes when you enforce SSO

When you confirm enforcement, Barndoor:

* Requires all organization members to sign in through your IdP
* Permanently clears saved Barndoor passwords for every member
* Leaves password sign-in enabled **only** for the break-glass admin email you configure
* Terminates all active sessions, including the administrator who enabled enforcement

### Prerequisites

Both items in **Before you can enforce SSO** must be complete before **Enforce SSO** is enabled:

1. Click **Test SSO sign-in** to run the full IdP login path.
2. Configure break-glass admin email.

### Enable organization-wide SSO

1. When both prerequisites are complete, click **Enforce SSO** at the bottom of the rollout card.
2. Acknowledge each consequence and click **Confirm Enforcement**.

## Troubleshooting

* **Common issues**: Check for common causes related to login failures, such as issuer mismatch or issues with email claims.
* **Fixes**: Follow prescribed steps to resolve issues.

## Recap

| Value                             | Where it comes from                                | Where it goes                             |
| :-------------------------------- | :------------------------------------------------- | :---------------------------------------- |
| Application (client) ID           | Entra app → Overview                               | Barndoor Client ID                        |
| Client Secret (Value)             | Entra app → Certificates & secrets                 | Barndoor Client Secret                    |
| Issuer URL (from OpenID Metadata) | Entra app → Overview → Endpoints → OpenID Metadata | Barndoor Issuer URL                       |
| Redirect URI                      | Barndoor SSO setup → Step 2                        | Entra app → Authentication → Web platform |

You've now connected Microsoft Entra ID to Barndoor for SSO, SCIM provisioning (if enabled), and optional organization-wide SSO enforcement with break-glass emergency access.