Press CTRL+K to open search

Jira Cloud Prerequisites

  • 5 minute(s) read
Prev Next

Overview

This article describes the necessary prerequisites for configuring a Jira Cloud connector in Nucleus to use OAuth authentication. OAuth 2.0 is the recommended authentication method for all Jira integrations. Legacy authentication methods (such as OAuth 1.0a) may result in reduced performance, limited support, and weaker security, and should only be used when OAuth 2.0 is not supported.

Connecting to Jira using OAuth 2.0 (Recommended)

In order for Nucleus to authenticate to Jira using OAuth 2.0 authentication, you must enable OAuth 2.0 in Jira for the Nucleus application. This will be used later when creating a Jira connector in Nucleus.
Follow the steps below to enable OAuth 2.0 in Jira:

  1. Log in to developer.atlassian.com, select your profile icon in the top-right corner, and from the dropdown, select Developer console.
  2. Click the Create button, then select OAuth 2.0 integration.
  3. Enter a Name for the integration, for example 'Nucleus', then click Create:
    image.png
  4. Under OAuth 2.0 (3LO) grant type, select Resource-level grant. This limits the integration to the specific Jira site(s) selected during user authorization, which is required for Nucleus.
  5. Click Create:

oauth2Create.png

  1. Select Distribution from the left navigation panel.

  2. You'll see your app is listed as private by default. To continue:

    1. Click Edit
    2. Select the Sharing option
    3. Enter 'Nucleus' as the Vendor Name and
    4. Set 'https://nucleussec.com/privacy-policy/' as the Privacy Policy.
    5. Click Save Changes:
      image.png

  3. Select Permissions from the left navigation panel, then click Add next to the Jira API option.

  4. Click the Configure button. The Classic scopes tab is displayed by default.

  5. In the Jira platform REST API section, click Edit Scopes at the top-right, check the View Jira issue data, View user profiles, and Create and manage issues scopes, then click Save.

  6. In the Jira Service Management API section, click Edit Scopes, check the View Jira Service Management request data scope, then click Save:
    jira_cloud_scopes_classic.png

  7. Select the Granular scopes tab, then click Edit Scopes. Use the Search by name or code box to find read:cmdb-object:jira, check the Read Assets objects scope, then click Save:
    jira_cloud_scopes_gran.png

  8. Confirm that Scopes Used at the top of the Jira API page shows 5. See Required OAuth 2.0 Scopes below for the full list.

  9. Select Authorization from the left navigation panel and you'll see OAuth 2.0 listed as an Authorization type. Under Action, click Add.

  10. Paste the Redirect URL copied from Nucleus into the Callback URL option, then click Save Changes.

  11. Select Settings from the left navigation panel, then copy the Client ID and Secret, you will need these to complete setting up the connector in Nucleus:
    image.png

Required OAuth 2.0 Scopes

Scope Console label Where to find it Purpose
read:jira-work View Jira issue data Classic scopes → Jira platform REST API Read projects, issue types, and field metadata
write:jira-work Create and manage issues Classic scopes → Jira platform REST API Create and update tickets
read:jira-user View user profiles Classic scopes → Jira platform REST API Resolve users for assignee fields
read:servicedesk-request View Jira Service Management request data Classic scopes → Jira Service Management API Locate the Jira Service Management Assets workspace
read:cmdb-object:jira Read Assets objects Granular scopes Read values for Assets/CMDB-backed custom fields
offline_access (not configured in the console) — Enables refresh tokens; requested automatically by Nucleus
All scopes are required

Every scope listed above must be enabled before you connect, including View Jira Service Management request data (read:servicedesk-request) and Read Assets objects (read:cmdb-object:jira). These two allow Nucleus to read the available values for Jira Service Management Assets/CMDB-backed custom fields.

Nucleus requests the full set of scopes during authorization, and Atlassian fixes the granted scopes at that time. A connector authorized with a partial set will fail, and scopes cannot be added to an existing connector without re-authorizing it.

You are now ready to continue creating a Jira connector in Nucleus.

Legacy Authentication Methods

The following authentication methods are supported for backward compatibility but are not recommended for new integrations.

Connecting to Jira using OAuth 1.0a (Legacy)

OAuth 1.0a Deprecation Warning

OAuth 1.0a is a deprecated authentication protocol and should not be used. This method may result in reduced performance, limited support, and weaker security compared to OAuth 2.0.

OAuth 2.0 authentication is highly recommended for new Jira connectors, and existing connections using OAuth 1.0a should be updated.

Migrate to OAuth 2.0

To migrate an existing connector:

  1. Navigate to your Nucleus project, then Integrations > Connector Setup
  2. Edit your Jira connector by clicking the pencil icon
  3. Select OAuth 2.0 as the authentication method
  4. Follow the prompt to complete the OAuth 2.0 setup steps

Re-authentication is required when switching authentication methods.

In order for Nucleus to authenticate to Jira using OAuth 1.0a authentication, you must create an application link in Jira. This will be used later when creating a Jira connector in Nucleus.

Follow the steps below to create an application link in Jira:

  1. Login to Jira as an administrator and navigate to Jira Settings page.

  2. Click on the Products link.

  3. Click Application Links

  4. Enter the URL of the Nucleus instance you have been assigned then click Create new link.

  5. In the popup, click Continue.

  6. On the Link Applications popup:

    1. For Application Name:, enter 'Nucleus'.
    2. For Application Type:, select 'Generic Application'.
    3. Check the Create Incoming Link checkbox at the bottom
    4. Click Continue

  7. On the next screen, complete the following fields then click Continue:

    1. For Consumer Key, enter a 15 character (or more) password of your choice.
    2. For Consumer Name, enter 'Nucleus'.
    3. For Public Key, enter the public key displayed in Nucleus on the Properties tab of the New/Edit Connector dialog.

  8. Click Continue to finish setting up your application link in Jira.

OAuth 1.0a Troubleshooting

Note: Support for OAuth 1.0a will be removed in a future release.

When using OAuth 1.0a, Nucleus communicates with your Jira Server over HTTPS and relies on a callback from Jira to complete authentication.

Your Jira Server must be able to establish outbound HTTPS connections (port 443) to your Nucleus instance. If your Jira instance is not internet-facing, firewall or network restrictions may prevent this connection and cause authentication to fail.

Ensure that outbound connectivity to Nucleus over port 443 is allowed. This is not required when using OAuth 2.0.

You are now ready to continue creating a Jira connector in Nucleus.

Basic Authentication

Important

Basic Authentication should only be used when OAuth cannot be supported. Nucleus recommends using a dedicated service account (for example, Nucleus Bot) rather than a personal user account.

  1. In Jira Cloud, identify the user account that Nucleus will use for ticket creation and updates.
  2. Generate an API token. This will be used as the password when authenticating via Basic Auth.
  3. Copy the Email Address and API Token for the account.
  4. When configuring the connector in Nucleus, select Basic Auth, then enter the Email Address and API Token in the corresponding fields.

For more information, refer to Atlassian’s documentation on managing API tokens for Jira Cloud.

You are now ready to continue creating a Jira connector in Nucleus.