Skip to end of metadata
Go to start of metadata

Applicable:

JIRA 5.0 and later.

This tutorial describes how to use a Java client to provide OAuth authentication when making requests to JIRA's REST endpoints. It assumes you are familiar with the OAuth terminology (e.g. Consumer, Service Provider, request token, access token, etc.). For more information about OAuth refer to the OAuth specification.

Looking for a Provider in a Language other than Java?

Atlassian provides samples of OAuth providers in a number of other languages. Visit the sample repo on Bitbucket to download and work with these samples.

 

Step 1: Configuring JIRA

The first step is to register a new consumer in JIRA. This is done through the Application Links administration screens in JIRA. Create a new Application Link.
When creating the Application Link use a placeholder URL or the correct URL to your client, if your client can be reached via HTTP and choose the Generic Application type. After this Application Link has been created, edit the configuration and go to the incoming authentication configuration screen and select OAuth. Enter in this the public key and the consumer key which your client will use when making requests to JIRA.
After you have entered all the information click OK and ensure OAuth authentication is enabled.

Step 2: Configuring the client

Your client will require the following information to be able to make authentication requests to JIRA.

OAuth Config

value

request token url

JIRA_BASE_URL + "/plugins/servlet/oauth/request-token"

authorization url

JIRA_BASE_URL + "/plugins/servlet/oauth/authorize""

access token url

JIRA_BASE_URL + "/plugins/servlet/oauth/access-token"

oauth signing type

RSA-SHA1

consumer key

as configured in Step 1

Example Java OAuth client

This example java code demonstrates how to write a client to make requests to JIRA's rest endpoints using OAuth authentication.
To be able to use OAuth authentication the client application has to do the "OAuth dance" with JIRA. This dance consists of three parts.

  1. Obtain a request token
  2. Ask the user to authorize this request token
  3. Swap the request token for an access token

After the client application has a valid access token, this can be used to make authenticated requests to JIRA.

Configuring JIRA and downloading the example client

This example client is using the consumer key "hardcoded-consumer" and the public key is:

You have to create an Application Link as described in Step 1 above and use this consumer key and the public key and leave the callback URL field empty.

Download the attached jar files:

  File Modified
Java Source rest-oauth-client-1.0.one-jar.jar Sep 27, 2011 by Felix Schmitz [Atlassian]
Java Source rest-oauth-client-1.0-sources.jar Sep 27, 2011 by Felix Schmitz [Atlassian]


The rest-oauth-client-1.0.one-jar.jar contains the sample client and the rest-oauth-client-1.0-sources.jar contains the source code.

1. Obtain a request token from JIRA

Execute this command:

Replace JIRA_BASE_URL with the URL to your JIRA instance and replace CALLBACK_URL with the URL that should be called after the user has authorized the OAuth request token.
After executing this command you should see a response like

2. Authorize this token

Go to the URL in system out and login into JIRA and approve the access. Afterwards JIRA will say that you have successfully authorised the access. It mentions a verification code which we need for the next step.

3. Swap the request token with an access token

Execute the following command

Replace JIRA_BASE_URL, REQUEST_TOKEN, TOKEN_SECRET and VERIFIER with the correct values.

In the response you should see

This access token will allow you to make authenticated requests to JIRA.

4. Make an authentication request to a rest-end point

To make an authenticated request to a rest resource in JIRA execute this command:

Replace ACCESS_TOKEN, JIRA_REST_URL and ISSUE_KEY with the correct values.
JIRA_REST_URL, e.g. http://localhost:8090/jira/rest/api/2/issue/HSP-1
This will return the issue JSON object for the issue with the key "HSP-1"

You should see a response like:

How to add OAuth support to your client

I suggest if you want to use OAuth to make request to JIRA to find a helper library which takes care of signing the requests and reading the tokens from the response.
The example above is using the net.oauth library.

  • No labels

4 Comments

  1. Anonymous

    On Step 1 I get an exception stating oauth_problem="consumer_key_unknown" . 

    1. You have to add your application link

  2. Anonymous

    The examples on BitBucket referenced above are really good. It helped us getting up and running in a matter of hours.

    We got stuck on the occations below:

    • Generating the keys. Solution (on Linux):
              openssl genrsa -out RSA.pem 1024
              openssl rsa -in RSA.pem -pubout -out RSA.pub
      The RSA.pub key is the one entered in the JIRA Application Link
      The RSA.pem key is the one used when  performing the next step and when using the app.
    • Performing the token dance. Solution:
      We went with the Python app at BitBucket because we wanted to integrate jira-python.
      But running the Atlassian supplied app was a breeze and we got everything needed right away.
      One issue though: The app gives a REST link to an issue which is wrong (at least with JIRA 6):

         data_url = 'http://localhost:8080/rest/api/latest/issue/ALM-100'

    Maybe this can help others attempting this. At least once it is done once, the path for creating more applications interfacing to JIRA is wide open.

  3. what is the correct way to generate the customer key?