Azure AD 2.0 Auth Module
The Azure AD 2.0 authentication module is a pre-configured OAuth 2.0 auth module that lets users log in to YouTrack with their Azure AD 2.0 credentials.
Custom Tenant Setup
When you follow this setup, logins are restricted to users whose accounts are stored in your Azure AD 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 an Azure AD 2.0 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 Azure AD 2.0 module:
From the Administration menu, select .
From the New module drop-down list, select Azure AD 2.0.
The New Azure AD 2.0 Module dialog opens in the sidebar.
Paste the value from the Tenant ID field in Microsoft Azure into the Tenant input field.
Click the Create button in the dialog.
The Auth Modules page displays the settings for a new Azure AD 2.0 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 Azure AD 2.0 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 Hub into the input field. For the type, select the Web option. |
Application (client) ID | his 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 Hub. |
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 Hub. |
Once you have the values that are required to connect with the authorization service, you can enable the Azure AD 2.0 auth module.
To enable the Azure AD 2.0 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 Hub.
Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Enable module button in the header.
The Azure AD 2.0 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
An Azure AD 2.0 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 Azure AD 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 Azure AD 2.0.
The New Azure AD 2.0 Module dialog opens in the sidebar.
Click the Create button in the dialog.
The Auth Modules page displays the settings for a new Azure AD 2.0 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 Azure AD 2.0 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 Hub. |
Redirect URI | Paste the redirect URI from Hub into the input field. For the type, select the Web option. |
Application (client) ID | his 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 Hub. |
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 Hub. |
Once you have the values that are required to connect with the authorization service, you can enable the Azure AD 2.0 auth module.
To enable the Azure AD 2.0 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 to apply the settings.
Click the Enable module button.
The Azure AD 2.0 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 a 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 that is 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. |
Authorization Service Endpoints
The settings in this section of the page store the OAuth 2.0 endpoints used by Azure AD 2.0.
For pre-configured OAuth 2.0 modules, the values that are used by the selected authorization service are set automatically.
Setting | Description |
|---|---|
Authorization | Stores the endpoint that YouTrack uses to obtain authorization from the resource owner via user-agent redirection. |
Token | Stores the endpoint that YouTrack uses to exchange an authorization grant for an access token. |
User data | Stores the endpoint used to locate profile data for the authenticated user. |
The endpoint used to locate the email address of the authenticated user. Use only when the email address is not stored in the user profile. | |
Avatar | The endpoint used to locate the binary file that is used as the avatar for the authenticated user. Use only when the avatar isn’t stored directly in the user profile. |
Field Mapping
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 to the corresponding YouTrack accounts.
For the Azure AD 2.0 module, the values are set automatically.
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.
Field | Description |
|---|---|
User ID | Maps to the field that stores the value to copy to the User ID property in the YouTrack account. |
Maps to the field that stores the value to copy to the Email field in the YouTrack account. | |
Email verification state | Maps to the field that stores the value to copy to the verified email property in the YouTrack account. |
Full name | Maps to the field that stores the value to copy to the Full name field in the YouTrack account. |
Avatar | Maps to the field that stores the image to use as the Avatar in the YouTrack account. |
Image URL pattern | Generates an image URL for avatars that are referenced by an ID. Use the <picture-id> placeholder to reference the field that stores the avatar. |
Groups | Maps to the attribute that stores group membership assignments in the connected authorization service. When this value is specified, you can map and sync group memberships in the authorization service with corresponding groups in YouTrack. For details, see Group Mappings. |
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 |
|---|---|
Scope | Sets the scope for the access request. Enter a list of scopes, separated by spaces. |
Authentication | Determines how credentials are passed to the authorization service. |
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. |
Email auto-verification | Determines how YouTrack sets the verification status of an email address when the authentication service does not return a value for this attribute. |
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 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 YouTrack. There, you can view a list of changes that were applied to this authentication module. |