Integrating with OAuth 2.0

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can integrate your application with OAuth 2.0 authentication to connect with 3rd party apps, such as your mail server. We only support 3-legged authentication.

OAuth 2.0 is only available for Jira server 8.5.9 (and further versions of 8.5.x), and 8.10 and later that use HTTPS or TLS. This is to ensure that the creation of tokens is secure.

Disabling Basic Authentication 

Some providers such as Google and Microsoft are planning on disabling Basic Authentication. When they do, 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 do not 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.

Currently, Jira does not support OAuth 2.0 for Microsoft Exchange Online via POP3. You can either continue using Basic Authentication until the support is provided or connect to the mail server using IMAP and then integrate with OAuth 2.0.


Integrating with OAuth 2.0 process for mail server

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 configuring your mail sever to use OAuth 2.0 as the authentication method.

Prerequisites

You need to ensure the following:

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

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.

  1. Go to Jira administration > System > OAuth 2.0.
    OAuth 2.0 integrations page in the Jira administration console.
  2. Click 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 obtain 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. 

    If you are configuring a custom service provider, click Generate to receive the redirect URL.


    Your redirect URL is endpoint-dependent. If you change the authorization of the token endpoint, the redirect URL needs to change as well. Click Generate to get a new URL. 

Different providers might have different 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 of a load balancer for 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 example, it can be:

    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 the detailed information at the Microsoft & Google sites.

When you complete the application registration process with your provider, you obtain the following unique credentials to authorise OAuth Client (for example, Jira) with the OAuth Server (for example, Google). Copy and paste them in 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.

9. On the OAuth 2.0 integrations page, click Test connection to make sure the connection works. 

If you're configuring OAuth 2.0 to connect to a mail server, you can select your integration as the Authentication method for this incoming mail server. Go to Jira configuration > System > Incoming mail to configure your server. 

For details on how to reconfigure Jira Service Management's email channels to use your OAuth 2.0 integration, see Receiving requests by email.

OAuth 2.0 settings details

Setting

Notes

Resource provider

Select Google or Microsoft if it’s applicable, or use Custom for other integrations

Name

A unique name for this integration.

Description

(Optional)

Client ID

The client ID generated by the provider. This is the public identifier of the application on the provider side.

Client Secret

The Client Secret generated by the provider. This is the shared secret between the application (such as Jira) and the provider ensuring the authorization is secure. This will not be viewable after saving.

Scopes

The required OAuth 2.0 scopes for interacting with the provider. Learn more about scopes.

Authorization Endpoint

The HTTPS URL where authorization to use OAuth 2.0 is started.

Token Endpoint

The HTTPS URL where refresh token requests are sent. As OAuth 2.0 tokens have an expiry, Jira will periodically update the token.

Redirect URL

The redirect URL that must be saved on the provider side. This redirects the authentication flow back to Jira to complete the initial process.

Troubleshooting

Last modified on Dec 15, 2021

Was this helpful?

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