Active Directory Auth Module
An Active Directory authentication module lets users log in to YouTrack with credentials that are stored in a directory service. This authentication module is pre-configured for Microsoft Active Directory. You can configure a module to use the standard LDAP scheme or LDAPS over SSL.
The Active Directory 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.
When Active Directory authentication is enabled, YouTrack checks the directory service for each login attempt. Users who have been removed from the directory service cannot log in.
Prerequisites
If you want to connect to the directory service over SSL, import the trusted SSL certificate for your Active Directory service 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 Active Directory authentication module. Instead, you need to access the SSL Certificates page and import it there. For more information, see SSL Certificates.
Enable Active Directory Authentication
To allow users stored in Microsoft Active Directory to log in to YouTrack, enable an Active Directory authentication module.
To enable Active Directory authentication:
In the Access Management section of the Administration menu, select .
From the Add Module drop-down list, select Active Directory.
The New Module dialog opens in the sidebar.
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
Select 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 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 DNdc=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 Active Directory 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 Active Directory 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 Active Directory Service
To verify that the Active Directory authentication module is connected to your Active 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 Active 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 Active 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 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. 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 YouTrack. The LDAP URL uses the format |
SSL key | Select an SSL key to encrypt the connection between YouTrack and the directory service. For more information about managing SSL keys in YouTrack, 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.
|
Bind Account Options
You can configure the module to perform the bind request with the Active Directory 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 |
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 the user profile in YouTrack. Use the following settings to define the filter criteria and map attributes that are stored in your directory service to Hub accounts that are linked to users in YouTrack.
Field | Description |
|---|---|
Login | Required. Maps to the LDAP attribute that stores the value to copy to the Login field in the Hub account. For Active Directory, the default value is |
Full name | Maps to the LDAP attribute that stores the value to copy to the Full name field in the Hub account. |
Maps to the LDAP attribute that stores the value to copy to the Email field in the Hub account. | |
Jabber | Maps to the LDAP attribute that stores the value to copy to the Jabber field in the Hub account. |
VCS user name | Maps to the LDAP attribute that stores the value to copy to the VCS user name field in the Hub account. |
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. 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. |
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 YouTrack. 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 Active Directory service to the groups in YouTrack.
If you want to map groups in the Active Directory service to YouTrack 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, YouTrack checks for Active Directory group memberships when users log in with accounts that are managed in the directory service. YouTrack performs the following operations for each LDAP group that is mapped to a YouTrack group:
Users who are members of a mapped Active Directory group and are not members of the mapped YouTrack group are added to the group in YouTrack.
Users who are not members of a mapped Active Directory group and are members of the mapped YouTrack group are removed from the group in YouTrack.
Changes to group memberships in the Active Directory service are only applied in YouTrack when users log in using the Active Directory auth module.
You can map multiple Active Directory groups to a single target group in YouTrack. You can't map Active Directory groups to more than one YouTrack group.
To map an Active Directory group to a group in YouTrack:
Open your Active Directory auth module.
Select the Group Mappings tab.
Click the Add mapping button.
The Add Mapping dialog opens.
Enter the name of the Active Directory 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 YouTrack group list.
Click the Add button.
The mapping is added to the list.
Sample Configurations
Use the following patterns to configure an Active Directory auth module using the LDAP protocol:
Setting | Value |
|---|---|
Server URL | ldap://ldap.company.com:389/dc=company,dc=com |
Bind DN | %u@<domain name> |
Filter | sAMAccountName=%u |
Use the following patterns to configure an Active Directory auth module with a secure connection over SSL:
Setting | Value |
|---|---|
Server URL | ldaps://ldap.company.com:636/dc=company,dc=com |
Bind DN | %u@<domain name> |
Filter | sAMAccountName=%u |