REST API Authentication Script

Overview

This article is for anyone making basic Jira REST API calls that have not explored the use of sessions. While the ideas in this blog can also be used for tools like Postman and Paw, it is focused on terminal use.

Basic use of REST API

Below is an example of the normal usage of Jira REST API calls using curl passing in the user's credentials in plain text (or optionally, base 64 encoded). This has the result of authenticating against the Jira Server and creating a new session for the REST API call to execute.

# example REST call to retrieve project 'MYPROJECT' information using credentials
curl -u 'username:password' \
    -H 'Accept: application/json' \
    'https://jira.random.xyz/rest/api/2/project/MYPROJECT'
    

Authentication Script

The authentication script is a simple procedure that uses Jira's REST API cookie-based authentication to create a session and store it in an environmental variable for use. Script details including prerequisites are listed below.

Prerequisites

To make it easy to parse the JSON result for the authentication call, I use jq, the lightweight and flexible command-line JSON processor which you can download directly, install through your operating system package manager, or use Homebrew if you're using macOS.

Procedure

The script below will perform the following actions:

• Gather user credentials (so that they don't have to be stored in the script)
• Perform REST authentication call to Jira server with user credentials to create the session
• If successful, set an environmental variable called 'JIRA_SESSION_COOKIE' with the resulting session ID

Go ahead and create a script called 'createJiraSession.sh' with the following contents:

#!/bin/sh
# set URL of Jira instance
JIRA='https://jira.random.xyz'
# gather credentials
printf "Create Jira authentication cookie for: ${JIRA}\n"
>printf 'Jira Username: '
read USER_NAME
printf 'Jira Password: '
read -s PASSWORD
# retrieve user session from Jira
OUTPUT=`curl -Ss -X POST \
-H 'Content-Type: application/json' \
-d "{\"username\": \"${USER_NAME}\",\"password\": \"${PASSWORD}\"}" \
"${JIRA}/rest/auth/1/session"`
# output results
printf "\n\nRESULT: ${OUTPUT}\n\n"
# if successful, set the session cookie variable
if [[ "$OUTPUT" == *"errorMessages"* ]]; then
printf "Authentication not successful\n\n"
else
export JIRA_SESSION_COOKIE="JSESSIONID=`echo $OUTPUT | jq -r .session.value`;"
printf "Final result assigned to variable JIRA_SESSION_COOKIE: ${JIRA_SESSION_COOKIE}\n\n"
fi

Using the script

Because the script needs to set an environmental variable in the current shell process, you'll need to source it.

# execute the script
source createJiraSession.sh

On successful execution (after typing in your credentials), you should see the successful output of the authentication call along with the authentication cookie value that will be set in the 'JIRA_SESSION_COOKIE' environmental variable.

RESULT: {"session":{"name":"JSESSIONID","value":"D9D91F5269979BA45F7C572156A785BB"},"loginInfo":{"failedLoginCount":1,"loginCount":20,"lastFailedLoginTime":"2019-01-02T20:00:00.000+0000","previousLoginTime":"2019-01-01T20:00:00.000+0000"}}

Final result assigned to variable JIRA_SESSION_COOKIE: JSESSIONID=D9D91F5269979BA45F7C572156A785BB;

Now on your following REST calls, just reference the session cookie variable. Be aware that session will eventually expire (following the settings you have configured).

# execute a REST call to retrieve project information referencing the session variable
curl -b $JIRA_SESSION_COOKIE \
    -H 'Accept: application/json' \
        'https://jira.random.xyz/rest/api/2/project/MYPROJECT'

That's it! I hope you find this script useful in your REST calls!