• Products
  • Documentation
  • Resources

Integrate with self-hosted tools using OAuth

Note that:

  • The info on this page is only for integrating Jira Software Cloud with on-premise/data center tools. If you‘re using a cloud-based tool for your CI/CD pipeline, see this page instead or check the Atlassian Marketplace.

OAuth credentials allow you to integrate your Jira Software Cloud site with self-hosted development and build tools like Bitbucket Data Center and Jenkins. This means you won’t need to open your firewall or install a third-party add-on to associate development or release information with Jira issues.

This is a system-to-system integration, and isn’t associated with any Jira user. This means it will continue to work regardless of any changes to your user-base.

Before you begin

You must be a site admin for Jira Cloud, as well as an admin for the tool you wish to integrate with.

Create OAuth credentials in Jira Cloud

To create OAuth credentials:

  1. Select > Apps.

  2. From the sidebar, select OAuth credentials.

  3. Select Create credentials.

  4. Enter the following details and click Create.

    • App name - The name of the tool. This will display in your list of credentials.

    • Data Center base URL -  A URL to the tool you're integrating with, used for future actions from the Jira issue view. 

    • Logo URL - A URL to the tool’s logo, which will be used as an icon in the list of credentials.

    • Permissions - The permissions that the app has to call the DevOps related APIs.

Oauth

Your OAuth credentials will include a client ID and client secret.

Update OAuth credentials permissions

You can update your OAuth credentials permissions by adding or removing permissions for a tool. Adding a new permission will give the tool access to start sending in the type of data granted by the permission (e.g. deployment information). Removing a permission will revoke the tool’s access to send in the type of data that was granted by the permission.

To update your OAuth credentials permissions:

  1. Log in to Jira select > Apps.

  2. From the sidebar, select OAuth credentials.

  3. In the three-dots menu under Actions, select Edit permissions.

  4. Update the permissions you want to add or remove and select Save.

When a permission is removed, the following will happen:

  • The tool will stop sending in the type of data that was allowed under the permission.

  • Any data that was previously sent to Jira via the removed permission will be kept, however it will no longer be visible in your projects (e.g. build information in the development panel).

  • If you add the permission back, your old data will be visible again in Jira, plus any new data going forward. However, any data that was created during the period the permission was removed will not be available.

Scopes

Each OAuth Credential (2LO) that you create is tied to a specific set of scopes, or what APIs you'll be allowed to use when sending requests to Jira.

You can only use the OAuth Credentials (2LO) to send data about build, deployment, development, and feature flag information, and associate that to Jira issues using the Builds API, Deployments API, Development Information API, Feature Flags API and Remote Links API.

How it works

After OAuth credentials are created in Jira, they must be copied to the tool you wish to integrate with.

At a high level, this is how it works:

  1. You create OAuth credentials in Jira for your tool.

  2. You copy these credentials to the tool you want to integrate with.

  3. The credentials must be referenced in a plugin or script, which triggers Jira-related data to be sent back to Jira.

By using OAuth, you get the following benefits:

  • Your Jira instance is secure, because the tool you integrate with doesn't have complete control over your Jira Cloud instance.

  • Your Jira data is secure, because the tool you integrate with doesn't have any read access to Jira Cloud. The only data that is exchanged is the issue-related information that is sent from the other tool to Jira.

Additional Help