> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.autophish.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set up Microsoft 365 Directory Sync (Beta)


> **Beta feature:** Microsoft 365 Directory Sync is currently in beta. Review the sync history after setup and after making changes to groups, permissions, or verified domains.

Microsoft 365 Directory Sync connects AutoPhish to Microsoft Entra ID. You select Microsoft 365 or security groups, and AutoPhish creates a corresponding target list for each group.

The synchronization is one-way:

**Microsoft Entra ID → AutoPhish**

Each generated target list is an exact mirror of the group’s eligible members. Add or remove members in Microsoft 365—not in AutoPhish.

## Before you begin

You need:

* Access to the [Microsoft Entra admin center](https://entra.microsoft.com/).
* Permission to create an app registration and grant tenant-wide admin consent. These actions may require assistance from your Microsoft 365 administrator.
* Company administrator access in AutoPhish.
* All employee email domains verified in AutoPhish.

> **Important:** AutoPhish only imports users whose email domain is verified for the active AutoPhish company. Verify the required domains before the first sync. Otherwise, users will be skipped and may be removed from an existing synchronized list.

## 1. Configure Microsoft Entra ID

### Register an application

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/).

2. If you have access to more than one tenant, confirm that you are working in the correct tenant.

3. Go to **Entra ID → App registrations**.

4. Select **New registration**.

5. Enter a name, such as:

   `AutoPhish Directory Sync`

6. Under **Supported account types**, select:

   **Accounts in this organizational directory only (Single tenant)**

7. Leave **Redirect URI** empty. Directory Sync uses application authentication and does not require an interactive Microsoft sign-in or redirect URI.

8. Select **Register**.

