What changed?

Starting with version 8.3, the system authentication mechanism provides in-app authentication based on JWT.  Cookie-based authentication is replaced with JWT based authentication transferred by the Authorization header.

Authentication token has 15 minutes expiration time. When the authentication token expires, a refresh token is used to query the new authentication token.

Impact

In order to successfully use automation (and communicate with our API) an additional authorization step is required. 

Instructions

When any client starts using the service it should authenticate under /system/auth endpoint (e.g., https://yourjira.com/rest/softwareplant-bigpicture/1.0/system/auth) 

Step one - authentication request

  1. Use the GET/ system/auth request (cookie: JSESSIONID which represents a session in Jira where BP/BG/BT is working). 
  2. As a response, you will receive either:
    1. two tokens
      1. authentication (valid for 15 min)
      2. refresh (valid for 7 days) 
    2. HTTP 401 → If Jira doesn't prohibit it, you can use basic authentication instead of using cookie JSESSIOND  - forward to request username and password.

{
    "authentication": "$authenticationJWT",
    "refresh": "$refreshJWT"
}
CODE

/system/auth endpoint is free of authentication filter for application. 

Step two - implementation

  1. A valid authentication token should be attached to the Authorization header for every BigPicture/ BigGantt/ BigTemplate request - the authorization header must contain the value of the authentication field (received as a response from system/auth).  
  2. Because our applications function in the Jira environment, the JSESSIONID cookie still has to be forwarded to our endpoints. 

Step three - token refresh

An authentication token is valid for a limited time. Query for an authentication token refresh when it expires.

  1. When the token expires, API will respond with an HTTP 401.
  2. Query /system/reauth endpoint using refresh token in Authorization header. Use the refresh token (the value of the refresh field received as a response from system/auth) for authorization → GET /system/reauth request. 
  3. The response will contain a new authentication token. Use it as described in step two above.


{
    "authentication": "$authenticationJWT"
}
CODE