LDAP Auth Module - Help

Prerequisites

If you want to connect to the directory service over SSL, import the trusted SSL certificate for your LDAPS server before you enable the authentication module. If there are any intermediate certificates that sit between the SSL certificate and the root CA certificate, you need to upload a file that contains the full certificate chain.

The option to import a trusted SSL certificate is not supported in the settings for the LDAP authentication module. Instead, you need to access the Trusted SSL Certificates page and import it there. For more information, see Trusted SSL Certificates.

Enable LDAP Authentication

To allow users stored in a directory service to log in to Hub, enable an LDAP authentication module.

To enable LDAP authentication:

In the Access Management section of the Administration menu, select Auth Modules.
From the Add Module drop-down list, select LDAP.
- The New Module dialog opens.

In the New Module dialog, enter values for the following settings:

Setting	Description
Name	Enter a name for the authentication module.
Server	Enter the server address of the directory service. For a connection over SSL, change the protocol part of the address to `ldaps`.
Port	Enter the number of the port used to communicate with the directory service. The default port for standard LDAP is `389`. The default port for LDAPS is `636`.
SSL	Enable this option to connect to the directory service over SSL. Before you can establish a secure connection, you need to import the trusted SSL certificate for your LDAPS server. For instructions, see Trusted SSL Certificates.
Search Base	Enter the domain components that define the top-level LDAP DN where user accounts are stored. For example, if your company uses the domain `mycompany.com`, enter the top-level LDAP DN `dc=mycompany,dc=com`. The value entered in this field is added to the LDAP URL and cannot contain unsafe characters. If you use organizational units to manage users, create separate auth modules for each organization. Include the organizational unit in the search base to create a unique LDAP URL for each module. LDAP authentication modules do not support recursive search in the LDAP tree.

Click the Create button.
- The LDAP authentication module is enabled. The current status of the module is displayed next to the name of the module in the header.
- The Auth Modules page displays the settings for the LDAP authentication module. The module is pre-configured with standard settings that are based on the information you provided in the Add Module dialog. For additional information about the settings on this page, see the Settings section.

Test the Connection to your Directory Service

To verify that the LDAP authentication module is connected to your directory service, test the connection.

To test the connection:

Click the Test Login button.
In the Test Authentication dialog, enter the credentials of a user who is stored in your directory service:
- In the Login field, enter the domainusername.
- In the Password field, enter the password.
Click the Test Login button.
- Hub searches for the specified user account in the directory service. If the user is found, a success notification is displayed. If you get an error, check your user credentials and server URL.

Settings

Use the following settings to fine-tune the connection to your directory service.

Field

Description

Type

Displays the type of directory service that is enabled for third-party authentication in Hub.

Name

Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list. The name is also shown in the list of supported authentication providers on the login form.

Server URL

Stores the LDAP URL of the directory service used to authenticate a login request in Hub.

The LDAP URL uses the format ldap://host:port/DN. Enter the full distinguished name (DN) of the directory where user accounts are stored.

SSL key

Selects an SSL key that can be used to verify the identity of your YouTrack installation to the LDAP service. You should only need to use this setting when your LDAP service requires client SSL authentication.

This list displays only keystores that have been imported into Hub. For more information, see SSL Keys.

Bind account

Determines which account is used for the LDAP bind request. For more information, see Bind Account Options.

Bind DN

Stores the value that is used to bind with the directory service. For more information, see Bind Account Options.

Filter

Stores an expression that locates the record for a specific user in the LDAP service. The substitution variable in the expression is replaced with the value entered as the username or email on the login page.

LDAP referral

Determines whether the LDAP authentication module ignores or follows requests from the service to locate additional information in the LDAP directory.

If your directory service stores attributes that are mapped to Hub profiles in different partitions, enable the Follow option.
When following redirects is not required for user authentication, enable the Ignore option to increase performance.

LDAP account status

Determines whether user accounts statuses are updated in Hub when an account with corresponding credentials is deleted from the connected directory service.

If the account was deleted in the directory service, the Hub account is banned and the corresponding credentials are removed from the Hub account.
The Hub account is not unbanned automatically when the account is restored in the connected directory service. The status must be updated manually in Hub.

The following options are available for this setting:

Option	Description
Ignore	The status of Hub accounts and accounts that are managed in the connected directory service are independent.
Forward	The status of an account in the connected directory service is forwarded to Hub on login or sync, when enabled.

This setting is only available when the Bind account setting for the authentication module is set to Fixed.

If the Synchronization setting is On, the account status is updated at the predefined interval. Otherwise, the account status is only synchronized when users attempt to use their LDAP account to log in to an application through Hub.

Synchronization

Determines the frequency with which user account credentials and group memberships are synchronized with the directory service. You can choose from one of three predefined intervals:

Daily at 9 AM
Every 3 hours
Hourly

You can also manually synchronize the Hub database with the directory service at any time by clicking the Synchronize now button.

