# Azure AD SSO

### 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 Azure AD credentials, giving them one-click access with the same identity they already use at work. By connecting Herd to Azure AD 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 Azure AD, configuring tokens and permissions, and wiring those settings into Herd. Once configured, your users will be able to sign in through Azure AD 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 Azure AD for authentication.

### What You'll Need

* Admin access to your 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 **Azure Active Directory** > **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.us-west-2.amazoncognito.com/oauth2/idpresponse`
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

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 Azure

**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

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://herd-security.gitbook.io/herd-security-docs/azure-ad-configuration/azure-ad-sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.