# Azure Active Directory User and Group Sync

### Overview of Azure AD User Group Sync

This section walks you through connecting Herd to your Azure Active Directory to automatically sync users and groups, so your Herd roster always reflects who is actually in your organization. By using Azure AD 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 Azure AD, 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 Azure AD 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 Azure AD tenant
* About 10 minutes

### Step 1: Create an App Registration

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 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                |
| ---------------------- | ---------------------- |
| `Directory.Read.All`   | Read directory data    |
| `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** > **Azure AD Sync**
3. Enter:
   * **Tenant ID**: From Step 2
   * **Client ID**: From Step 2
   * **Client Secret**: From Step 3
4. Click **Test Connection**
5. If successful, click **Save**

## Troubleshooting

### Error: 403 Forbidden

This means permissions are missing or not consented:

1. Go back to **API permissions** in Azure Portal
2. Verify all 4 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.


---

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