Integrating OAuth 2.0 for Microsoft Accounts on Jira

Summary

On Jira Data Center, email configuration pages show the warning: "This authentication method is deprecated, you should use OAuth 2.0 instead."

Diagnosis

On service management project settings page, click Email Requests and there is a warning that says "This authentication method is deprecated, you should use OAuth 2.0 instead. Learn more". Elsewhere, under system menu on Jira administration, click Incoming Mail, then Add Mail Server and select Password (basic authentication) from Authentication method. This shows a warning "We recommend selecting OAuth to authenticate to this mail server. Basic authentication using only a password is planned to be deprecated by Microsoft and Google. Learn more".

Cause

Google and Microsoft are planning to disable using password as an authentication method. Once this method is disabled, you will not be able to connect to your Gmail or Microsoft Exchange Online. This means you wouldn’t be able to use these providers (Gmail, Microsoft Exchange Online) to let users create issues and comments from emails if you were authenticating using basic auth. To fix this, you need to configure the OAuth 2.0 integration with these providers, and then update the configuration of your mail servers.

Solution

Configure OAuth 2.0 integration and select it as your authentication method (learn more about Integrating with OAuth 2.0). It involves setting up an application registration at the provider side and integrating the same on Jira.The steps below are for the integration of Microsoft accounts on Jira and it provides a general guidance to the app registration on Microsoft as well. Microsoft specific steps may get changed and at this time of writing this KB article, the relevant Microsoft link is here.

Before you begin

You need to ensure the following:

• Running Jira applications over SSL or HTTPS. If it doesn’t, you will not be able to configure OAuth 2.0.

• Configuring the base URL. This is important as the redirect URL you’ll need to provide is based on Jira’s base URL.

• Port 443 needs to be open for outgoing and incoming connections since the OAuth 2.0 authentication uses https connections.

• IMAP or POP port (depending on the connection protocol) needs to be open for outgoing connections.

ℹ️ You can use the same OAuth2 configuration to authenticate all the users if you have multiple mail servers. This applies if the users are from the same tenant or the enterprise app is setup for multi-tenant. Otherwise, you would need to have an additional OAuth2 configuration.

Create OAuth 2.0 Integration for Microsoft

From Jira v8.22 onwards, the OAuth 2.0 Integration has been moved from global Jira administration "System" menu to "Application Links" menu. The Jira specific steps are explained in this documentation page for Jira version above 8.22 and in this documentation page for Jira version below 8.22. The steps are common from #2 onwards.

1. Add a New Integration

For Jira versions above 8.22.0.

• In the upper-right corner of the screen, select Administration > Applications.

• Under the Integrations (the left-side panel), select Application links.

• Select Create link.

• In a new dialog that opens, select External application, and then choose Outgoing as the direction. Do not get confused by the selection of Outgoing here - Jira acts as a client to the application and hence, the outgoing is selected even for Incoming mail server.

For Jira versions below 8.22.0.

• In the upper-right corner of the screen, select Administration > System.

• Under the OAuth 2.0 (the left-side panel), select Add New Integration.

2. Configure your Integration

For this integration, choose Microsoft as the service provider and some fields will be pre-filled for you. Enter a friendly name for the integration and click Copy at the Redirect URL field.

3. Register your external application on Microsoft.

• Login to "https://portal.azure.com/"

• From the left menu, select Azure Active Directory. Click on App registrations

• Click on New registration

• Pick up a friendly name so it will be easier to identify

• Under the "Supported account types" section, let's choose "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"

• Under the "Redirect URI" section, let's pick up Web and insert the URL from the step 2 above

• Click on Register

4. Configure API permissions and grant permissions on Microsoft.

• Click on API permissions

• Click on Add a permission

• Click on Microsoft Graph

• Select Delegated permissions

• Search and select the following permissions:

To learn more about scopes, see detailed information from Microsoft.

• Click on Add permissions

• Click on Grant admin consent for XXXX

5. Create certificate and secrets.

• Click on Certificates & secrets

• Click on New client secret

• Choose a description and expiration date and click Add

• Take note of the Value generated (this will be used as the "Client secret" at Jira). Copy the value and keep it for use on Jira.

• At the left side, click on Overview

• Take note of the Application (client) ID (this will be used as the "Client ID" at Jira). Copy the value and keep it for use on Jira.

6. Provide remaining application details on Jira

• Provide the remaining details. Here you can find descriptions for all the fields.

ℹ️ You can run connectivity test at this Microsoft Link with the email account ID you'll be using on Jira. The test should return a successful result and if not, reach out to your Exchange admin to grant necessary permissions to the account. ( This may not work for GCC High )

7. Save your Integration

• After you save the configuration, it will appear on the application links menu (for Jira above v8.22) or under OAuth 2.0 on Jira administration system menu (for Jira below v8.22).

• Click Test connection to make sure the connection works. Once connection is tested successfully, you will be able to select this newly created integration when configuring mail servers or Jira Service Management email channels.

Test OAuth Integrations

• When configuring "Email Settings" under project settings, you can select newly created OAuth 2.0 under the authentication method.

• When configuring "Incoming Mail" under Jira global system administration menu, click "Add Mail Server" and you can select newly created OAuth 2.0 under the authentication method.

• When configuring "Outgoing Mail" Jira global system administration menu, click "Configure new SMTP mail server". Under the "Service Provider" field, pick up Microsoft Exchange Online / Outlook (IMAP). At the "Authentication method" field, select the newly created OAuth 2.0. Remember to add scope https://outlook.office365.com/SMTP.Send for outgoing mail.

  ⚠️ OAuth 2.0 for SMTP outgoing mail servers is supported only in Jira 9.2 and above.

ℹ️ For troubleshooting OAuth2.0 integration issues with Jira global mail handlers or Jira Service Management mail handlers, please refer to our troubleshooting guide