Install AD Pro Toolkit

AD Pro Toolkit is installed on one computer, a server or a PC, and used from a web browser. If several people will use it, install it on a server so it's available whenever they need it.

Before you install

The computer

• A Windows server or PC joined to the domain you want to manage.
• You are signed in with an account that is a local administrator on that computer.
• Port 8083 reachable from the computers people will browse from. If you turn on HTTPS during setup, port 443 too.

The account AD Pro Toolkit uses for Active Directory

Choose one of these before you start. The setup wizard asks for it.

Option 1: A managed service account (recommended). A group managed service account (gMSA) or standalone managed service account (sMSA). Windows manages its password, so there is no password to type, store or rotate. The service runs as this account and connects to Active Directory as itself.

The account must be created and installed before you run the setup wizard. See Set up a managed service account.

Option 2: A normal domain account with a password. The service runs as Local System, and connects to Active Directory with a domain account you choose. The password is stored encrypted on the computer, and only that computer can decrypt it.

Permissions

AD Pro Toolkit reads and changes Active Directory using its service account (the account you choose in the setup wizard), not the account of the person using the app. The audit log under Settings > Logs records which person made each change.

Grant Replicating Directory Changes on a domain controller:

dsacls "DC=contoso,DC=com" /G "CONTOSO\ADToolkitSvc$:CA;Replicating Directory Changes"

A few reports, such as BitLocker and Deleted users, need extra read access. If the service account can't read something, the app says so.

Adding the service account to Domain Admins works but isn't recommended. Delegate only the permissions you need.

Step 1: Run the installer

1. Run the AD Pro Toolkit installer on the computer.
2. Follow the prompts.
3. When it finishes, the setup wizard opens.

Step 2: The setup wizard

The setup wizard has four steps. Nothing is changed until you select Finish setup on the last one, except the Active Directory connection, which is saved when you leave step 2.

Step 1 of 4: Choose the service account

Choose the account the AD Pro Toolkit Windows service runs as:

• Local System: the built-in Windows account. Choose this if you are using a normal domain account with a password (Option 2 above).
• Managed service account: enter the account, for example CONTOSO\ADToolkitSvc, and select Validate to check it is installed on this computer.

Step 2 of 4: Connect to Active Directory

1. Enter your Active Directory domain, for example ad.contoso.com.
2. Tick Connect over LDAPS (port 636) if your domain controllers require encrypted LDAP.
3. If the service runs as Local System, enter the Username and Password of the domain account AD Pro Toolkit should connect with, as DOMAIN\username or username@domain. With a managed service account there is nothing to enter; it connects as itself.
4. Select Test connection. The result appears under the button:
   • Connected and Sync permission OK (green): you're ready.
   • Missing the sync permission (amber): the account can connect, but doesn't have Replicating Directory Changes. A message shows the exact command to fix it. You can grant it now and test again, or continue and grant it later.
   • An error (red): the connection failed. See Troubleshooting.
5. Select Next. The connection is tested again and saved.

Step 3 of 4: Administrator access

Choose who can use AD Pro Toolkit and what they can do.

On a new install, you (the person running the setup wizard) are already listed as a Super admin. Super admins can do everything, including managing who has access. There must be at least one.

To add someone else:

1. Search by name or DOMAIN\username. You can add users or groups.
2. Choose a Role.
3. Select Add.

Adding a group is usually easier to manage: anyone you add to the group in Active Directory gets access, and anyone you remove loses it. Changes in group membership take effect the next time the person signs in to Windows.

You can add more people, and change roles, later under Settings > Access control in the app.

Step 4 of 4: Review & Finish

1. Check the summary.
2. Optionally tick Enable HTTPS. This creates a self-signed certificate on port 443 and trusts it on this computer. Browsers on other computers will warn about the certificate until it is trusted there too, for example by deploying it with Group Policy. You can also turn HTTPS on later, or use your own certificate, under Settings > SSL certificate in the app.
3. Select Finish setup.

The setup wizard then:

• turns on HTTPS, if you ticked it;
• gives the people you added access to the app;
• sets the service to run as the account you chose, gives that account what it needs to run the service, and restarts the service.

When it finishes, select Open AD Pro Toolkit.

Step 3: Open the app

