Detailed steps to configure OAuth 2.0 integration with Microsoft Azure

Still need help?

The Atlassian Community is here for you.

Ask the community

Summary

As of now the transition from Basic Authentication to OAuth 2.0 is causing much confusion, so this guide aims to add more visual details from the Jira side as well as on the Azure portal side!



Basic Authentication deprecation date was postponed

Microsoft postponed the deprecation of basic authentication:

Basic Authentication Deprecation in Exchange Online – September 2022 Update


Today we are announcing an update to our plan to offer customers who are unaware or are not ready for this change.

When we turn off basic auth after October 1st, all customers will be able to use the self-service diagnostic to re-enable basic auth for any protocols they need, once per protocol. Details on this process are below.

Once this diagnostic is run, basic auth will be re-enabled for those protocol(s). Selected protocol(s) will stay enabled for basic auth use until the end of December 2022. During the first week of the calendar year 2023, those protocols will be disabled for basic auth use permanently, and there will be no possibility of using basic auth after that.


Creating the OAuth 2.0 application link in Jira:

Step "zero": We'll start by creating the Oauth integration, to find this page there are 2 places depending on the Jira versions:

For Jira 8.22 and later:

Go to Jira administration > Applications, and then Application links

(info) Select the External application and Outgoing, then Microsoft as the provider for default settings:

For previous Jira versions:

Go to Jira administration > System > OAuth 2.0

(info) Add New integration and Select Microsoft as the provider for default settings:

Now the actual Jira initial config:

1. On the bottom section, copy the Redirect URL from the Jira OAuth2.0 integration that you created.

That's the Jira part 1!

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:

Required API Permissions for IMAP and POP
offline_access
IMAP.AccessAsUser.All
POP.AccessAsUser.All

or

Required API Permissions for Microsoft Graph API (valid for JSM 5.8+ only)
Mail.ReadWrite
offline_access

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.

Azure Active Directory configuration
16. Click on Certificates & secrets
17. Click on New client secret
18. Choose a description and expiration date
19. Take note of the Value generated, this "Value" will be used as the "Client secret" at Jira.

Known errors:

The "Value" is the "Client secret" we need to use on Jira.
The "Secret ID" is not the password and 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:

Scopes for IMAP and POP, and non-GCC (Government Community Cloud) accounts:
https://outlook.office.com/IMAP.AccessAsUser.All 
https://outlook.office.com/POP.AccessAsUser.All 
offline_access

Known errors:

The above scopes will not work for GCC accounts.

or

Scopes for IMAP and POP, and GCC accounts:
https://outlook.office365.com/IMAP.AccessAsUser.All
https://outlook.office365.com/POP.AccessAsUser.All
offline_access

Known errors:

Using GCC scopes with non-GCC accounts will cause connection issues.

 (info) Read more for similar issues caused by wrong scopes.

or

Scopes for Microsoft Graph API (valid for JSM 5.8+ only):
Mail.ReadWrite
offline_access

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 to be 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

On the atlassian-jira.log file we have this: AADSTS7000215
2022-xx-xx 20:34:03,014+0000 http-nio-8080-exec-253 ERROR username 1234x5727202x3 1i8mi5a 0.0.0.0.0.0.0.0 /rest/oauth2-client/latest/config/flow/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx [c.a.o.c.rest.resource.ClientConfigurationResource] Error occurred while authorizing an integration. The error message is: AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'.
    Trace ID: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
    Correlation ID: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
    Timestamp: 2022-xx-xx 20:33:57Z

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.





Last modified on Aug 17, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.