Quick Connect to Active Directory / LDAP
Use KeePass with Pleasant Password Server
This guide describes creating an integrated connection to Active Directory or OpenLDAP from Password Server. Users and Groups can be imported and synchronized to be used in the Password Server application.
Applies to: Versions 7+
-
Have Questions? Contact Us!
Sections:
- Adding a User Directory
- Advanced Settings
- Importing Groups & Users
- Automatic Directory Synchronization
- User Login
- Username Formats
Related Topics:
- Directory Connection - Setup Overview
- Directory Settings for performance
- Use an Advanced User Filter
- Troubleshooting
Navigate to:
- Users and Roles > Active Directory / LDAP
Adding a User Directory
The first step is to add a User Directory entry in:
-
Users & Roles > Manage Directories
On this page, you can create a new entry by pressing:
- Add New ActiveDirectory button - to connect to an Active Directory server
-
Add New LDAP Directory button - to connect to an OpenLDAP or similar LDAP directory server.
A directory page will open with some default values initialized which will be appropriate for the type of directory you selected. These should be reviewed to ensure that they are appropriate for your situation and may be edited later if changes are required.
Most fields will display a pop-up help item when you either select the text field or mouse over the "?" icon.
Edit Directory
Name: This is a name for the directory which will be used elsewhere in Password Server to refer to this directory connection.
Connection
Authentication Type: The authentication method used when connecting to the directory server.
- Typically select "Microsoft Negotiate"
- Active Directory typically uses Microsoft Negotiate.
- Kerberos:
- Recommendation: it is recommended to select the "Microsoft Negotiate" instead of the Kerberos option. This will automatically prefer the Kerberos protocol (ahead of NTLM, etc.), if it is available.
- However, if selecting the Kerberos authentication option, you can allow login using a UPN format (User Principle Name, e.g. username@alias)
- set the "Alias" field (mentioned below) to be the same as your domain (i. e. username@alias = username@domain).
-
Other LDAP servers may use Kerberos or Basic, depending on configuration.
Alias: The directory identifying portion of a fully-qualified username (user@alias). This is used to resolve conflicts with local users or users from multiple directories.
- Using Kerberos authentication method will also use the alias to create fully qualified names for Kerberos authentication (see notes above).
- For example, to differentiate from the following 2 users:
- a user named "sbrown" created locally
- a user named "sbrown" imported from directory with an alias "mydomain"
-
The username "sbrown@mydomain" will properly refer to the imported sbrown user.
Host: Enter the domain of the AD/LDAP. This can be an IP address or a hostname or a DNS entry that resolves to directory server(s), and could also be a specific machine name (which is less preferred). This value is used to connect to the directory service.
-
By specifying the domain of your directory, instead of the address of a single DC (Domain Controller), will allow the connection to failover if the DC is busy or unavailable. LDAP/AD will resolve and load balance to the appropriate connection.
Port: The port number to use when connecting to the directory server.
- Port 389 is commonly used, or port 636 for TLS/SSL connections.
- Hosing AD on Azure only supports port 636 (LDAPS)
- Use Port 3268, or 3269 for TLS/SSL, when querying acrosss subdomains and ensure that the Global Catalog is on each Domain Controller
Use SSL: Connecting using TLS/SSL requires a valid TLS/SSL certificate.
- Note: some may have trouble using this setting with Kerberos (e.g. clicking Updating User & Roles). More info: see details for "Authentication Type" field.
Directory Credentials
Select a credential to use when connecting to the directory server for administrative operations by:
A) using system or anonymous credentials, or
B) by specifying credentials and entering an admin User Name and Password
Use the web server's credentials:
-
Connect to the directory as the user that the web server is configured to run as. This may require configuring the web server or website application pool to run as a directory user rather than a local user.
Use the following credentials:
- If entering a User Name & Password, ensure that your channel to your directory server is secure
- The format of User Name varies depending on server and authentication type and may be:
- username
- domain\username
- Distinguished Name
Note: Pleasant Password Server does not currently support logging in with a User Principal Name (UPN). Until it
does, use a sAMAccountName instead.
Import
All users and roles can be granted access to Password Server by adding them as members to a Security Group (recommended) and filtering on group membership. However, this is not necessary using the basic directory settings.
Auto Import: When this is checked, a user will be auto-imported into the system when they first login. Enabling this option requires that the Password Server connect to the directory server to search for users.
The system will look for users from the following directory locations:
- User Relative DN,
- Base Distinguished Name,
-
Directory root
Allow Password Changes (Enterprise+): Setting this will enable the setting of user passwords in the connected directory. This setting requires that Admin User Name and Admin Password specify a user that has permission to set passwords to work correctly.
Base Distinguished Name: This field is used as the base path from which to import users and groups. We then recommend to filter on group membership.
-
For example, Mr. Smith might type in "OU=MainBranch,DC=srv,DC=mydomain" to import users from that particular path.
If the path is left empty, the root naming context for the directory will be used.
Advanced Settings
For testing or for smaller and more basic directory structures (which have users and groups in one location), it may not be necessary to use the advanced options, and to:
However, once a connection with the directory is established, it is usually recommended for performance and ease-of-use, to use the advanced settings.
Here are the options listed below...
Connecting with Basic Directory Structures
- A) Just connect to the directory
- B) Add a Base Distinguish Name
- C) Setup multiple directory connections, to different locations
Connecting with Advanced Directory Structures
- D) Recommended: Use a Group Membership Filter
- E) Use Relative DN fields
Settings
Adding values in User Relative DN and Group Relative DN will help, and will narrow the scope of the active directory.
User Relative DN: This field is used with the Base Distinguished Name to specify the path from which to import users.
- For example, if your Base Distinguished Name is "OU=MainBranch,DC=srv,DC=mydomain", then:
- User Relative DN is "CN=Users"
- the search query will find this:
- "CN=Users,OU=MainBranch,DC=srv,DC=mydomain"
- the search query will find this:
Group Relative DN: This field is used with the Base Distinguished Name to specify the path from which to import groups. For example, if your Base Distinguished Name is "OU=MainBranch,DC=srv,DC=mydomain" then:
- Group Relative DN is "CN=Groups"
- the search query will find this:
-
"CN=Groups,OU=MainBranch,DC=srv,DC=mydomain"
-
- the search query will find this:
Also Assign Roles from User's Nest Groups (v7.4.0+): Enabled by default. When enabled, users will inherit membership in AD/LDAP groups that have been imported as Roles in the same manner that membership is inherited in the directory.
- In LDAP structures that are highly nested, leaving this option enabled in can result in performance issues when interacting with the LDAP server.
-
Active Directory uses a different method to resolve Nested Group membership so its performance is not affected.
Connecting with Multiple Domains and AD Forests
Password Server is capable of connecting with with multiple domains and forests and following are some options.
- Option A: Use a security group membership filter
- This is our default recommendation for most Password Server implementations, and allows your users and roles to be administered from one location even if they are spread out in various locations.
- Option B: Setup multiple User Directories
- When the directory is unable to query across all domains / forest, or if the login/import search performance is slow. This could happen if for example there are multiple subdomains with users spread across each.
- As an example, when you are importing users with 'Get User List', perhaps you could pull user@domain1, but the forest trust relationship may not allow pulling user@domain2.
- In this case, specify the domain when importing users.
- When the directory is unable to query across all domains / forest, or if the login/import search performance is slow. This could happen if for example there are multiple subdomains with users spread across each.
- Option C: Use an alternate port
- Mentioned above (3268, or 3269 for TLS/SSL) - when querying subdomains, with setup as mentioned. Double-check the login/import search performance.
Search Filters
Help to narrow down the scope of the directory search for Users or Groups and may provide better manageability and performance.
-
See a list of Directory Search Filters
Recommended User/Role Filter
- In your LDAP/AD directory, add a new Security Group (e.g. "PPassUsers"), and add each Password Server user as a member of this new group.
- View the Distinguished Name of this group
- Add an Additional User/Role Filter, for example:
- Group Membership:
- memberOf is CN=PPassUsers,OU=MainBranch,DC=srv,DC=mydomain
- Nested Group Membership:
-
memberOf:1.2.840.113556.1.4.1941 is CN=PPassUsers,OU=MainBranch,DC=srv,DC=mydomain
-
- Group Membership:
For more details: see AD User Filter for Group Membership
Importing Groups & Users
First import your Groups, which will create the Groups from your directory as "Roles".
Then as your users are imported, the application will automatically assign the Roles to match the assignments in the directory. However, note that it is not necessary to do in this order.
Importing Groups
Groups can be imported by:
- Navigating to Users & Roles -> Manage Directories tab -> Select Import Roles from the Actions menu on the directory.
Importing Users
Users can be imported by:
-
Navigating to Users & Roles -> Manage Directories -> Select Import Users from the Actions menu on the directory
You may then need to enter credentials to connect to the directory server with, unless default credentials were entered during directory setup.
Note: Active Directory searches return a maximum of 1000 objects (i.e. users or groups). Either filter your
Directory connection or your Search Filters to return fewer than 1000 results, or use Ntdsutil.exe to configure a larger MaxPageSize.
Import Settings
Enter Credentials: For the import pages, various username formats are accepted, including UPN format (username@domain). Including the domain may be necessary for directories with multiple domains / forest. For more specific info, see the troubleshooting page: Unable to Bind.
Change Filters & Directory Settings: By default, the list will be filtered based on the Directory settings specified under "Adding a User Directory", and selecting Change Filters will allow the custom search options to narrow down the scope of the items in this list.
Get Groups List: Pressing this button will attempt to query and show a list of groups which are available for import.
- Mark a checkbox beside each groups to import and press Import Selected Groups button. If the groups were successfully imported, you will be able to see them by clicking the Users & Roles -> Roles tab.
-
For example, Mr. Smith might see "Finance" and "HR" in the table and import both of them. He should then be able to see that these two Groups are imported as Roles.
Get Users List: Pressing this button will attempt to query and show a list of users which are available for import.
- Mark a checkbox beside each groups to import and press Import Selected Users button.
- If the users were successfully imported, you will be able to see the users by clicking the Users & Roles > Users tab.
- If "Assign Roles from User's Nested Groups" s enabled for this directory, the users will be added to Roles similarly to their directory groups.
-
For example, Mr. Smith might see "sbrown" and "rlee" in the table, and decide to import only "sbrown". Since "sbrown" belongs to the "Finance" group, "sbrown" will automatically be granted the "Finance" role.
Troubleshooting:
If you are having trouble with Bind errors, the Search Results are empty, or have other Errors:
-
Please see Import Users / Groups are missing
Automatic Directory Synchronization
Configure Password Server to synchronize to the User Directory from:
- Directories > Click Actions button beside the directory link > Select Automatic Directory Sync
Sync Schedule:
-
When Password Server users / roles will be synchronized with Directory user / role information
- The recommended frequency for which you should set you automatic sync depends largely on how often you are making changes to your AD structure. You should be able to sync at least once per day (outside of business hours) without seeing substantial performance delays.
Health Check Schedule:
-
When Password Server will test the Directory Connection
Send Email Alert on Failure:
- Send an email when an error occurs in the directory sync connection
Recipient Roles / Users:
-
Enter the recipients of this Email Failure Alert
Directory synchronization also happens at other times: for example, at user login and when admins perform manual updates. For more information continue to the section below.
User Login
Various User Name formats are accepted at login. See the possible Username Formats below.
Auto-Import users: must first login using the Web application.
For multiple users with same usernames: the user will need to qualify their username with the Alias specified in directory settings, as otherwise it may be ambiguous which user is being referenced.
- For example, sbrown, who was imported in the previous section, can log in as "sbrown@mydomain".
Synchronization
Group membership and other directory fields will by synchronized when:
- The user is created
- Each time the user logs in
-
Upgrade of the software
Manual synchronization: can be triggered for all directory users by an Administrator, from Manage Users & Roles, either:
- Manage Directories tab > Select the Update Users action, or
- Manage Users tab > Select a specific user > Click Update User from Directory action
Username Formats
Various username formats are accepted at login. Note that the import page also accepts UPN format.
- Login page or Auto-Import:
- username - sAMAccountname format
- domain\username
-
username@alias - using the Directory Alias, from the Directory settings page
- Directory Settings & Import Users (only):
- username - sAMAccountname format
- domain\username
- username@alias - using the Directory Alias, from the Directory settings page
- username@domain - UPN format
Note: Pleasant Password Server does not currently support logging in with a User Principal Name (UPN).
Until it does, use:
- sAMAccountName instead (username, domain\username).
- Set the "Alias" field in your Directory settings to be the same as your domain, for example:
- username@alias = username@domain
Editing Email Attribute Mapping
In your AD Directory connection settings in Password Server, you can change which AD attribute maps to the user's email.
- So that once the users are imported, you will notice they will have the email address from this custom field you have defined.
Editing Distinguished Name
(No longer possible in Versions 7.4.0+)
Changes to your AD/LDAP structure may cause Users and Roles in Password Server to become un-synced from their AD/LDAP counterparts.
To correct this issue for a User, go to Users & Roles > Manage Users and click on the [Edit] link next to the name of the user that has become un-synced.
Update the User's Distinguished Name to match your AD/LDAP, then click Save.
To correct this issue for a Role, go to Users & Roles > Manage Roles, find the Role that has become un-synced and click Actions > Set Distinguished Name
Update the Role's Distinguished Name to match your AD/LDAP, then click Save.