An LDAP authentication module lets users log in to YouTrack and any connected services with credentials that are stored in a directory service.
YouTrack provides pre-configured authentication modules for LDAP, OpenLDAP, and Active Directory.
You can configure a module to use the standard LDAP scheme or LDAPS over SSL.
The LDAP authentication module does not import all of the user accounts from the directory service.
YouTrack only creates a user account when an unregistered user first logs in to YouTrack or a connected service.
When LDAP authentication is enabled, YouTrack checks the directory service for each login attempt.
Users who have been removed from the directory service cannot log in to YouTrack.
Prerequisites
If you want to authenticate over SSL, import the trusted SSL certificate and key store before you enable the authentication module.
For more information, see SSL Certificates.
Enable LDAP Authentication
To allow users stored in a directory service to log in to YouTrack, 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 the option that corresponds to the directory service you want to enable.
You can select LDAP, OpenLDAP, or Active Directory.
The Add Module dialog opens.
In the Add Module dialog, enter values for the following settings:
Field
Description
Name
Enter a name for the authentication module.
Server
Enter the server address of the directory service.
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
Select this option to authenticate over SSL.
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 Module button.
The LDAP authentication module is enabled.
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 Settings.
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.
YouTrack 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 configure how YouTrack connects to your directory service.
Field
Description
Type
Displays the type of directory service that is enabled for third-party authentication in YouTrack.
Name
Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules
in the Auth Modules list.
Authentication
Displays the current status of the module. This status indicates whether the module is currently enabled or disabled.
Server URL
Stores the LDAP URL of the directory service used to authenticate a login request in YouTrack.
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 store
Selects the key store that contains the private key for your YouTrack server.
Use this setting when your LDAP service requires a trusted certificate to establish a connection to another service.
This list displays only key stores that have been imported into YouTrack. For more information, see SSL Keystores.
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.
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 Set password control to store the password for this account in YouTrack.
The password for the bind user is stored as a 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 YouTrack 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 corresponding Hub profile.
Use the following settings to define the filter criteria and map attributes that are stored in your directory service to user accounts in YouTrack.
Field
Description
Full name
Maps to the LDAP attribute that stores the value to copy to the Full name field in the Hub profile.
Login
Maps to the LDAP attribute that stores the value to copy to the Login 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.
User Management Options
The following options are located at the bottom of the page.
Use these settings to manage account creation and group membership.
Option
Description
User creation
Enables creation of YouTrack accounts for unregistered users who log in with an account that is stored in
the connected directory service.
YouTrack 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 Settings
The settings in this section of the page let you reduce the loss of processing resources consumed by idle connections.
Setting
Description
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).
Sample Configurations
Service Type
Setting
Value
LDAP
Server URL
ldap://ldap.company.com:389/dc=company,dc=com
SSK key store
No
Bind DN
uid=%u,ou=People
Filter
uid=%u
LDAP over SSL
Server URL
ldaps://ldap.company.com:636/dc=company,dc=com
SSK key store
LDAP SSL
Bind DN
uid=%u,ou=People
Filter
uid=%u
OpenLDAP
Server URL
ldap://ldap.company.com:389/dc=company,dc=com
SSK key store
No
Bind DN
uid=%u,dc=company,dc=com
Filter
uid=%u
OpenLDAP over SSL
Server URL
ldaps://ldap.company.com:636/dc=company,dc=com
SSK key store
LDAP SSL
Bind DN
uid=%u,dc=company,dc=com
Filter
uid=%u
Active Directory
Server URL
ldap://ldap.company.com:389/dc=company,dc=com*
SSK key store
No
Bind DN
%u@company.com
Filter
sAMAccountName=%u
Active Directory over SSL
Server URL
ldaps://ldap.company.com:636/dc=company,dc=com*
SSK key store
Active Directory SSL
Bind DN
%u@company.com
Filter
sAMAccountName=%u
* replace
company.com
with the domain name of the Active Directory.
