Make your 3rd party application compatible with application links
Application Links is a bundled app that allows you to connect Bitbucket Data Center and Server and other Atlassian tools to set up links, share information, and provide access to resources or functionality.
On this page we use Jenkins as an example to explain how to:
Make your 3rd party application compatible with application links using OAuth 1.0
Create an outgoing application link from Bitbucket to your 3rd party application.
This page explains how to set up a 3rd party application as an OAuth provider. It doesn't explain how to set it up as an OAuth consumer as this can be done easily using existing libraries.
What about OAuth 2.0?
Application links now also support OAuth 2.0 when linking to external applications. If you’re looking to update your integrations to use this protocol, you can find the details of our OAuth 2.0 implementation in Bitbucket OAuth 2.0 provider API.
Terms used in this article
OAuth 1.0a - OAuth is an open standard for access delegation. It's commonly used as a way for Internet users to grant websites or applications access to their information on other websites without giving them their passwords. Application Links is based on OAuth 1.0a, and all references to OAuth in this article relate to this protocol.
Resource owner - An end user who owns the resource. For example, a Jenkins Job.
Client - An application that makes OAuth calls on behalf of a resource owner.
OAuth provider - An application that allows a client to create a token that will be used later for authentication.
OAuth consumer - A client that is an OAuth consumer. The OAuth consumer will ask the OAuth provider for various tokens. These tokens will be explained later.
3-legged OAuth dance - This process is explained on Github in these diagrams.
Application link options
Before you jump into making your application compatible with application links, it’s useful to understand some details about app links themselves.
Your application link can be:
Outgoing/incoming, or both.
Automatically created or manually created.
Outgoing/incoming, or both
If an Application Link is outgoing/incoming (outgoing for one application, incoming for the other application), only one party can perform actions on the other. If it’s both outgoing and incoming, like in Atlassian products, both parties can perform actions on each other.
In our Jenkins example, the Application Link is outgoing/incoming. It is:
Outgoing from Bitbucket, the OAuth consumer | → | Incoming for Jenkins, |
In this arrangement:
Jenkins provides access tokens to Bitbucket. Jenkins users are resource owners while the Jenkins server acts as an OAuth provider.
Bitbucket consumes these tokens and uses them to perform actions on Jenkins.
Jenkins, however, cannot perform actions on Bitbucket.
This also means that Jenkins needs to manage token creation and handling, and it needs to expose endpoints to generate request tokens, to generate access tokens, and for authorization.
Automatically created or manually created
When connecting Atlassian applications, Application Link creation is automatic. How this works is explained in the Jira documentation.
When connecting Atlassian applications with 3rd party applications, the Application Link must be created manually. An example of how to do this is explained in our plugin readme.
In our Jenkins example, Jenkins is an OAuth provider only, so the Application Link needs to be created manually. This process can be tedious, but it only needs to be done once.
Making your 3rd party application compatible with application links
To make your 3rd party application compatible with application links:
Decide if the Application Link from Bitbucket needs to be outgoing, incoming, or both.
Implement OAuth:
For an outgoing link from Bitbucket, your 3rd party application needs to be configured as an OAuth provider.
For a bidirectional link from Bitbucket, your 3rd party application needs to be configured as an OAuth provider and also needs to act as an OAuth Consumer.
See below for how to do this:
Configuring your 3rd party application as an OAuth provider
To be an OAuth provider, your 3rd party application needs to:
Do token handling.
Have exposed endpoints:
To generate request tokens
To generate access tokens
For authorization to generate authorization code.]
For a more concrete example of how this can be done, take a look at the OAuth provider guide that we’ve written for our integration plugin for Jenkins. It explains how you can potentially copy and reuse the Application Link module to quickly configure your 3rd party application as an OAuth provider.
Configuring your 3rd party application as an OAuth consumer
There are many libraries that work out of the box for configuring your 3rd party application as an OAuth consumer. For example, Scribe.
Once your 3rd party application is an OAuth provider and consumer, you can manually create a bidirectional Application Link between it and Bitbucket and perform actions on both ends.