When synchronization is Off, group memberships and account statuses are still synchronized on a per-user basis during login. To learn more about this feature, see Group Mappings.

The Synchronization option is only available when the Bind account setting is Fixed. This gives Hub the ability to search the directory service on behalf of bind account owner.

The synchronization feature is only active when the authentication module is Enabled.

Bind Account Options

You can configure the module to perform the bind request with the LDAP service in one of two ways. The method used is determined by the option selected for the Bind account setting.

The value that you use for the Bind DN setting depends on the option that you select for the Bind account setting. Use the following guidelines to set the value for the Bind DN setting:

Option	Description	Guideline for Bind DN Setting
Fixed	Uses a fixed account to bind to the LDAP service and searches for the user you want to authenticate on behalf of the bind user. With this option, you can set up an LDAP authentication module and still use logins that are not part of the Distinguished Name (DN), like an email address or token. This method is also commonly called search + bind or two-step authentication. To use this method, you need a special account on the directory server that has permission to look up other user accounts in the directory service.	Enter the full DN of the user account that you want to use for the LDAP bind request. This account must have permission to look up other user accounts in the directory service. Use the Change password control to store the password for this account in Hub. The password for the bind user is stored as a salted hash of the plain-text value.
Dynamic	Derives the user DN from the login and attempts to bind to the LDAP service as the user directly. This method is also commonly called direct bind.	Use a query to bind with the directory service. This query looks up the distinguished name of the user to be authenticated. Reference the username with an expression. The expression maps a substitution variable to the attribute that stores the username in the directory service. The attribute you select determines which query is used in the filter string. The value entered as the username on the login page is trimmed before it replaces the substitution variable. If the user specifies a domain, it is discarded. For example, a username with the value `WORKGROUP\smith` is trimmed to `smith`. To specify a domain, enter the domain name as a static value. For example, `WORKGROUP\%u`.

Option

Description

Guideline for Bind DN Setting

Fixed

Uses a fixed account to bind to the LDAP service and searches for the user you want to authenticate on behalf of the bind user. With this option, you can set up an LDAP authentication module and still use logins that are not part of the Distinguished Name (DN), like an email address or token. This method is also commonly called search + bind or two-step authentication.

To use this method, you need a special account on the directory server that has permission to look up other user accounts in the directory service.

Enter the full DN of the user account that you want to use for the LDAP bind request. This account must have permission to look up other user accounts in the directory service.

Use the Change password control to store the password for this account in Hub. The password for the bind user is stored as a salted hash of the plain-text value.

Dynamic

Derives the user DN from the login and attempts to bind to the LDAP service as the user directly. This method is also commonly called direct bind.

Use a query to bind with the directory service. This query looks up the distinguished name of the user to be authenticated. Reference the username with an expression. The expression maps a substitution variable to the attribute that stores the username in the directory service. The attribute you select determines which query is used in the filter string.

The value entered as the username on the login page is trimmed before it replaces the substitution variable. If the user specifies a domain, it is discarded. For example, a username with the value WORKGROUP\smith is trimmed to smith. To specify a domain, enter the domain name as a static value. For example, WORKGROUP\%u.

Attribute Mapping

When Hub finds a record in the LDAP service that matches a filter, it fetches values from the LDAP attributes that are specified for each field and copies them to the user profile in Hub. Use the following settings to define the filter criteria and map attributes that are stored in your directory service to user accounts in Hub.

Field	Description
Login	Required. Maps to the LDAP attribute that stores the value to copy to the Login field in the Hub profile. For LDAP, the default value is `uid`. We urge you not to change the default values unless it is strictly required. If you do change the default value, the field must specify an attribute of the LDAP record that uniquely identifies a user account. Also, if the default value is changed, on the first next attempt to log in with the LDAP credentials, a new credentials record may be added to the Logins section of the user profile.
Full name	Maps to the LDAP attribute that stores the value to copy to the Full name field in the Hub profile.
Email	Maps to the LDAP attribute that stores the value to copy to the Email field in the Hub profile.
Jabber	Maps to the LDAP attribute that stores the value to copy to the Jabber field in the Hub profile.
VCS user name	Maps to the LDAP attribute that stores the value to copy to the VCS user name field in the Hub profile.

Additional Settings

The following options are located at the bottom of the page. Use these settings to manage Hub account creation, group membership, and connection options.

Option	Description
User creation	Enables creation of Hub accounts for unregistered users who log in with an account that is stored in the connected directory service. Hub uses the email address to determine whether the user has an existing account. All LDAP authentication modules must allow user creation. If user creation is denied, unregistered users are shown an error.
Auto-join groups	Adds users to a group when they log in with an account that is stored in the connected directory service. You can select one or more groups. New users that auto-join a group inherit all of the permissions assigned to this group. We recommend that you add users to at least one group. Otherwise, a new user is only granted the permissions that are currently assigned to the All Users group.
Connection timeout	Sets the period of time to wait to establish a connection to the authorization service. The default setting is 5000 milliseconds (5 seconds).
Read timeout	Sets the period of time to wait to read and retrieve user profile data from the authorization service. The default setting is 5000 milliseconds (5 seconds).
Audit	Links to the Audit Events page in Hub. There, you can view a list of changes that were applied to this authentication module.