For additional information, see [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

### Copy the tenant and client IDs

On the app registration’s **Overview** page, copy:

* **Directory (tenant) ID**
* **Application (client) ID**

You will enter both values in AutoPhish.

> Copy the **Application (client) ID**, not the application’s Object ID.

### Add Microsoft Graph permissions

1. In the app registration, go to **API permissions**.

2. Select **Add a permission**.

3. Select **Microsoft Graph**.

4. Select **Application permissions**.

   Do not select Delegated permissions.

5. Add these permissions:

| Permission | Type | Purpose |
| ---- |
| `Group.Read.All` | Application | Lists supported groups and reads group information |
| `GroupMember.Read.All` | Application | Reads group membership |
| `User.Read.All` | Application | Reads member names, email addresses, user principal names, and account status |

6. Select **Grant admin consent for *your tenant***.

7. Confirm the consent prompt.

8. Verify that all three permissions show **Granted for *your tenant*** in the Status column.

All required permissions are read-only. AutoPhish cannot create, edit, or delete users or groups in Microsoft Entra ID.

Microsoft Graph application permissions apply tenant-wide, even though AutoPhish only synchronizes groups that you explicitly select. See the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for Microsoft’s permission descriptions.

> AutoPhish does not use delegated permissions. If the app registration contains a default delegated `User.Read` permission, it is not required for Directory Sync and may be removed.

### Create a client secret

1. In the app registration, go to **Certificates & secrets**.

2. Open **Client secrets**.

3. Select **New client secret**.

4. Enter a description, such as:

   `AutoPhish Directory Sync`

5. Select an expiration period that complies with your organization’s security policy.

6. Select **Add**.

7. Immediately copy the client secret’s **Value**.

> Copy the secret **Value**, not the Secret ID. Microsoft displays the Value only once.

Store the secret securely until it has been entered in AutoPhish. For more information, see [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials).

### Microsoft 365 configuration checklist

Before continuing, confirm that you have:

* A single-tenant app registration.
* The Directory (tenant) ID.
* The Application (client) ID.
* A client secret Value.
* `Group.Read.All` as an Application permission.
* `GroupMember.Read.All` as an Application permission.
* `User.Read.All` as an Application permission.
* Admin consent granted for all three permissions.
* No redirect URI configured or required.

## 2. Connect Microsoft 365 to AutoPhish

1. Sign in to AutoPhish as a company administrator.

2. Select the company you want to configure.

3. Confirm that the company’s employee email domains are verified in AutoPhish.

4. Go to **Settings → Directory Sync**.

5. Enter the following values:

* **Tenant ID:** the Directory (tenant) ID
* **Client ID:** the Application (client) ID
* **Client Secret:** the client secret Value

6. Select **Save Connection**.

7. Select **Test Connection**.

A successful test displays the number of supported groups found in the tenant.

> **Important:** The connection test verifies authentication and group listing. The first synchronization also tests access to group membership and user details. If the test succeeds but the first sync fails, recheck all three Graph application permissions and their admin-consent status.

## 3. Add a group synchronization

1. Under **Group Mappings**, select **Refresh Groups** if necessary.

2. Select a Microsoft 365 or security group.

3. Select **Add Group Sync**.

AutoPhish creates a new integration-managed target list named approximately:

`M365: <group name>`

The feature does not synchronize into an existing target list.

4. Select **Sync Now** to perform the first synchronization.

5. Review the result under **Sync History**.

Repeat these steps for each group you want to synchronize.

## Supported groups and users

AutoPhish supports:

* Microsoft 365 groups.
* Security-enabled groups, including mail-enabled security groups.
* Users contained in nested groups. Nested membership is flattened during synchronization.

Ordinary distribution lists and dynamic distribution groups are not displayed as supported groups.

Groups with hidden membership should be avoided during the beta. The standard configuration does not request Microsoft Graph’s additional `Member.Read.Hidden` permission.

A user is synchronized only when all of the following apply:

* The member is a Microsoft Entra user object.
* The account is enabled.
* The user has a usable `mail` address or `userPrincipalName`.
* The resulting email address belongs to a domain verified in AutoPhish.

Disabled accounts, users without a usable address, `#EXT#` user principal names, and users with unverified or external email domains are skipped.

## How synchronization works

AutoPhish performs a daily scheduled synchronization. You can also select **Sync Now** at any time.

During each sync, AutoPhish:

* Adds eligible users who joined the group.
* Updates existing members’ first and last names.
* Removes list membership for users who left the group or are no longer eligible.
* Records added, updated, removed, and skipped counts in **Sync History**.

Removing someone from a synchronized list does not erase their historical campaign or reporting data.

Microsoft Graph uses eventual consistency for membership queries. Very recent Microsoft 365 changes may therefore take a short time to appear.

## Managing synchronized target lists

A synchronized target list is integration-managed. While its group mapping exists, you cannot:

* Add, edit, or remove list members manually.
* Import members by CSV.
* Delete the target list.

These restrictions also apply while synchronization is paused.

You can still rename the target list or update its context.

Use the controls under **Settings → Directory Sync** to:

* **Sync Now:** run an immediate synchronization.
* **Pause:** stop scheduled synchronizations.
* **Resume:** restart scheduled synchronizations.
* **Remove:** remove the group mapping.

Removing a mapping keeps the current target-list members and returns the list to normal manual management.

Disconnecting Microsoft 365 removes future group synchronizations but also keeps the current target-list snapshots.

## Rotate an expiring client secret

Microsoft Entra client secrets expire. AutoPhish does not currently track the expiration date or send expiration reminders.

Create an internal reminder to rotate the secret before it expires:

1. Open the AutoPhish app registration in Microsoft Entra ID.

2. Go to **Certificates & secrets → Client secrets**.

3. Create a new client secret.

4. Copy its **Value**.

5. In AutoPhish, go to **Settings → Directory Sync**.

6. Enter the new secret and select **Update Connection**.

7. Select **Test Connection**.

8. After confirming that synchronization works, delete the old secret from Microsoft Entra ID.

When updating only the Tenant ID or Client ID, you can leave the Client Secret field blank to retain the currently stored secret.

## Troubleshooting

### The connection test reports an invalid client secret

Confirm that:

* You entered the client secret **Value**, not its Secret ID.
* The secret has not expired.
* The Tenant ID and Client ID belong to the same app registration.
* No leading or trailing spaces were copied.

### The connection test reports insufficient privileges

Confirm that:

* The permissions were added under **Application permissions**.
* `Group.Read.All`, `GroupMember.Read.All`, and `User.Read.All` are present.
* Admin consent was granted for the tenant.
* Each permission shows **Granted** in Microsoft Entra ID.

Permission changes can take a short time to propagate.

### The connection test succeeds, but synchronization fails

The connection test lists groups but does not read their complete membership.

Recheck `GroupMember.Read.All` and `User.Read.All`, including admin consent. Also confirm that the selected group does not use hidden membership.

### A group does not appear

Select **Refresh Groups**. Only Microsoft 365 groups and security-enabled groups are supported. Ordinary distribution lists are not displayed.

### Users are skipped or the target list is empty

Open **Sync History** and review the skipped-member counts.

Common causes include:

* The user account is disabled.
* The user has no usable email address or user principal name.
* The email domain has not been verified in AutoPhish.
* The user is an external account with an external or `#EXT#` address.

### A manual target-list change is blocked

This is expected. Synchronized lists are exact mirrors and cannot be edited manually. Make the membership change in Microsoft Entra ID, then wait for the next scheduled sync or select **Sync Now**.

To manage the list manually, remove its group mapping first.

### Synchronization stopped after previously working

Check whether the Microsoft Entra client secret has expired. Create a new secret, save it in AutoPhish, and test the connection again.

## Security and data access

Directory Sync uses application-only Microsoft Graph authentication. No Microsoft 365 user signs in through AutoPhish.

AutoPhish reads only the information required for synchronization:

* Group identity and type.
* Group membership.
* Account-enabled status.
* Email address or user principal name.
* First and last name.

The integration does not request Microsoft Graph write permissions and cannot modify your Microsoft 365 users or groups. The client secret is encrypted at rest and is not displayed again after it is saved.