Jira OAuth2 connection guide

Owned by Peter Atthem
2023-11-23
4 min read

If you want to connect and collaborate with Jira instances other than the one where the iHub app is installed, or if you need to access certain APIs that the app doesn't reach by default, you can use a more secure method called OAuth2 connection, which is safer than the PAT token version.

The OAuth2 connection involves two steps. First, you need to add what Atlassian calls an "app" of the type OAuth 2.0. In simpler terms, think of it as creating a special key that allows your iHub app to talk securely to other Jira instances. You also configure what kind of permissions this key, or "app," will have using Scopes.

The second part is connecting this key to your iHub app by using your iHub credentials. This connection allows the app to get an access token, which is like a digital pass, and it will automatically get a new one when needed. This way, your connection stays secure without you having to do anything manually.

Part 1. Prepare iHub

  1. Click on Credentials

  2. Click Add Credential

  3. Select OAuth as the type

  4. Name it something, like Site X

  5. Click Create

  6. Select grant type Authorization Code Grant

  7. Copy the callback URL on the page, you will be needing it in the next part.

Part 2. Setting up the OAuth 2.0 App in Atlassian

  1. Goto https://developer.atlassian.com/

  2. Login with the account that shall own the app and for the sake of simplicity the one that will be authorizing the app.

  3. Click Create button and select OAuth 2.0 integration

  4. Click on Permissions, click on Add on the Scope that you want the app to. Use Classic if you are unfamiliar with the fine graned scopes.

  5. Click on Authorization menu

  6. Click Configure

  7. Paste in the callback URL copied from the prepare step to the iHub credential.

  8. Save the configuration

Part 3. Finalize the OAuth 2.0 Connection

  • Go back to iHub and open the Credential that you created in part 1

  • In Authorization URL enter: https://auth.atlassian.com/authorize?audience=api.atlassian.com&prompt=consent

  • In Access Token Url enter: https://auth.atlassian.com/oauth/token

  • In Client Id enter: click on Settings in the app in Atlassian and copy the client id (the app created in part 2)

  • In the Client Secret enter: click on Settings in the app in Atlassian and copy the client secret (the app created in part 2)

  • In the Scope enter the selected scope from step 4 in Part 2. example
    read:jira-work manage:jira-project manage:jira-configuration read:jira-user write:jira-work manage:jira-webhook manage:jira-data-provider
    Scopes are named with action colon and then resource, each scope is separated with a space.

  • Uncheck Include Scope when requesting an access token

  • Select body (json) in the Make access token request with select list

  • Check Include state

  • Click Save


Part 4. Grant access by Authorizing

  1. Click on the blue button “Click here to authorize”

  2. Select the site you are connecting to, must be site where the oauth app is installed on, form part 2.

If all goes good you will have a green light like the image below

If it goes bad you will get the red light, like the image below.

If you get FAILED, then check the credentials that they are copied as it should and make sure that the checkboxes and dropdown are selected as it should be and try authorize again.

 

Making request to the Atlassian api

First thing you need to do is to find your cloud id!

Make a GET request to https://api.atlassian.com/oauth/token/accessible-resources using you newly created OAuth2 credential.

Response will include the id which is your cloud id, copy that.

Next to send any API call use the format like below.

https://api.atlassian.com/ex/jira/YOUR_CLOUD_ID/rest/api/3/myself

Base URL will not work, you must use the api format above!

 

 

Reference https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/