Detailed steps to configure OAuth 2.0 integration with Microsoft Azure
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This guide aims to provide a more detailed overview of every step required to integrate Jira using OAuth2.0 authentication with Microsoft Azure.
It shows screenshots of the location of each piece of information we need to successfully complete the integration.
Creating the OAuth 2.0 application link in Jira:
First, start creating an application link integration:
For Jira 8.22+/4.22+:
Go to Jira administration > Applications, and then Application links.
Select External application and Outgoing, then Microsoft as the provider if you're on a "non-GCC" or a "normal GCC plan, or choose Custom if you're on a DoD or GCC-High plan. (More details will follow in the next steps)
Initial configuration on the Jira side:
1. On the bottom section, copy the Redirect URL from the Jira OAuth2.0 integration that you created.
Now to the Azure side:
2. Go to "https://portal.azure.com/"
3. Click on App registrations
4. Click on New registration
5. Let's pick up a friendly name so it will be easier to identify
6. 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)"
In this step is important to choose the "and personal Microsoft accounts", as this uses the common endpoint.
7. Under the "Redirect URI" section, let's pick up Web and insert the URL from the step #1 above
8. Click on Register
9. Click on API permissions
10. Click on Add a permission
11. Click on Microsoft Graph
12. Select Delegated permissions
13. Search and select the following permissions, depending on what protocols you are going to use:
If you're using the regular API:
offline_access
IMAP.AccessAsUser.All
POP.AccessAsUser.All
Or these if you're using Microsoft Graph API:
Mail.ReadWrite
Mail.ReadWrite.Shared (for shared mailboxes only)
offline_access
Check with Microsoft which one you should be using.
14. Click on Add permissions
15. Click on Grant admin consent... if this option is not available, there must be a message saying that your grant is already given above this table.
16. Click on Certificates & secrets
17. Click on New client secret
18. Choose a description and expiration date
19. Copy the Value generated, as this "Value" will be used as the "Client secret" in Jira to complete the configuration.
Known errors:
The "Value" is the "Client secret" we need to use on Jira. If you use the "Secret ID" as the "Client secret" on the Jira OAuth settings it will cause an authentication error.
20. Click on Overview
21. Take note of the Application (client) ID, we'll use this as the "Client ID" at the Jira side config.
Extra step:
On the Overview page, there's a link on the top called "endpoints", check if your "OAuth 2.0 authorization endpoint (v2)" and "OAuth 2.0 token endpoint (v2)" match the same ones defaulted on the Jira side.
Correct them on the Jira side to the Endpoints Azure is expecting if needed as this is the root cause of several "single-tenant" and "multi-tenant" issues.
Jira side part 2:
22. Let's go back to Jira and complete the configuration by inserting the following details:
Client ID = "Application (client) ID" from step #21 above.
Client secret = "Value" from step #19 above.
23. For the Scopes, manually copy and paste individually these URLs, depending on what protocols you are going to use and on your Azure account type:
For non-GCC, and "normal" Government Community Cloud (GCC) plans, which are the most commons type of plans, use the following scopes:
https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All offline_access
For US Government DoD or US Government GCC High plans, use the following scopes:
https://outlook.office365.us/IMAP.AccessAsUser.All https://outlook.office365.us/POP.AccessAsUser.All offline_access
Known errors:
Using GCC High scopes with non-GCC or "normal" GCC accounts will cause connection issues.
Read more for similar issues caused by wrong scope
For more details on GCC High accounts, check this even more detailed guide:
For Microsoft Graph API, use these:
Scopes for Microsoft Graph API (valid for Jira 9.9+ or Jira Service Management 5.8+ only):https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/offline_access https://graph.microsoft.com/Mail.ReadWrite.Shared (for shared mailboxes only)
Microsoft Graph API
For more details of the use and configuration of the Microsoft Graph API, check these pages:
Configuring an incoming mail server with POP, IMAP, or Microsoft Graph API
Setting up an email channel with the Microsoft Graph API protocol
24. Click on Save
25. Test the connection
You'll be redirected to the authentication page.
If the Auth is successful, you'll return to Jira with a confirmation message that the integration worked!
What if the authorization fails?
We'll most likely have a network issue that is preventing this Authorization from being fully completed, as the root cause requires a deeper debug, please raise a ticket on our Atlassian Support Channel.
Known issues and errors:
AADSTS7000215: Invalid client secret is provided
This might indicate that the secret value / ID was wrongly copied, as step #19 states.
Or, create a new secret to use with this Jira application link.