This guide shows how to connect upKeeper Manager to Microsoft Active Directory (AD), how to fill in the Active Directory Groups and Active Directory Users settings, and what to expect after you save.
In short: enter an account that can read your directory, your domain name and a root node. Save. upKeeper Application Server then synchronizes groups and users within 15 minutes and repeats that every 15 minutes.
Before you start
You need:
- A service account in Active Directory. A normal domain user with read access is enough. It does not need administrator rights. Use an account with a password that does not expire, so the integration does not stop working later.
- Network access from upKeeper Application Server to a domain controller:
- Port 636 (LDAP over SSL, LDAPS), preferred
- Port 389 (LDAP), used if LDAPS is not available
- The DNS name of your domain, for example
upkeeperdev.local.
Tip: Use LDAPS if you can. upKeeper Application Server always tries a secure LDAPS connection first and only falls back to plain LDAP if that fails. For LDAPS, the domain controller needs a valid certificate that the application server trusts.
Active Directory Groups
Open Integration > Active Directory Groups.
| Field | What to enter | Example |
|---|---|---|
| Username | The service account. Both formats work: DOMAIN\user or user@domain. | upkeeperdev\DomainReader or DomainReader@upkeeperdev.local |
| Change password? | Tick this box to enter or replace the password. Leave it unticked to keep the saved password. | |
| Password | The password of the service account. The field is locked until you tick Change password?. | |
| Domain | The DNS name of the domain. | upkeeperdev.local |
| Root node | Where in the directory the search starts. Everything below this point is searched. | LDAP://DC=upkeeperdev,DC=local |
Click Save when you are done.
Only Distribution Groups will be returned and next step is to select which group/groups should be visible in Groups and updated with computer members.
Active Directory Users
Open Integration > Active Directory Users.
The first five fields work exactly as for groups. You can use the same service account, but Groups and Users are saved separately, so enter the values on both pages.
| Field | What to enter | Example |
|---|---|---|
| Username | The service account. | upkeeperdev\DomainReader |
| Change password? | Tick to enter or replace the password. | |
| Password | The password of the service account. | |
| Domain | The DNS name of the domain. | upkeeperdev.local |
| Root node | Where in the directory the search starts. | LDAP://DC=upkeeperdev,DC=local |
| Include Groups | Optional. Only users who are members of these groups are imported. Separate groups with a semicolon. | Employees;Consultants |
| Exclude Groups | Optional. Users who are members of these groups are not imported. Separate groups with a semicolon. | Service Accounts;Disabled Users |
Leave Include Groups and Exclude Groups empty if you do not want to filter. Do not type "none".
Click Save when you are done.
Root node
The root node decides which part of the directory is searched.
| You want to search | Root node |
|---|---|
| The whole domain | LDAP://DC=upkeeperdev,DC=local |
| One organizational unit (OU) | LDAP://OU=Staff,DC=upkeeperdev,DC=local |
| A nested OU | LDAP://OU=Sales,OU=Staff,DC=upkeeperdev,DC=local |
Rules:
- Write the path without spaces after the commas:
DC=upkeeperdev,DC=local, notDC=upkeeperdev, DC=local. - Start with the most specific part (the OU) and end with the domain parts (
DC=...). - The Groups and Users pages have separate root nodes. You can search different parts of the directory for groups and for users.
- A plain distinguished name without
LDAP://, or the name of an OU, can also be used.
Include Groups and Exclude Groups
These fields filter which users are imported.
- Separate group names with a semicolon (
;). Do not use commas. Commas can be part of a group name. - Use the group name (the name shown in Active Directory), not the full distinguished name.
- Names are not case sensitive.
- A user counts as a member of a group both through normal membership and through the user's primary group.
- Exclude wins. A user who is a member of an excluded group is never imported, even if the user is also a member of an included group.
- If Include Groups is empty, all users below the root node are considered. If it contains groups, only members of those groups are imported.
Example:
| Include Groups | Exclude Groups | Result |
|---|---|---|
| (empty) | (empty) | All users below the root node |
Employees | (empty) | Only members of Employees |
Employees;Consultants | Service Accounts | Members of Employees or Consultants, except members of Service Accounts |
What to expect after you save
- Synchronization starts within 15 minutes. upKeeper Application Server fetches groups and users and then repeats this every 15 minutes. Changes you make in Active Directory therefore show up in upKeeper Manager within about 15 minutes.
- No restart or manual action is needed.
- Users are imported with these properties: user name, display name, e-mail, telephone number, manager and distinguished name.
- Users without a display name are not imported. If a user is missing after synchronization, check that the Display name attribute is set in Active Directory.
- If you change a setting later, save it and wait up to 15 minutes for the next synchronization.
Test the settings before you save (optional)
Wrong settings are easiest to find before they are saved. Use the PowerShell script Test-UpkeeperAdIntegration.ps1. It uses the same logic and the same field names as upKeeper Manager, and it prints the values to copy into the forms when the test succeeds.
Run it from a computer that has the same network access to the domain controller as the application server, ideally the application server itself.
Test groups:
.\Test-UpkeeperAdIntegration.ps1 -Username "upkeeperdev\DomainReader" -Domain "upkeeperdev.local" -Mode Groups -RootNode "LDAP://DC=upkeeperdev,DC=local"
Test users:
.\Test-UpkeeperAdIntegration.ps1 -Username "upkeeperdev\DomainReader" -Domain "upkeeperdev.local" -Mode Users -RootNode "LDAP://DC=upkeeperdev,DC=local" -IncludeGroups "Employees;Consultants" -ExcludeGroups "Service Accounts"
The script asks for the password. It then shows:
- Whether LDAPS and LDAP work
- Whether the account and password are correct
- The number of groups and users found, and how many users were skipped and why
- Warnings for group names that do not exist
- A block of values for each form, ready to copy
The password is masked in the output. Add -ShowPassword if you need to copy it. The script only reads from Active Directory and never changes anything. A log file is saved next to the script.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| No groups or users appear after 15 minutes | Wrong password, wrong username format or no connection to the domain controller | Run the test script and check the result. |
| Login fails | Wrong password, locked or expired account | Reset the password, tick Change password?, enter it again and save. |
| Cannot connect | DNS, firewall or the domain controller is down | Check that the application server can reach the domain controller on port 636 or 389. |
| LDAPS fails but LDAP works | Missing or untrusted certificate on the domain controller | Install a valid certificate on the domain controller, or accept plain LDAP. |
| The result is empty | Root node points to the wrong place, or the Include Groups filter is too narrow | Check the root node and the include groups. |
| A specific user is missing | The user has no display name, is a member of an excluded group, or is outside the root node | Check display name, group memberships and the OU of the user. |
| A group filter does not work | Spelling error, commas instead of semicolons, or a full path instead of the group name | Use the group name only and separate with semicolons. |
| The root node is rejected or returns nothing | Spaces after the commas, or an OU that does not exist | Check the spelling and remove spaces. |
Good to know
- Use a dedicated service account for the integration, not a personal account.
- Keep the same account on both pages so there is one account to manage.
- Do not change the password of the service account in Active Directory without also updating it in upKeeper Manager (tick Change password?).
- Limit the root node and use Include Groups if you only need part of your organization. This makes synchronization faster.
If you still need help, contact upKeeper support and include the log file from the test script.
Comments
0 comments
Please sign in to leave a comment.