Active Directory Pro
Login Download Free Trial

Connect Microsoft 365 Tenant

Settings > Connections is where AD Pro Toolkit connects to your Active Directory domains and your Microsoft 365 tenants. It has a tab for each.

Active Directory

The first domain is connected by the setup wizard when you install AD Pro Toolkit. Use the Active Directory tab to add more domains, or to change how a domain connects.

Add a domain

  1. Go to Settings > Connections > Active Directory and select Add domain.
  2. Enter the Domain (FQDN), for example contoso.com.
  3. Enter the Username and Password of the account AD Pro Toolkit should connect with, as DOMAIN\username. If AD Pro Toolkit's service runs as a managed service account, these fields aren't shown; it connects to every domain as that account.
  4. Tick Use LDAPS (port 636) if your domain controllers require encrypted LDAP.
  5. Select Test connection. The test finds a domain controller for you and checks the account has the Replicating Directory Changes permission. If the permission is missing, a warning shows the command to grant it. AD Pro Toolkit still works without it, but syncs are slower.
  6. Select Save.

The new domain is synced at the next scheduled sync.

Switch between domains

When more than one domain is connected, a domain list appears in the title bar. Choose a domain to see its reports and manage its objects. AD Pro Toolkit remembers the last domain each person chose.

The Default domain is the one people see first. To change it, edit a domain and tick Default domain.

Edit a domain

From the ⋯ menu on the domain's row, select Edit. You can change the account, the password, LDAPS, the preferred domain controller and whether the domain is enabled. Leave Password blank to keep the stored one. The domain name can't be changed.

Clear Enabled to stop syncing a domain without removing it.

Delete a domain

From the ⋯ menu on the domain's row, select Delete. If it was the default domain, another domain becomes the default.

Managed service accounts

The account the service runs as is chosen in the setup wizard, not on this page. To switch to or from a managed service account, run the setup wizard again from the AD Pro Toolkit Setup shortcut in the Start menu.

Microsoft 365

AD Pro Toolkit connects to Microsoft 365 using an app registration you create in your own Entra ID (Azure AD) tenant. The app uses application permissions to create and offboard cloud users, assign licenses and manage group membership on your behalf. You stay in control: you grant the permissions, you create the secret, and you can revoke access at any time.

There are two ways to set it up:

  • Run the setup script (recommended). It does every step for you in about two minutes.
  • Set it up by hand in the Entra admin center, if your organization doesn't allow running scripts against the tenant.

Either way you need an account with the Global Administrator role, because the setup grants admin consent and assigns a directory role to the app.

What you will end up with

Three values to paste into AD Pro Toolkit (Settings > Connections > Microsoft 365):

  • Directory (tenant) ID
  • Application (client) ID
  • Client secret value

Option A: Run the setup script

The script creates the app registration, adds every API permission the app needs, grants admin consent, assigns the Exchange Recipient Administrator role, creates a client secret, and prints the three values. It is safe to run again: each step checks whether it is already done first.

Before you start

  • Any Windows PC with internet access will do. It does not have to be the AD Pro Toolkit server.
  • Windows PowerShell 5.1 or PowerShell 7 both work.
  • The script installs the Microsoft.Graph.Authentication module for your user account if it is missing. No other modules are needed.
  • The script supports the Commercial cloud (worldwide and GCC) only. For GCC High or DoD, use Option B.

Run it

  1. In AD Pro Toolkit, go to Settings > Connections > Microsoft 365, open How to connect a tenant, and select Download setup script. This saves Setup-M365AppRegistration.ps1.

  2. Open PowerShell. It does not need to be run as administrator.

  3. Go to the folder you saved the script to, for example:

    cd $HOME\Downloads

  4. Windows blocks scripts downloaded from the internet. Unblock this one:

    Unblock-File .\Setup-M365AppRegistration.ps1

  5. Run the script:

    .\Setup-M365AppRegistration.ps1

    If PowerShell still refuses with "running scripts is disabled on this system", run it for this session only instead:

    powershell -ExecutionPolicy Bypass -File .\Setup-M365AppRegistration.ps1

  6. A Microsoft sign-in window opens. Sign in with your Global Administrator account. If you are asked to consent to Microsoft Graph Command Line Tools, accept. That permission is for the script's own session, not for AD Pro Toolkit.

  7. The script reports each step as it goes. When it finishes, it prints a box like this:

    ====================  Paste these into Settings > Connections > Microsoft 365  ====================
  Tenant ID            : 1a2b3c4d-....
  Application (Client) : 5e6f7a8b-....
  Client Secret        : Abc8Q~....
  (The secret is shown only once. Copy it now.)

  8. Copy all three values now. The secret is not shown again. Then continue with Connect the tenant in AD Pro Toolkit.

Permission and role changes can take a few minutes to apply. If the connection test fails right after the script finishes, wait five minutes and test again.

Script options

Option What it does
-TenantId <id> Signs in to a specific tenant. Useful if your account belongs to more than one.
-DisplayName "<name>" Names a new registration. The default is AD Pro Toolkit.
-AppId <id> Updates an existing registration instead of creating a new one. Permissions already on it are kept.
-SecretMonths <n> Sets how long the client secret lasts. The default is 12 months.
-NoSecret Skips creating a client secret, for example if you manage secrets separately.

