> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/microsoft-entra-id-azure-ad/azure-ad-sso.md).

# Entra ID SSO

### Microsoft Entra ID (Azure AD) SSO Login and Architecture Overview

This section walks you through setting up Single Sign-On (SSO) so users can log in to Herd using their Microsoft Entra ID (Azure AD) credentials, giving them one-click access with the same identity they already use at work. By connecting Herd to Microsoft Entra ID for authentication, you reduce password fatigue, improve security, and keep access control aligned with your central identity provider.​

You’ll find step-by-step instructions for creating the required app registration in Microsoft Entra ID, configuring tokens and permissions, and wiring those settings into Herd. Once configured, your users will be able to sign in through Entra ID while you maintain centralized control over who can access Herd, making it easier to onboard, offboard, and audit accounts as your organization grows.

```
User → Herd App → AWS Cognito → Azure AD → User Authenticated
```

Herd uses AWS Cognito as the identity broker, which federates to Microsoft Entra ID (Azure AD) for authentication.

### What You'll Need

* Admin access to your Microsoft Entra ID (Azure AD) tenant
* Admin access to AWS Cognito
* About 20 minutes

### Step 1: Create an App Registration for SSO

> **Note**: This is a SEPARATE app registration from the User Sync app. SSO requires different settings.

1. Go to [Azure Portal](https://portal.azure.com)
2. Navigate to **Microsoft Entra ID (Azure AD)** > **App registrations**
3. Click **+ New registration**
4. Fill in:
   * **Name**: `Herd SSO` (or any name you prefer)
   * **Supported account types**: Select "Accounts in this organizational directory only"
   * **Redirect URI**:
     * Platform: **Web**
     * URL: `https://your-cognito-domain.auth.<region>.amazoncognito.com/oauth2/idpresponse`
       * Replace `<region>` with the AWS region of your Herd deployment's Cognito user pool. This is not always `us-west-2` — copy the exact Cognito domain from your Herd contact.
5. Click **Register**

### Step 2: Note Your IDs

Copy these values from the **Overview** page:

| Field                       | Where to Find It |
| --------------------------- | ---------------- |
| **Application (client) ID** | Overview page    |
| **Directory (tenant) ID**   | Overview page    |

### Step 3: Create a Client Secret

1. Go to **Certificates & secrets**
2. Click **+ New client secret**
3. Add a description (e.g., "Herd SSO")
4. Choose an expiration (recommended: 24 months)
5. Click **Add**
6. **IMPORTANT: Copy the secret VALUE immediately** - you won't be able to see it again

> ⚠️ **Common Mistake**: Copy the **Value** column, NOT the **Secret ID** column. Using the Secret ID will cause authentication to fail.

### Step 4: Configure Token Claims

Microsoft Entra ID (Azure AD) needs to send the user's email in the token:

1. Go to **Token configuration**
2. Click **+ Add optional claim**
3. Select **ID** token type
4. Check these claims:
   * `email`
   * `preferred_username`
   * `upn`
5. Click **Add**
6. Repeat for **Access** token type

### Step 5: Configure API Permissions

1. Go to **API permissions**
2. Click **+ Add a permission**
3. Select **Microsoft Graph**
4. Select **Delegated permissions**
5. Add these permissions:
   * `openid`
   * `profile`
   * `email`
6. Click **Add permissions**
7. Click **Grant admin consent for \[Your Organization]**
8. Share your credentials with Herd support, and we'll complete the configuration

## SSO Troubleshooting

### Error: "Invalid client secret provided"

```
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent
in the request is the client secret value, not the client secret ID
```

**Cause**: You copied the wrong value when creating the client secret.

**Fix**:

1. Go to Azure AD → App Registrations → your SSO app → **Certificates & secrets**
2. Create a **new** client secret
3. Copy the **Value** column (NOT the "Secret ID")
4. Update the secret in AWS Cognito → User Pool → Identity providers → AzureAD

### Error: "Access Token does not have required scopes"

This error appears in backend logs when the Cognito access token doesn't have the scopes needed to call Cognito's GetUser API.

**Cause**: This is expected for federated (SSO) users. The system automatically falls back to extracting email from the ID token.

**Fix**: No action needed if authentication succeeds. If it fails:

1. Ensure the ID token is being passed from frontend to backend via `x-id-token` header
2. Verify Azure AD is configured to include email claims (Step 4)

### Error: User not found / Cannot create user

**Cause**: The user doesn't exist in Herd and couldn't be auto-created.

**Fix**:

1. Run Azure AD User Sync first to import users
2. Or ensure Azure AD is sending the email claim so users can be auto-created

### Error: "Token does not belong to requested organization"

**Cause**: Token issuer mismatch during token refresh.

**Fix**:

1. Clear browser storage and cookies
2. Log out completely
3. Log in again

### SSO Login Not Redirecting to Microsoft Entra ID

**Cause**: Identity provider not configured or `identityProvider` field not set.

**Fix**:

1. Verify the identity provider exists in Cognito
2. Set the `identityProvider` field on the organization to match the Cognito provider name exactly

## Understanding the Username Format

Microsoft Entra ID (Azure AD) SSO users in Cognito have usernames like:

```
azuread-devmscust_f7dsazfc_3_lpr9jokhw0-20fr-y97vwyfkgb57bpkk
```

This is generated by Cognito and contains:

* Prefix: Identity provider name (e.g., `azuread-devmscust`)
* Separator: `_`
* Suffix: Unique identifier from Azure AD

The system automatically detects these as SSO users and handles authentication appropriately.