> 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-active-directory-user-and-group-sync.md).

# Entra ID User and Group Sync

### Overview of Microsoft Entra ID (Azure AD) User and Group Sync

This section walks you through connecting Herd to your Microsoft Entra ID (Azure AD) to automatically sync users and groups, so your Herd roster always reflects who is actually in your organization. By using Entra ID as the source of truth for identities and group membership, you can reduce manual user management, keep access tightly aligned with your directory, and support clean onboarding and off-boarding as people join, move, or leave.

You’ll find step-by-step instructions for creating a dedicated app registration in Entra ID, capturing the required tenant and client IDs, generating a secure client secret, and granting the read-only directory permissions needed for sync. Once those values are entered into Herd and the connection test succeeds, Herd will be able to regularly pull in users and groups from your Entra ID tenant; helping you target the right people, avoid stale accounts, and maintain a consistent security posture across your environment.

### What You'll Need

* Admin access to your Microsoft Entra ID (Azure AD) tenant
* About 10 minutes

### Step 1: Create an App Registration

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 User Sync` (or any name you prefer)
   * **Supported account types**: Select "Accounts in this organizational directory only"
   * **Redirect URI**: Leave blank
5. Click **Register**

### Step 2: Note Your IDs

After creating the app, you'll see the **Overview** page. Copy these values - you'll need them later:

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

### Step 3: Create a Client Secret

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

### Step 4: Add API Permissions

1. Go to **API permissions**
2. Click **+ Add a permission**
3. Select **Microsoft Graph**
4. Select **Application permissions** (not Delegated)
5. Search for and add these permissions:

| Permission             | Purpose                |
| ---------------------- | ---------------------- |
| `User.Read.All`        | Read all users         |
| `Group.Read.All`       | Read all groups        |
| `GroupMember.Read.All` | Read group memberships |

6. Click **Add permissions**

### Step 5: Grant Admin Consent

After adding permissions, you must grant admin consent:

1. Still on the **API permissions** page
2. Click **Grant admin consent for \[Your Organization]**
3. Click **Yes** to confirm
4. Verify all permissions show a green checkmark under "Status"

### Step 6: Configure in Herd

1. Log into Herd as an admin
2. Go to **Settings → Integrations** and open the **Microsoft Entra ID** card (in the **Identity** section)
3. Enter:
   * **Tenant ID (Directory ID)**: From Step 2
   * **Application (Client) ID**: From Step 2
   * **Client Secret**: From Step 3
4. Click **Save**. Herd automatically runs a connection test as part of saving — there is no separate "Test Connection" button. If the test fails, the configuration is not saved and an error is shown.

## Troubleshooting

### Error: 403 Forbidden

This means permissions are missing or not consented:

1. Go back to **API permissions** in Azure Portal
2. Verify all 3 permissions are listed
3. Check that each has **Application** type (not Delegated)
4. Click **Grant admin consent** again
5. Wait 5-10 minutes for changes to propagate
6. Retry the connection test

### Error: Invalid Client

The Client ID or Client Secret is incorrect:

1. Double-check the Client ID matches exactly
2. Create a new Client Secret and try again
3. Make sure you copied the secret **Value**, not the Secret ID

### Error: Unauthorized Client

Admin consent was not granted:

1. Go to **API permissions**
2. Click **Grant admin consent for \[Your Organization]**
3. Ensure you're signed in as an Azure AD admin

### Security Notes

* The app registration only has **read** permissions - it cannot modify your directory
* We recommend setting a calendar reminder to rotate the client secret before it expires
* You can revoke access at any time by deleting the app registration

## Questions?

Contact <support@herdsecurity.io> for assistance.