Setting up OAuth 2.0 integration

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

OAuth 2.0 is now part of application links

This page is obsolete and describes the state of OAuth 2.0 as it was released with Jira 8.10 EAP. In Jira 8.22 and later, you can set up your OAuth 2.0 integrations in application links. To do this, go to Administration > Applications, and then Application links

For more information on OAuth 2.0 and how to set up your integrations, see Link to other applications.

To add Microsoft as a new integration, you should have an OAuth key and secret from Microsoft Azure. Learn how to generate them


In response to Google and Microsoft planning to deprecate Basic Authentication, we are adding three-legged OAuth 2.0 authentication methods for incoming email. If you currently use email to create issues and issue comments, you will need to reconfigure your incoming mail settings. 

OAuth 2.0 is only available for Jira server 8.10 and later uses HTTPS or TLS. This is to ensure that the creation of tokens is secure.

What if I don’t update my settings?

Once Google and Microsoft disable Basic Authentication, you will not be able to create issues and comments from email and your connection to the Gmail and/or Microsoft Exchange Online server will no longer be operational. You don't need to update the settings in your custom email servers or other service providers if they use IMAP or POP3. They will continue to work.

POP Support for OAuth 2.0 using Microsoft is only available for the following Jira versions:

  • 8.5.12 (or any newer 8.5.x version)
  • 8.13.4 (or any newer 8.13.x version)
  • 8.15.0+

Please check JRASERVER-72033 - Getting issue details... STATUS for more information.


What do I need to do?

You need to configure OAuth 2.0 for your Google and/or Microsoft email server and update your email server configuration. You need to be a system administrator to do that.

You need to configure the OAuth 2.0 settings first. To do that you will require specific info such as a client ID from your service provider. You can generate this data on the service provider’s side. Then, you need to copy the data to the OAuth plugin in your application to generate a redirect URL. You need to provide the redirect URL that your application generated at the service provider’s site. Once you save your configuration, you can proceed to configure your mail server to use OAuth 2.0 as the authentication method.

What are the prerequisites?

You need to ensure the following:

How do I do it?

You first need to add OAuth 2.0 integration for your mail server to use. Next, you need to configure your mail server to use this integration.

Configure OAuth 2.0 for Google, Microsoft, or your own custom server

Using Jira 8.22 or later? To configure OAuth 2.0, follow the steps in Configure an outgoing link.

  1. Go to Jira administration > System > OAuth 2.0.
  2. Select Add new integration.
  3. Select your Service provider.
  4. Enter your integration’s name.
  5. For Google and Microsoft, we will auto-fill the authorization and the token endpoint data. However, if you are using a custom service provider, you need to get this data from the service provider and fill it in yourself.
  6. Copy the generated redirect URL, which you’ll have to provide at the service provider’s site to obtain the client ID and client secret.
    Different providers might have additional requirements related to the redirect URL. For example, Google does not allow it to be a private IP address. Make sure you provide an external URL (for example a load balancer for the Data Center).
  7. Go to the service provider to generate the data to enter on the plugin’s site to complete the integration.
    Google: Go to https://developers.google.com/identity/protocols/oauth2/web-server to learn how to generate the required data.
    Microsoft: Go to https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow to learn how to generate the required data.
    You will need the following data for the integration:

    Scopes - this is the level of the authenticated user data that you allow your service provider to share with the application.

    For Google, we recommend using the https://mail.google.com/ scope for IMAP and POP3. For Microsoft, we recommend https://outlook.office.com/IMAP.AccessAsUser.All or https://outlook.office.com/POP.AccessAsUser.All, and offline_access.

    To learn more about scopes, see detailed information from Microsoft and Google.
    When you complete the application registration process with your provider, you obtain the following unique credentials to authorize the OAuth Client (for example, Jira) with the OAuth Server (for example, Google). Copy and paste them into Jira at the OAuth 2.0 site:
    Client ID
    Client Secret
    If you use a custom service provider, you might need to generate the client ID and the client secret yourself. Make sure that the values are the same on the application and the service provider side.

  8. Save your configuration.

To add Microsoft as a new integration for OAuth 2.0, please review the below steps:

Add Microsoft as a new OAuth 2.0 integration

To add Microsoft as a new integration for OAuth 2.0, check the Jira version you’re using and follow the corresponding instructions.

Jira 8.22 and newer

Follow the instructions on configuring an incoming link

Jira 8.21 and older

  1. Go to Administration > System > OAuth 2.0.

  2. Select Add new integration.

  3. In the Service Provider field, select Microsoft.

  4. In the Redirect URL field, select Copy.

  5. Generate an OAuth key and secret in Azure and go back to Jira. See the following instructions.

Generate an OAuth 2.0 key and secret in Azure

The following are common high-level steps for setting up the OAuth 2.0 application and related parameters in Azure. Please reach out to your MSFT administrator or their documentation and support if you need additional assistance or have questions. The work in Azure is outside of Jira’s support scope.