Group Mappings

On the Group Mappings tab, you can map existing groups in the LDAP service to the groups in Hub.

If you want to map LDAP groups to Hub groups, you need to specify the Groups attribute that stores LDAP group memberships in the Attribute Mapping section of the settings for this auth module.

When group mappings are configured, Hub checks for LDAP group memberships when users log in with accounts that are managed in the directory service. Hub performs the following operations for each LDAP group that is mapped to a Hub group:

Users who are members of a mapped LDAP group and are not members of the mapped Hub group are added to the group in Hub.
Users who are not members of a mapped LDAP group and are members of the mapped Hub group are removed from the group in Hub.

This behavior is based on the current value for the Synchronization setting.

When the Synchronization setting is On, these operations are performed on a set schedule.
When Off changes to group memberships in the directory service are only applied in Hub when users log in using the LDAP auth module.

Scheduled synchronization is only available when the Bind account option is Fixed. If the Bind account option is Dynamic, group memberships are synchronized only on user login.

You can map multiple LDAP groups to a single target group in Hub. You can't map LDAP groups to more than one Hub group.

To map an LDAP group to a group in Hub:

Open your LDAP auth module.
Select the Group Mappings tab.
Click the Add mapping button.
- The Add Mapping dialog opens.
Enter the name of the LDAP group in the LDAP group name field.
- If the Bind account option is set to Fixed, the auth module uses the bind account look up groups in the directory service. Available groups are shown in the LDAP group name list.
- If the Bind account option is set to Dynamic, the list of groups in the directory service is not available to the bind account. To map a group successfully, you need to enter the name of the group exactly as it appears in the directory service.
Select a group from the Hub group list.
Click the Add button.
- The mapping is added to the list.

Sample Configurations

Use the following patterns to configure an LDAP auth module using the LDAP protocol:

Setting	Value
Server URL	`ldap://ldap.company.com:389/dc=company,dc=com`
Bind DN	`uid=%u,ou=People`
Filter	`uid=%u`

Use the following patterns to configure an LDAP auth module with a secure connection over SSL:

Setting	Value
Server URL	`ldaps://ldap.company.com:636/dc=company,dc=com`
Bind DN	`uid=%u,ou=People`
Filter	`uid=%u`

Troubleshooting

If you encounter problems with this authentication module, see if any of the following conditions apply.

Condition	Group memberships are not properly synchronized with the directory service or synchronization is applied inconsistently.
Cause	The Hub user account stores credentials for multiple accounts that are managed in the directory service. The accounts in the linked directory service belong to different sets of groups. If a Hub user has multiple accounts that are managed in the linked directory service, group membership synchronization may behave unpredictably. The synchronization job will apply membership assignments for the first account it finds, then update these assignments if it encounters different group assignments for subsequent accounts.
Solution	You can resolve this problem by applying any one of the following solutions: Delete any unused or unnecessary accounts in the linked directory service, then use the Synchronize now option in Hub. This removes unnecessary credentials from the Hub profile and syncs the account memberships with the single remaining directory service account. This is the recommended solution for this case. Turn the synchronization setting off and remove unnecessary credentials in the Hub account. You can remove the credentials manually through the user interface or using the REST API. Delete all of the logins from the linked directory service from the Hub account. If the email address for the linked account matches the email in Hub, the credentials for the active account will be restored the next time the user attempts to use this account to log in. The group membership assignments will be synchronized automatically.

Condition

Group memberships are not properly synchronized with the directory service or synchronization is applied inconsistently.

Cause

The Hub user account stores credentials for multiple accounts that are managed in the directory service. The accounts in the linked directory service belong to different sets of groups.

If a Hub user has multiple accounts that are managed in the linked directory service, group membership synchronization may behave unpredictably. The synchronization job will apply membership assignments for the first account it finds, then update these assignments if it encounters different group assignments for subsequent accounts.

Solution

You can resolve this problem by applying any one of the following solutions:

Delete any unused or unnecessary accounts in the linked directory service, then use the Synchronize now option in Hub. This removes unnecessary credentials from the Hub profile and syncs the account memberships with the single remaining directory service account.

This is the recommended solution for this case.
Turn the synchronization setting off and remove unnecessary credentials in the Hub account. You can remove the credentials manually through the user interface or using the REST API.
Delete all of the logins from the linked directory service from the Hub account. If the email address for the linked account matches the email in Hub, the credentials for the active account will be restored the next time the user attempts to use this account to log in. The group membership assignments will be synchronized automatically.