Step By Step Guide to Setup REST API Authentication on Jira

Jira provides REST APIs to perform number of operations such as Create Issue, Add Comment, Raise a ticket, etc. However, it supports only two authentication methods for REST APIs:

  1. Basic Authentication
  2. Using Jira as OAuth 1.0 Provider

 
The REST API Authentication plugin for Jira allows you to use any third party OAuth 2.0 provider/ OpenID provider to authenticate REST APIs.

Benefits of using REST API Authentication add-on:

  1. Secure: This is more secure than Basic Authentication as user’s credentials are not passed with every API request. The add-on only requires access token generated by OAuth 2.0 Provider/ OpenID Provider.
  2. Flexible:  It allows you to use any third party OAuth 2.0 provider/ OpenID provider for authentication and not just Jira.
  3. Overall Protection: The plugin also blocks the basic authentication requests such that no one without a valid access token can use any REST API.
  4. SSO Compatible: If you’re using Single Sign-On on Jira, you can configure your Identity Provider to provide authentication for REST APIs as well.

 
The REST API Authentication flow involves these two simple steps:

  1. Request Access Token from OAuth 2.0/OIDC Provider
  2. Call Jira’s REST API using this access token

 

Steps to set up OAuth 2.0/OpenID Connect authentication using miniOrange REST API Authentication add-on for Jira:

Note: I’ve used miniOrange OAuth Provider as an example here. The add-on supports any custom OAuth 2.0/OpenID connect provider such as Azure AD, Keycloak, Okta, Gsuite (Google apps), AWS Cognito, Github, Gitlab etc.

  • Step 1: Setup OAuth flow between your Client Application and OAuth 2.0/OpenID Connect provider

    1. Client Application: It’s a service or user who wants to access Jira’s REST API.
    2. You will need to set up OAuth flow between miniOrange and your client application. The client application is any service or user calling Jira’s REST API.
    3. It will be used to authorize the user and get access token Note: This flow will be set up between your client application and miniOrange OAuth provider. The REST API Authentication add-on is not involved in this process. If your application doesn’t support OAuth 2.0, just drop us an email at info@xecurify.com.
    4. Set up miniOrange as OpenID provider using step by step guide on this link: Setup miniOrange as OpenID Connect Provider
    5. After setting up miniOrange as OAuth provider, go to Apps Manage Apps. Click on the Edit link beside your the app you created in miniOrange
    6. Copy the Userinfo Endpoint.
  • Step 2: Configure Introspection Endpoint in the REST API Authentication add-on:

    1. Introspection Endpoint: An introspection endpoint is any endpoint of the OAuth/OpenID provider which can be called using access token and returns username in response.
    2. Select Custom OAuth Provider in the OAuth Provider Setting tab
    3. Enter the Userinfo endpoint we copied in the step 1 in Introspection endpoint field. It looks like this.
      https://login.xecurify.com/moas/rest/oauth/getuserinfo
    4. The userinfo endpoint of miniOrange returns a response like this:
      {
      "sub": "demouser",
      "firstname": "Demo", 
      "email": "demo@example.com",
      "username": "demouser",
      "lastname": "User"
      }
    5. Username Attribute: This key in introspection endpoint response tells plugin which user is making the API call.
    6. In the above response, username attribute contains the Jira username of person making the API call. Hence username is entered as username attribute. So the plugin will know that Jira user demouser is making an API call.
  • Step 3: Fetch Access Token from miniOrange OAuth Provider

    1. Initiate OAuth flow with miniOrange. This OAuth Flow looks like this:
      OAuth Flow
    2. At the end of this flow, an access token will be returned to your applications redirect URI configured in miniOrange
    3. A sample access token from miniOrange OAuth provider looks like this:
      A834c0606ba71336423013699db8e971

     

  • Step 4: Use Jira’s REST API using access token:

    1. Call Jira’s any REST API. Include the access token in Authorization header. Here’s an example of create issue API:
      Request:

      curl \
      -X POST \ 
      -H "Authorization: Bearer <Access Token>" \
      -H "Content-type: application/json" \
      --data {see below} \
      http://localhost:8080/rest/api/2/issue/ \
      

      Input Data:

      {
          "fields": {
             "project":
             {
                "key": "TEST"
             },
             "summary": "REST ye merry gentlemen.",
             "description": "Creating of an issue using project keys and issue type names using the REST API",
             "issuetype": {
                "name": "Bug"
             }
         }
      }
      
    2. The add-on will validate the access token
    3. The issue will be created if the access token in valid
    4. If the token is invalid or missing, the call will return a 401 Unauthorized response

Here’s the flow diagram of REST API Authentication using miniOrange plugin