Quick Active Directory and OpenLDAP User Guide

Version from 18:07, 25 Oct 2018

(Versions 7+)

Introduction

This guide describes how to use Active Directory or OpenLDAP with Password Server.

In this guide, we assume a scenario where Mr. Smith is an admin who has a directory server with srv.mydomain as its domain, two groups (Finance and HR), and two users (sbrown, in Finance, and rlee in HR).

Related Topics:

• Directory Connection - Setup Overview
• Directory Settings for performance
• Use an Advanced User Filter
• Troubleshooting

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 "Microsft 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: The host name or address of the directory server. This may be a specific machine name or IP or a DNS entry that resolves to directory server. 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.
• 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.

Using Multiple Domains and AD Forests

Larger organisations may use multiple domains and forests, which is possible to setup with the Password Server. There are a couple different options to handle this scenario:

• Option A) 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.
• Option B) 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.

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

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 path from which to import users and groups.

• 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 most directory connections, especially a large or spread out directory, it's recommended to add all users to one Security Group and use an Additional User Filter (see below: Recommended User Filter).

For many directory connections 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"

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"

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.

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 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 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

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.

Import Settings

Enter Credentials: For the import pages, various username formats are accepted, including UPN format (username@domain). Including the domainmay 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

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 Distinguished Name (Versions 7.3.7 & Earlier)

(No longer necessary in Versions 7.4.0+)

Changes to your AD/LDAP structure may cause Users and Roles in Password Server to become desynced 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 desynced. 

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 desynced and click Actions > Set Distinguished Name

Update the Role's Distinguished Name to match your AD/LDAP, then click Save.

Version as of 03:02, 19 Jan 2019

(Versions 7+)

Introduction

This guide describes how to use Active Directory or OpenLDAP with Password Server.

In this guide, we assume a scenario where Mr. Smith is an admin who has a directory server with srv.mydomain as its domain, two groups (Finance and HR), and two users (sbrown, in Finance, and rlee in HR).

Related Topics:

• Directory Connection - Setup Overview
• Directory Settings for performance
• Use an Advanced User Filter
• Troubleshooting

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 "Microsft 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: The host name or address of the directory server. This may be a specific machine name or IP or a DNS entry that resolves to directory server. 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.
• 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.

Using Multiple Domains and AD Forests

Larger organisations may use multiple domains and forests, which is possible to setup with the Password Server. There are a couple different options to handle this scenario:

• Option A) 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.
• Option B) 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.

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 most directory connections, especially a large or spread out directory, it's recommended to add all users to one Security Group and use an Additional User Filter (see below: Recommended User Filter).

For many directory connections 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"

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"

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.

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 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 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

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.

Import Settings

Enter Credentials: For the import pages, various username formats are accepted, including UPN format (username@domain). Including the domainmay 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

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 Distinguished Name (Versions 7.3.7 & Earlier)

(No longer necessary in Versions 7.4.0+)

Changes to your AD/LDAP structure may cause Users and Roles in Password Server to become desynced 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 desynced. 

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 desynced and click Actions > Set Distinguished Name

Update the Role's Distinguished Name to match your AD/LDAP, then click Save.