Microsoft Entra ID Auth Module
The Microsoft Entra ID authentication module is a pre-configured auth module that lets users log in to YouTrack with their Microsoft Entra ID accounts.
The Microsoft Entra ID 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.
Custom Tenant Setup
When you follow this setup, logins are restricted to users whose accounts are stored in your Microsoft Entra ID instance. If you want to accept login requests from any Azure Active Directory (AD) tenant, follow the instructions for a common tenant.
When you create a Microsoft Entra ID module for a custom tenant, you provide the tenant ID of the custom tenant when you create the auth module. This automatically adds your Azure Tenant ID to the authorization and token endpoints that are used by the auth module.
To learn how to set up a new tenant, please refer to the Microsoft Azure documentation.
To create the Microsoft Entra ID module:
From the
Administration menu, select .From the New module drop-down list, select Microsoft Entra ID.
The New Microsoft Entra ID Module dialog opens.
Enter a name for the module in the Name field.
Paste the value from the Tenant ID field in Microsoft Azure into the Tenant field.
Click the Create button in the dialog.
The Auth Modules page displays the settings for a new Microsoft Entra ID authentication module.
YouTrack generates a redirect URI for you to use in the authorization service.
If the feature is supported by your browser, use the Copy button to copy the redirect URI to your clipboard.
The next step is to register the authorized redirect URI for YouTrack in the Microsoft Azure portal. This gives you access to the client ID and secret that you need to enable the Microsoft Entra ID authentication module.
To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.
The following table lists the key configuration options that are required for this authentication module:
Setting | Description |
|---|---|
Supported account types | This determines who can use the application, sometimes called its sign-in audience. For this setup, choose the Accounts in this organizational directory only (Single tenant) option. |
Redirect URI | Paste the redirect URI from YouTrack into the input field. For the type, select the Web option. |
Application (client) ID | This value is automatically generated when you register the application in the Azure portal. Use the value from this field as the Client ID setting in YouTrack. |
Client secret | Value | This value is generated in the Certificates & secrets section of the App registration experience. Once you have added a client secret for the application, use the value for the client secret as the Client secret in YouTrack. |
API permissions | To map existing group memberships from the Microsoft Entra ID service to groups in Hub, you must grant the application the following Delegated type permissions for working with the Microsoft Graph API:
If you want to set up synchronization between Microsoft Entra ID and Hub, the following Application type permissions are required as well:
The complete list of permissions that are currently available to your app is listed on the API permissions page. |
Once you have the values that are required to connect with the authorization service, you can enable the Microsoft Entra ID auth module in YouTrack.
To enable the Microsoft Entra ID auth module:
Copy the Application (client) ID from Microsoft Azure and paste it into the Client ID input field in the YouTrack auth module.
Copy the value for the Client secret from Microsoft Azure and paste it into the Client secret input field in YouTrack.
Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Save button at the bottom of the page.
Click the Enable module button in the header.
The Microsoft Entra ID authentication module is enabled.
The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to YouTrack with their Microsoft accounts.
Common Tenant Setup
A Microsoft Entra ID module that uses the endpoint for common tenants follows the standard setup for an OAuth 2.0 auth module. This setup accepts login requests from any Azure Active Directory (AD) tenant, including users who are not members of your organization. If you want to restrict logins to users who are registered in your company's Microsoft Entra ID instance, follow the instructions for a custom tenant.
Your first step is to create an auth module and generate a redirect URI in YouTrack.
To generate a redirect URI in YouTrack:
From the Administration menu, select .
From the New module drop-down list, select Microsoft Entra ID.
The New Microsoft Entra ID Module dialog opens.
Enter a name for the module in the Name field.
Leave the Tenant ID field empty.
Click the Create button in the dialog.
The Auth Modules page displays the settings for a new Microsoft Entra ID authentication module.
YouTrack generates a redirect URI for you to use in the authorization service.
If the feature is supported by your browser, use the Copy button to copy the redirect URI to your clipboard.
The next step is to register the authorized redirect URI for YouTrack in the Microsoft Azure portal. This gives you access to the client ID and secret that you need to enable the Microsoft Entra ID authentication module.
To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.
The following table lists the key configuration options that are required for this authentication module:
Setting | Description |
|---|---|
Supported account types | This determines who can use the application, sometimes called its sign-in audience. Choose whichever option best matches your intended audience for YouTrack. |
Redirect URI | Paste the redirect URI from YouTrack into the input field. For the type, select the Web option. |
Application (client) ID | This value is automatically generated when you register the application in the Azure portal. Use the value from this field as the Client ID setting in YouTrack. |
Client secret | Value | This value is generated in the Certificates & secrets section of the App registration experience. Once you have added a client secret for the application, use the value for the client secret as the Client secret in YouTrack. |
API permissions | To map existing group memberships from the Microsoft Entra ID service to groups in Hub, you must grant the application the following Delegated type permissions for working with the Microsoft Graph API:
If you want to set up synchronization between Microsoft Entra ID and Hub, the following Application type permissions are required as well:
The complete list of permissions that are currently available to your app is listed on the API permissions page. |
Once you have the values that are required to connect with the authorization service, you can enable the Microsoft Entra ID auth module in YouTrack.
To enable the Microsoft Entra ID auth module:
Copy the Application (client) ID from Microsoft Azure and paste it into the Client ID input field in YouTrack.
Copy the value for the Client secret from Microsoft Azure and paste it into the Client secret input field in YouTrack.
Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Save button at the bottom of the page.
Click the Enable module button in the header.
The Microsoft Entra ID authentication module is enabled.
The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to YouTrack with their Microsoft accounts.
Settings
The first section of the settings page displays the general settings for the authentication module. Here, you also find the redirect URI that you use to register YouTrack in the authorization service and the input fields that store the Client ID and Client Secret that are generated in the authorization service.
Setting | Description |
|---|---|
Type | Displays the type of authorization 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. |
Button image | Displays the image used for the button that a user clicks to log in to YouTrack with their account in the connected authorization service. You can upload a JPG, GIF, or PNG file. The image is resized to 48 x 48 pixels automatically. |
Redirect URI | Displays the authorized redirect URI used to register the connection to YouTrack in the authorization service. |
Client ID | Stores the identifier that the authorization service uses to validate a login request. You generate this value in the authorization service when you configure the authorization settings for a web application and enter an authorized redirect URI. |
Client Secret | Stores the secret or password used to validate the client ID. You generate this value in the authorization service together with the client ID. |
Tenant ID | Stores the ID of the custom tenant in the Microsoft Entra ID service. For auth modules that are connected to a common tenant, this field is empty. |
Synchronization Settings
The settings in this section let you set up synchronization of user account data between YouTrack and Microsoft Entra ID.
When synchronization is enabled, changes applied to Microsoft Entra ID profiles are synchronized with YouTrack on a set schedule. This synchronization is performed in addition to the synchronization requests that are automatically sent when users log in to YouTrack using their Microsoft account credentials.
Values for the Full Name, Username, and Email that are stored in YouTrack are populated when the user account is first created, which is usually when a new user logs in to YouTrack using their Microsoft Entra ID account. Later changes to these attributes in Microsoft Entra ID profiles are not synced with YouTrack. These changes are synced with the corresponding attributes that are associated with their Microsoft Entra ID 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 Field Mapping settings and group memberships as configured on the Group Mappings tab. For details, see Field Mapping and Group Mappings.
Setting | Description |
|---|---|
Account status | This setting determines whether accounts are banned in YouTrack when an account with corresponding credentials is deleted or deactivated in the Microsoft identity platform.
|
Schedule | Determines the frequency with which user attributes 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 at any time by clicking the Synchronize now button. When synchronization is Off, group memberships are still synchronized on a per-user basis during login. To learn more about this feature, see Group Mappings. The synchronization feature is only active when the authentication module is Enabled. |
Field Mapping
If you have added custom attributes to user profiles, these attributes can also be mapped to attributes that are stored in the authorization service. Each custom attribute is listed by name with an input field for storing the name of the corresponding field in the authorization service.
Attribute names are case-sensitive. If the Microsoft attribute synced is written in camelCase, the attribute field name entered in YouTrack must match.
Custom attributes in YouTrack are created with a specific type. The corresponding value from the Azure field must match the field type specified in YouTrack.
YouTrack supports attributes retrievable directly from the authentication service user accounts. Attributes like Manager or Sponsors that require querying a separate resource are not supported.
To learn more about custom attributes in user profiles, see Manage Custom Attributes.
When a user profile response object is returned by Azure Active Directory, values from the specified field paths are copied to the accounts that are stored in YouTrack. Use the following settings to define the endpoint that locates profile data for the authenticated user and map fields that are stored in the authorization service user profiles to the corresponding YouTrack accounts.
To specify paths to fields inside nested objects, enter a sequence of segments separated by the slash character (
/).To reference values that may be stored in more than one location, use the "Elvis operator" (
?:) as a delimiter for multiple paths. With this option, YouTrack uses the first non-empty value it encounters in the specified field.
Additional Settings
The following options are located at the bottom of the page. These settings let you define the request scope and choose how to authenticate with the service.
Other options in this section 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 authorization service. YouTrack uses the email address to determine whether the user has an existing account. |
Auto-join groups | Adds users to a group when they log in with an account that is stored in the connected authorization 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. |
Group Mappings
On the Group Mappings tab, you can map existing groups in the authorization service to the groups in YouTrack.
The Microsoft Entra ID module automatically maps the attribute that stores Microsoft Entra ID group memberships to the field that stores membership records in the YouTrack database. All you need to do is map the groups in the Microsoft Entra ID service to their counterparts in YouTrack.
When group mappings are configured, YouTrack checks for Microsoft Entra ID group memberships when users log in with accounts that are managed in the directory service. YouTrack performs the following operations for each Microsoft Entra ID group that is mapped to a YouTrack group:
Users who are members of a mapped Microsoft Entra ID 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 Microsoft Entra ID group and are members of the mapped YouTrack group are removed from the group in YouTrack.
Changes to group memberships in the authorization service are only applied in YouTrack when users log in using their Microsoft Entra ID accounts.
You can map multiple Microsoft Entra ID groups to a single target group in YouTrack. You can't map Microsoft Entra ID groups to more than one YouTrack group.
To map a group from Microsoft Entra ID to a group in YouTrack:
Open your Microsoft Entra ID auth module.
Select the Group Mappings tab.
Click the Add mapping button.
The Add Mapping dialog opens.
Enter the name of the Microsoft Entra ID group in the OAuth group name field.
Select a group from the Target group list.
Click the Add button.
The mapping is added to the list.
Actions
The following actions are available in the header:
Action | Description |
|---|---|
Set default | Designates the authentication module as the default for your YouTrack site. 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. This option is only shown when the current authentication module is not designated as the default. |
Clear default | Removes the authentication module as the default for your YouTrack site. If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the Hub login page. This option is only shown when the current authentication module is designated as the default. |
Disable module | Disables the authentication module. This option is only shown when the authentication module is currently enabled. |
Enable module | Enables the authentication module. This option is only shown when the authentication module is currently disabled. |
Delete module | Removes the authentication module from YouTrack. Use only when you have configured additional authentication modules that let users log into your YouTrack site. |
Migration from the Azure AD 2.0 Auth Module
The Azure AD authentication module included in YouTrack versions earlier than 2022.2 doesn't support the ability to map and sync memberships between groups in the Microsoft Entra ID service and groups in YouTrack. If you want to use this feature, you need to migrate to the updated version of the authentication module.
To perform this migration:
Delete the existing Azure AD 2.0 authentication module. You can distinguish the older module because it is assigned the OAuth 2.0 type in the list.
Set up a new Microsoft Entra ID authentication module as described on this page.
You can also copy the existing client ID and client secret that are stored in the deactivated module to the new authentication module and register the redirect URI for the new module in Microsoft Azure.
To register the redirect URI for the new module:
From the Administration menu, select .
Select the Azure AD 2.0 authentication module from the list.
Open the Auth Modules page in a separate window or browser tab.
From the New module drop-down list, select Microsoft Entra ID.
The New Microsoft Entra ID Module dialog opens.
Enter a name for the module in the Name field.
If you're working with a custom tenant setup, copy the value for the Tenant ID from the deactivated module and paste it into the input field for the new module. If working with a common tenant setup, leave the Tenant ID field empty.
Click the Create button in the dialog.
The Auth Modules page displays the settings for a new Microsoft Entra ID authentication module.
YouTrack generates a redirect URI for you to use in the authorization service.
If the feature is supported by your browser, use the Copy button to copy the new redirect URI to your clipboard.
Navigate to your existing application in the Microsoft Azure portal.
Add the new redirect URI to the list of redirect URIs that are registered for the application. If you want to remove the redirect URI for the deactivated module, it's safe to do so now as well.
Switch back to the Azure AD 2.0 auth module in YouTrack.
Copy the value stored as the Client ID, switch to the new authentication module, then paste this value in to the Client ID field there.
Switch back to the old module and copy the value stored as the Client secret. Switch back to the new authentication module and paste this value in to the Client secret field there.
Click the Save button at the bottom of the page.
Click the Enable module button in the header.
The new Microsoft Entra ID authentication module is enabled.
The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to YouTrack with their Microsoft accounts.
Click the Auth Modules link to return to the list of authentication modules.
Select the deactivated Azure AD 2.0 module from the list.
Click the Delete button in the toolbar.
Click the Delete button in the confirmation dialog.