For example, to update a registration you already made and give it a 24 month secret:

.\Setup-M365AppRegistration.ps1 -AppId 11111111-2222-3333-4444-555555555555 -SecretMonths 24

Option B: Set it up by hand

Step 1: Register the application

  1. Sign in to the Microsoft Entra admin center.
  2. Go to Identity > Applications > App registrations.
  3. Select New registration.
  4. Enter a name, for example AD Pro Toolkit.
  5. Under Supported account types, choose Accounts in this organizational directory only (Single tenant).
  6. Leave Redirect URI empty. It is not needed.
  7. Select Register.

On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID. You will need both later.

Step 2: Add the API permissions

  1. In the app, go to API permissions.

  2. Select Add a permission, then Microsoft Graph.

  3. Choose Application permissions (not Delegated).

  4. Add the following permissions:

    Permission Why it is needed
    User.ReadWrite.All Create, offboard and manage cloud users, and assign licenses
    Organization.Read.All Read available licenses, verified domains, and tenant country
    Group.Read.All Search groups and read a user's group membership
    GroupMember.ReadWrite.All Add and remove users in security and Microsoft 365 groups
    Device.Read.All Hybrid device last-logon report
    AuditLog.Read.All Hybrid user sign-in activity report

  5. Select Add permissions.

  6. Select Add a permission again, open the APIs my organization uses tab, and search for Office 365 Exchange Online.

  7. Choose Application permissions, add Exchange.ManageAsApp, and select Add permissions. This lets the app manage distribution lists and mail-enabled security groups.

Application permissions do not take effect until an administrator consents to them.

  1. Still on the API permissions page, select Grant admin consent for [your organization].
  2. Confirm. Each permission's Status should change to a green Granted for [your organization].

If the button is greyed out, sign in with a Global Administrator account.

Step 4: Assign the Exchange role

Exchange.ManageAsApp only works when the app also holds an Exchange role.

  1. In the Entra admin center, go to Identity > Roles & admins > Roles & admins.
  2. Open Exchange Recipient Administrator.
  3. Select Add assignments, search for your app by name, select it, and add it.

Step 5: Create a client secret

  1. Back in the app registration, go to Certificates & secrets > Client secrets.
  2. Select New client secret.
  3. Enter a description, for example AD Pro Toolkit, and choose an expiry. A longer expiry means fewer renewals; a shorter one is more secure. 12 or 24 months is common.
  4. Select Add.
  5. Copy the secret Value immediately. It is shown only once. If you navigate away before copying it, delete the secret and create a new one.

Copy the Value, not the Secret ID. The Value is the long string you paste into the app; the Secret ID is just an internal reference and will not work.

Connect the tenant in AD Pro Toolkit

  1. In AD Pro Toolkit, go to Settings > Connections > Microsoft 365.
  2. Select Connect a tenant.
  3. Enter:
    • Connection Name: a friendly label, for example Production Tenant.
    • Tenant ID: the Directory (tenant) ID.
    • Application (Client) ID: the Application (client) ID.
    • Client Secret: the secret Value.
    • Cloud: Commercial for worldwide and GCC, or GCC High / DoD for US Government clouds.
  4. Select Add Connection. The app validates the credentials before saving. A successful test confirms the tenant is connected and ready.

The client secret is stored encrypted on the server and is never shown again.

Renewing the secret before it expires

Client secrets expire on the date you set when creating them. Before then, create a new one either way:

  • With the script: run it again with your app's ID, which adds a new secret and leaves everything else as it is:

    .\Setup-M365AppRegistration.ps1 -AppId <your Application (client) ID>

  • By hand: create a new client secret (Option B, Step 5) and copy its Value.

Then, in AD Pro Toolkit, edit the connection, paste the new secret, and save. Once the new secret works, you can delete the old one in Entra under Certificates & secrets.

Troubleshooting

Active Directory

  • "The username or password was rejected by the domain": check the account and password. Use DOMAIN\username.
  • "Could not reach a domain controller": check the domain name, and that port 389 (or 636 with LDAPS) is open from the computer AD Pro Toolkit is installed on to your domain controllers.
  • The sync permission warning: the account doesn't have Replicating Directory Changes. Run the command shown in the warning on a domain controller, then select Test connection again.
  • The domain list doesn't appear in the title bar: it only shows when more than one domain is connected and enabled.

Microsoft 365

  • "Running scripts is disabled on this system": run Unblock-File on the script, or start it with powershell -ExecutionPolicy Bypass -File .\Setup-M365AppRegistration.ps1.
  • The script fails with "Insufficient privileges" or "Authorization_RequestDenied": the account you signed in with is not a Global Administrator. Run it again with one.
  • "Invalid client secret": you likely copied the Secret ID instead of the Value, or the secret has expired. Create a new secret and use its Value.
  • "Insufficient privileges" in AD Pro Toolkit: admin consent was not granted, or was granted only a few minutes ago. Check the API permissions page (Option B, Step 3), or wait and test again.
  • Distribution lists can't be changed: the app is missing Exchange.ManageAsApp or the Exchange Recipient Administrator role (Option B, Steps 2 and 4). Running the script with -AppId adds both.
  • "The domain portion of the userPrincipalName is invalid": the UPN suffix you are creating the user with is not a verified domain in the tenant. Verify the domain in Entra, or create the user with a verified suffix.