To get an OAuth key and secret in Azure:

  1. Login to https://portal.azure.com/.

  2. Select App registrations.

  3. Select New registration.

  4. Enter a friendly, easy-to-identify name.

  5. Under Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  6. Under Redirect URI, select Web and insert the URL from step 5.

  7. Select Register.

  8. Select API permissions.

  9. Select Add permission.

  10. Select Microsoft Graph.

  11. Select Delegated permissions.

  12. Select the following permissions:

    1. OpenId permissions: offline_access

    2. IMAP: IMAP.AccessAsUser.All

    3. POP: POP.AccessAsUser.All

  13. Select Add permissions.

  14. Select Grant admin consent for.

  15. In the left menu, select Certificates & secrets.

  16. Select New client secret.

  17. Enter a description and select an expiration date.

  18. Save the generated Value. You’ll use it as the Client secret in Jira. You’ll see the Value only once.

  19. Select Overview.

  20. Save the Application (client) ID. You’ll use it as the Client ID in Jira.

  21. Go back to Jira and complete the configuration by inserting the following details:

    1. Client ID from step 20

    2. Client secret from step 18

    3. Scopes: "https://outlook.office.com/IMAP.AccessAsUser.All", "https://outlook.office.com/POP.AccessAsUser.All" and "offline_access"

  22. Select Save.

  23. Test the connection.

If the connection is successful, proceed with the following steps.

Optionally, check the Microsoft doc on how to get the Client ID and secret.

To add google as a new integration for OAuth 2.0, please review the below steps:

How to setup Jira and Gmail OAuth 2.0

Please find the below-detailed steps on how to configure the OAuth 2.0 integration on Google's side:

The following are common high-level steps for setting up the OAuth 2.0 application and related parameters in Gmail. Please reach out to your gmail administrator or their documentation and support if you need additional assistance or have questions. The work in Gmail is outside of Jira’s support scope.

  1. Navigate to Open the API Library

  2. Find the Gmail API

  3. Click Create credentials > OAuth client ID.

  4. Select Web application as "Application type"

  5. Choose a friendly name

  6. Under the "Authorized JavaScript origins" section, insert the Jira URL

  7. Open a new browser tab, navigate to Jira and login as a user with the Jira System Administrators global permission

  8. Navigate to Administration > System > OAuth 2.0

  9. Click on Add new integration

  10. At the "Service provider", select Google

  11. Click on Copy at the Redirect URL field

  12. Go back to the Google tab

  13. Under the "Authorized redirect URIs", insert the URL copied above

  14. Click on Save

  15. Click on the OAuth consent screen

  16. Select the Jira instance

  17. Make sure the scope *https://mail.google.com/* was added

  18. Go back to Jira, and insert the Client ID and Client secret generated by Google

  19. Under the "Scopes" field, insert *https://mail.google.com/*

  20. Click on Save

  21. Test the connection

Configure your Jira incoming mail server to use OAuth 2.0

Using Jira 8.22 or later? To configure OAuth 2.0, follow the steps in Configure an incoming link.

  1. Go to Jira configuration > System > Incoming mail.
  2. Click Edit next to the mail server.
  3. If you use a Microsoft server, select Custom in the Service provider dropdown.
  4. Select the OAuth 2.0 integration you’ve configured as your authentication method.
  5. Click Authorize to give Jira access to mail.
  6. Log in to the mailbox's mail account. This should display the service provider’s popup asking you to allow Jira to access the account. Click Allow.
  7. To verify that everything works, click Test connection. If the connection doesn't work, you will be unable to save your settings.
  8. Click Save to complete the process.

Configure Jira Service Desk to use OAuth 2.0

For Jira Service Desk projects, you’ll need to reconfigure email channels that allow customers to create requests via email. This can be done by a Jira admin, for each project separately.

  1. Open your desired Service Desk project.

  2. Go to Project settings > Email requests. There can only be one email channel for a project, so you should see the details of your current channel.

  3. Change the authentication method to the OAuth 2.0 integration that you created earlier (Administration > System > OAuth 2.0). 

    When adding your email account, you need to be able to authenticate to the email service provider used in your OAuth 2.0 integration.

  4. Click Update to save the changes, and then Authorize (if you’re creating a brand new configuration, these actions will be called Save and authorize).

  5. Log in to your email account. Unlike basic authentication, it can’t just be any email address. It must belong to a domain that was configured in the OAuth 2.0 integration.

  6. Once authorized, you will see a success message about the channel is enabled. Your customers should now be able to create their requests via email.

Is there anything else I need to do as a plugin vendor?

Check whether you need to go through the Google verification process for your app. This might be needed if your app uses sensitive user scopes and is available to external users. Unless the app is internal only, you might need to pay for the verification. See Google OAuth 2.0 verification process.

If your app provides a custom mail handler, the OAuth 2.0-related changes should not affect it. This feature doesn’t deliver any new API, and it’s up to the admin to set the mail handler to use the updated mail server.

Known issues

It's possible that the connection to the mail server breaks. If it’s not because your token has expired, you need to renew your consent. Go to Jira configuration > System > Incoming mail, click Edit next to the mail server and click Authorize.

Last modified on Mar 27, 2023

Was this helpful?

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