YouTrack Server 2022.2 Help

Critical Updates for Integrations with Microsoft Exchange Online

Starting from October 1, 2022, Microsoft will no longer support connections to Microsoft Exchange Online mailboxes that use Basic Auth. Instead, the connection must be set up through a client application registered in the Microsoft Azure portal. Additional information about this change is available from the Microsoft Tech Community forum.

If you are currently using Microsoft Exchange Online to support a Mailbox integration in YouTrack, you must migrate to the new configuration before the end of September 2022. Otherwise, requests to retrieve messages from the mail server will be blocked.

This update requires that you perform the following actions:

Register a Client Application in Microsoft Azure

This setup requires that you meet the following prerequisites:

  • A valid license for Microsoft Exchange Online. This licence must also be assigned to the tenant directory that contains the accounts that you want to use for sending and receiving email messages.

  • The registered application that authenticates the connection with YouTrack must be created in the same tenant directory where the Microsoft Exchange Online license is applied.

  • The security groups must be configured to grant this application access to the mailboxes that are used to send and receive email messages. To learn how to grant access to an application, please refer to the Microsoft documentation.

  • Administrative access to Microsoft Azure Active Directory (AD).

To complete the migration, you will need to obtain the following information from the Microsoft platform:

  • The email address of the mailbox where the integration currently retrieves incoming messages. This mailbox must belong to the same Azure AD service where you register the app.

  • The Application (client) ID of the app that is registered in the Microsoft Azure portal.

  • The Directory (tenant) ID of your Azure Active Directory tenant organization.

  • A client secret that you created for the registered app.

The Application (client) ID and Directory (tenant) ID can be found in the Essentials section of the client application as shown below.

The Essentials section of a registered client application in Microsoft Azure.

The client secret can be generated from the Certificates & secrets < Client secrets section.

The Certificates & secrets section of a registered client application in Microsoft Azure.

To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.

Add the Required Permissions to the Client App

Next, you need to grant the following API permissions to the app:

  • Mail.Read

  • Mail.Read.Shared (for working with shared and delegated mail folders)

  • User.Read

The list of permissions can be found in the API permissions settings of the client app.

The API permission settings of a registered client application in Microsoft Azure.

If you are logged in under an administrator account (as listed in the prerequisites), you can grant these permissions yourself. If not, you will need to ask an administrator to grant these permissions for you.

To learn how to configure permissions for a client app, please follow the instructions in the product documentation for Microsoft Azure.

Update the Mailbox Integration Settings in YouTrack

Once you have collected the required information from the Microsoft platform, you can update the configuration for your Mailbox integration in YouTrack.

To migrate from Basic Auth to the app-based authentication scheme:

  1. From the Administration menu, select Integrations > Mailbox Integration.

  2. Select the integration with Microsoft Exchange Online from the list. If the Details panel is collapsed, click the Show details button.

  3. For the Server type setting, select Microsoft Exchange Online.

    • The integration is updated to show specific settings for this mailbox type.

  4. For the Mailbox address, enter the email address where the integration currently retrieves incoming messages.

  5. For the Tenant ID, enter the Directory (tenant) ID of the Azure Active Directory tenant organization.

  6. For the Client ID, enter the Application (client) ID for the registered client application in Microsoft Azure.

  7. For the Client secret, enter the value for the secret that you generated for the client app in Microsoft Azure.

  8. To verify that YouTrack is able to establish a connection with the mail server, click the Test connection button.

  9. If the test is successful, click the Save button.

    • The mailbox integration is updated to use the app-based authentication scheme.

    • The integration will continue to retrieve messages from the mail server according to the current Fetching interval setting.

Last modified: 21 September 2022