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 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:
From the main navigation menu, select
.Click the New module button.
The Select an identity provider dialog opens.
In the Select an identity provider dialog, select Active Directory.
The Configure Login with Active Directory wizard opens.
Fill in the fields, then click Next.
In the Auth module name field, enter a name for the authentication module.
In the Server field, enter the server address of the directory service. For a connection over SSL, change the protocol part of the address to
ldaps.In the Port field, enter the port used to connect to the directory service.
The default port for standard LDAP is 389.
The default port for LDAPS is 636.
To connect over SSL, enable the Use SSL option. Before you can establish a secure connection, you need to import the trusted SSL certificate for your LDAPS server. For instructions, see SSL Certificates.
Define the search base and filter, then click Next.
In the Search base field, enter 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 stored 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. Active Directory authentication modules do not support recursive search in the LDAP tree.
In the Filter field, enter the expression that locates the authenticated user in the directory service. Use
%uto reference the username entered on the login page.
Choose how YouTrack binds to the directory service during authentication.
Select Fixed when YouTrack needs a dedicated bind account to query users and groups for synchronization.
In the Bind DN field, enter the distinguished name (DN) of the account that YouTrack uses to authenticate to the directory service and query user information.
In the Password field, enter the password for the bind account.
Select Dynamic when users can bind directly with their own directory credentials.
In the Bind DN field, enter the pattern that YouTrack uses to construct the user's distinguished name (DN). Use
%uto reference the username entered on the login page. For example,uid=%u,dc=company.
Click Finish.
The Active Directory authentication module is created and its configuration page opens.
To complete the setup:
Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Save button to apply the settings.
Click the Enable button.
The Active Directory authentication module is enabled.
The Active Directory icon is added to the login dialog window. Users can click this icon to log in to YouTrack with their Active Directory credentials.
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:
From the main navigation menu, select
.Open the Active Directory module.
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 Username 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.
General Information
In the header of the settings page, you can find the general information about the authentication module.
Setting | Description |
|---|---|
Name | Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list. You can change the name and icon of the authentication module using the Rename action. For more details, see Actions. |
Type | Displays the type of authorization service that is enabled for third-party authentication in YouTrack. |
Accounts imported to YouTrack | Displays the number of users that have been imported to YouTrack. |
Accounts discovered in Active Directory | Shows the number of user accounts found in the connected Active Directory service. |
Groups discovered in Active Directory | Shows the number of groups found in the connected Active Directory service. |
Actions
The following actions are available in the header:
Action | Description |
|---|---|
Test login | Lets you enter a username and password to test the connection with the authentication service. |
Sync now | Launches the synchronization of users and groups between the connected service and YouTrack. You can configure which groups to use in YouTrack on the Group Mapping tab. |
Enable | Enables the authentication module. This option is only shown when the authentication module is currently disabled. |
Disable | Disables the authentication module. This option is only shown when the authentication module is currently enabled. |
Rename | Lets you update the existing authentication module name and change its default icon. You can find this action in the |
Delete | Removes the authentication module from YouTrack. Use only when you have configured additional authentication modules that let users log into your YouTrack installation. You can find this action in the |
General Settings
On the General Settings tab, you configure the connection to the Active Directory service, define how authenticated users are located in the directory, and manage synchronization settings.
Field | Description |
|---|---|
Default | Designates the authentication module as the default for your installation. Only one authentication module can be set as the default at any time. If another module is currently set as the default, that state is cleared. If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the YouTrack login page. |
Connection
The Connection settings establish the primary communication channel between YouTrack and your organization's directory service. By defining the authoritative network location and access parameters, this configuration allows YouTrack to securely query your Active Directory service.
Field | Description |
|---|---|
Server URL | Stores the LDAP URL of the Active Directory service used to authenticate a login request in YouTrack. The LDAP URL uses the format |
SSL key | Selects an SSL key that can be used to verify the identity of your YouTrack installation to the directory service. You should only need to use this setting when your directory service requires client SSL authentication. For more information about managing SSL keys in YouTrack, see SSL Keys. |
Filter | Stores an expression that locates the record for a specific user in the Active Directory service. The substitution variable in the expression is replaced with the value entered as the username or email on the login page. If left empty, YouTrack falls back to the value sAMAccountName=%u, where LDAP filter syntax is supported in this field. This makes it possible to add multiple attributes if needed. Example: Configure authentication to accept either a username or email as a login input.
|
Synchronization
The Synchronization settings allow you to automate user management by periodically aligning YouTrack’s user directory with your Active Directory service. By configuring a dedicated, fixed service account (bind DN) with read permissions, YouTrack can run scheduled background updates. This process ensures that user profiles, group memberships, and account statuses within YouTrack remain continuously up-to-date with any changes made on the central identity provider.
Field | Description |
|---|---|
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:
|
You can also manually synchronize the YouTrack database with the directory service at any time by clicking the Sync now button.
Values for the Full Name, Username, and Email that are stored in the YouTrack profile are populated when the user account is first created, which is usually when a new user logs in to YouTrack using their Active Directory account. Later changes to these attributes in Active Directory profiles are not synced with the YouTrack profile. These changes are synced with the corresponding attributes that are associated with their Active Directory credentials. This information is displayed in the Credentials section of the Account Security tab in the YouTrack profile.
This synchronization applies to the attributes that are configured in the Attribute Mapping settings and group memberships as configured on the Group Mapping tab. For details, see Attribute Mapping and Group Mapping.
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 Mapping.
The Synchronization option is only available when the Bind account setting is Fixed. This allows YouTrack to search the directory service on behalf of the bind account owner.
The synchronization feature is only active when the authentication module is Enabled.
Bind
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 user accounts in YouTrack.
User Attributes
The User Attributes configuration defines how data fields from your Active Directory service translate into distinct profile properties within YouTrack. By mapping standard Active Directory keys like sAMAccountName for unique usernames, cn for full names, and mail for email addresses, YouTrack can accurately populate and maintain personal user profiles upon successful authentication, ensuring identity consistency across both platforms.
Setting | Description |
|---|---|
Username | Required. Maps to the LDAP attribute that stores the value to copy to the Username field in the YouTrack profile. 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 YouTrack profile. |
Maps to the LDAP attribute that stores the value to copy to the Email field in the YouTrack profile. | |
VCS username | Maps to the LDAP attribute that stores the value to copy to the VCS username field in the YouTrack profile. |
Group Attributes
The Group Attributes settings establish the relationship between Active Directory groups and YouTrack user groups to automate access control. YouTrack can synchronize team hierarchies and assign appropriate roles and permissions based on your central directory's structure.
Setting | Description |
|---|---|
User groups | Maps to the attribute on user objects in LDAP that lists the distinguished names of groups the user belongs to. You must specify either Group members or User groups. |
Group members | Maps to the attribute on group objects in LDAP that lists the distinguished names of its members. You must specify either Group members or User groups. Separate multiple values with commas. |
LDAP Account Status
The LDAP account status setting determines whether user account statuses are updated in YouTrack when the status for an account with corresponding credentials is updated in the Active Directory service.
If the account has been denied access in the Active Directory service, the YouTrack account is automatically banned. If access is later restored to the account in Active Directory, the YouTrack account will be unbanned.
If the account was deleted in Active Directory, the YouTrack account is banned and the corresponding credentials are removed from the YouTrack account. In this case, the YouTrack account is not unbanned automatically when the account is restored in the linked directory service. The status must be updated manually in YouTrack.
The following options are available for this setting:
Option | Description |
|---|---|
Ignore | The status of YouTrack 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 YouTrack on login or sync, when enabled. |
If the Bind account setting for the authentication module is set to Fixed and 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 Active Directory account to log in to YouTrack.
The following attribute mapping settings are used to synchronize account status from Active Directory:
Setting | Description |
|---|---|
Account expired | Maps to the LDAP attribute that stores the expiration date for the account in the connected directory service. |
Account disabled | Maps to the LDAP attribute that stores the date when the user account was disabled in the connected directory service. |
Lockout threshold | Maps to the LDAP attribute that stores the number of attempts that users are allowed to log in unsuccessfully before their account is locked out. |
Lockout time | Maps to the LDAP attribute that stores the date and time when an account was blocked because the maximum lockout threshold was exceeded. |
Lockout duration | Maps to the LDAP attribute that stores the amount of time a user is blocked from logging in to their account after exceeding the lockout threshold. |
Group Mapping
On the Group Mapping 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.
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 Active Directory service are only applied in YouTrack when users log in using the Active Directory 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 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:
From the main navigation menu, select
.Open your Active Directory auth module.
Select the Group Mapping 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 to 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 full DN of the group exactly as it appears in the directory service.
Click the Add button.
The mapping is added to the list.
SCIM 2.0
The tab lets you enable System for Cross-domain Identity Management (SCIM) provisioning for the Active Directory authentication module. When SCIM provisioning is enabled, an external identity provider can create, update, and deactivate Hub user accounts using the SCIM 2.0 protocol.
The Active Directory authentication module synchronizes user data only during login. When a user signs in, YouTrack reads the user attributes and group memberships returned by the identity provider.
Changes made in the identity provider are not synchronized automatically while the user is inactive. For example, updates to user attributes or group memberships are applied only after the user signs in again.
To keep user accounts and groups synchronized automatically, enable SCIM 2.0 provisioning and create a SCIM 2.0 token for the authentication module.
Enable SCIM 2.0 provisioning
To allow an external identity provider to provision users through SCIM:
Open your Active Directory auth module.
Select the SCIM 2.0 tab.
Enable the Enable SCIM 2.0 provisioning option.
YouTrack generates a SCIM 2.0 base URI for this authentication module.
Create a SCIM 2.0 token and copy its value.
Specify both the SCIM 2.0 base URI and SCIM 2.0 token generated in YouTrack when configuring SCIM provisioning in your identity provider. The base URI identifies the provisioning endpoint, while the token authenticates provisioning requests sent by the identity provider.
Create a SCIM 2.0 Token
In the SCIM 2.0 Tokens section, click New Token.
In the New SCIM 2.0 Token dialog, enter a name for the token.
Click Create.
Hub generates the token and displays its value in the SCIM 2.0 Token Created dialog.
Copy the token value and store it in a secure location before closing the dialog. The token value cannot be viewed again after the dialog is closed.
Delete a SCIM 2.0 Token
Select one or more tokens in the SCIM 2.0 Tokens table.
Click Delete and confirm the action in the Delete SCIM 2.0 token dialog.
Additional Settings
The settings on the Additional settings tab let you manage account creation and group membership and reduce the loss of processing resources consumed by idle connections.
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 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 YouTrack. There, you can view a list of changes that were applied to this authentication module. |
Sample Configurations
Use the following patterns to configure an Active Directory auth module using the LDAP protocol:
Setting | Value |
|---|---|
Server URL |
|
Bind DN |
|
Filter |
|
Use the following patterns to configure an Active Directory auth module with a secure connection over SSL:
Setting | Value |
|---|---|
Server URL |
|
Bind DN |
|
Filter |
|