• On the computer where it's installed: use the AD Pro Toolkit shortcut in the Start menu, or browse to http://localhost:8083.
• From another computer: browse to http://COMPUTERNAME:8083. With HTTPS on, use https://COMPUTERNAME.

AD Pro Toolkit uses Windows sign-in. On a domain-joined computer, people are signed in automatically with their Windows account. From a computer that isn't joined to the domain, the browser asks for a username and password: enter your domain account as DOMAIN\username. What people can do depends on the role you gave them.

If people will connect from computers that aren't joined to the domain, turn on HTTPS. Their sign-in is better protected over HTTPS than over plain HTTP.

The first sync of your directory starts as soon as the service restarts. Reports fill in as it runs. The sync status is shown in the title bar at the top of the app. After that, AD Pro Toolkit syncs every 30 minutes.

Run the setup wizard again

You can run the setup wizard again at any time, for example to change the service account or the Active Directory connection. Use the AD Pro Toolkit Setup shortcut in the Start menu.

It opens on your current settings. Things to know:

• The password is needed again. If the connection uses a username and password, you have to enter the password again on step 2, even if it hasn't changed.
• HTTPS is left alone. If HTTPS is already on, the box shows ticked and greyed out, and your certificate is kept. To change it, use Settings > SSL certificate in the app.
• Only the default domain. The setup wizard edits the default domain. Entering a different domain on step 2 adds it as a new domain and makes it the default. To manage several domains, use Settings > Connections in the app.
• People already listed keep their access. Adding the same person again does nothing.
• The app restarts. Finish setup restarts the service, so the app is unavailable for about a minute, and a sync in progress stops. It runs again at the next scheduled time.

Set up a managed service account

AD Pro Toolkit doesn't create the managed service account, so create it before you run the setup wizard. Replace ADToolkitSvc with the name you want, and HOSTNAME with the name of the computer AD Pro Toolkit is installed on.

1. Create the account. In PowerShell, on a computer with the Active Directory PowerShell module:

   New-ADServiceAccount -Name "ADToolkitSvc" -RestrictToSingleComputer
   

2. Allow the AD Pro Toolkit computer to use it:

   Add-ADComputerServiceAccount -Identity "HOSTNAME" -ServiceAccount "ADToolkitSvc"
   

3. On the AD Pro Toolkit computer, install the account:

   Install-ADServiceAccount -Identity "ADToolkitSvc"
   

4. On the same computer, test it. It should return True:

   Test-ADServiceAccount -Identity "ADToolkitSvc"
   

5. Grant the account the permissions it needs. See Permissions.

Then run the setup wizard. On Step 1 of 4, choose Managed service account and enter the account, for example CONTOSO\ADToolkitSvc. On step 2 there is no username or password to enter; the account connects as itself.

Troubleshooting

• "The username or password was rejected": check the account name and password. Use DOMAIN\username or username@domain.
• The connection fails or times out: the computer AD Pro Toolkit is installed on can't reach a domain controller. Check the domain name, and that port 389 (or 636 with LDAPS) is open from it to your domain controllers.
• "Missing the sync permission": grant Replicating Directory Changes as shown in Permissions, then select Test connection again.
• "exists but is not a managed service account on this machine": the managed service account isn't installed on this computer. Run Install-ADServiceAccount as shown in Set up a managed service account.
• The service doesn't start after Finish setup: usually the managed service account can't run on this computer. Check that Test-ADServiceAccount returns True, and that the computer is allowed to retrieve the account's password (the gMSA's PrincipalsAllowedToRetrieveManagedPassword).
• Other computers can't reach the app: open port 8083 (and 443 with HTTPS) in Windows Firewall on the computer AD Pro Toolkit is installed on.
• Asked to sign in on a domain-joined computer: the browser doesn't treat the app's address as internal. This is common when you use a full name or IP address, such as https://adpro.contoso.com or http://10.0.0.5:8083. Add the address to the Local intranet zone in Internet Options, or for everyone with Group Policy (Site to Zone Assignment List), and people are signed in automatically again.
• "Insufficient access rights" when using a tool: AD Pro Toolkit's service account doesn't have permission for that change on that OU. Grant it as described in Permissions. It doesn't matter whether the person using the app has the permission; only the service account's permissions count.
• People see a blank app or no menus: they have no role. Add them, or a group they're in, under Settings > Access control. A new group membership only counts after they sign out of Windows and back in.