Communicating with Atlassian products from an external program, website or script is mostly straightforward thanks to the well-documented REST API’s these products provide. While most of time when you see instructions in the web about how to access one of these product’s REST API from an external application or script, authentication is done by using plain username/password with basic authentication. While this is certainly an easy way to authenticate, it is much better to use OAuth.

While Atlassian’s cloud solutions like Bitbucket Cloud make it very easy to use OAuth, the behind-the-firewall editions of Atlassian products like Bamboo Server make this significantly harder — yet not impossible. In this blog post, we will show you how you can access Bamboo’s REST API with OAuth1. To achieve this, we’ll make use of application links. Although we have chosen Bamboo here, the basic procedure is the same for JIRA, Confluence and Bitbucket Server.

Why should I use OAuth?

The main advantage of OAuth compared to using username/password is that you never have to expose a user’s credentials when accessing external websites. Instead of passing a user’s name and password with a request, OAuth allows us to use a security token to access specific resources for a predefined duration. So the main benefit for end-users is security: if the website (and hence your access token) you are using ever gets compromised, then you can simply revoke your token. And the attacker will never have access to your account on this website (at least as long as the website provider got this right).

How to create an application link to use OAuth

There is no native support for creating and maintaining OAuth in Atlassian’s behind-the-firewall products as users know it from Bitbucket or Github. But there is a possibility to make authentication with OAuth1 possible by using application links. As an example, let’s create an application link for Bamboo. Go to the application links admin page of your Bamboo instance and create a new application link with the following parameters:

Creating a new application link in an Atlassian product to support OAuth access.

As you can see, you can just use any application URL. For the request, access and authorize URL’s you should use the following:

• Request Token URL: http://YOUR_BAMBOO_SERVER/plugins/servlet/oauth/request-token
• Access Token URL: http://YOUR_BAMBOO_SERVER/plugins/servlet/oauth/access-token
• Authorize URL: http://YOUR_BAMBOO_SERVER/plugins/servlet/oauth/authorize

If you now click on continue, a new dialog comes up:

The credentials one has to enter when creating an OAuth-based application link.

Just enter a consumer key and name of your choice. For the public key, generate one like follows:

Create public key with OpenSSL

Paste the content of your public key into the field of the dialog. Now, click “Continue” and you should see a newly created application link. This link will now allow us to access Bamboo’s REST API using OAuth.

Example of a Python client using OAuth

Of course, we now also want to verify that authenticated access with OAuth to Bamboo’s REST API works. We will now show how to do this with Python. For this, we use the OAuthlib support for Python’s famous requests library.

The first step of the OAuth dance is to create a request token:

Create an OAuth request token with Python

This will open a page in Bamboo in your default web browser where the end user has to authorize that requests using this token will run under the user's permissions:

A confirmation screen to authorize Bamboo to run this action under the user’s permissions.

The last step of the OAuth dance is to generate the access token which we will later use to authenticate against Bamboo's REST API:

Create an OAuth access token with Python

Finally, we are able to authenticate with a token instead of passing the user's credentials when using basic authentication:

Authenticate with OAuth and Python for an Atlassian application

As you can see, with some additional work, you can now get rid of exposing the users credentials and use the generated access token in your applications. Just be aware that you cannot restrict the scope of an access token in any way as you are used to from Github / Bitbucket where fine-grained permission scopes are available. By using the access token, you can do anything the user is allowed to do. Also keep in mind that there is no easy way to restrict the token's duration for a specific amount of time.

If you ever have to revoke the token, go to your profile and you will see all your granted tokens in the tab OAuth Access Tokens:

Screen to revoke OAuth access tokens in Bamboo.

From now on, there is no excuse anymore to use plain old username/password access, even in shell scripts. Just do the OAuth dance :-)