Query string hash

A query string hash (QSH) is an important technique to prevent URL tampering and secure HTTP requests when they are made via a browser. The QSH secures the HTTP method, the relative URI path, and the query string parameters. A QSH claim is a SHA-256 hash of a canonical request, sent within a JWT token as a custom claim. Atlassian products send QSH claims that must be validated by apps to prevent leaking data.

Canonical request

A canonical request is a normalized representation of the HTTP request. It consists of:

• Canonical method
• Canonical URI
• Canonical query string

These elements are joined by ampersand.

Example

Canonical method

The canonical method is the HTTP method in upper case.

Example

Canonical URI

The canonical URI is the relative URI path for the Atlassian product or app, that represents a specific resource for the request. As a relative URI path, the canonical URI can survive URL rewrites performed by a reverse proxy. Therefore the canonical URI discards the protocol, server, port, context path, and query parameters from the request URL. The canonical URI always starts with a / character. Therefore, empty-string is not permitted and the minimum canonical URI is just /. The canonical URI only ends with a / character if it is the only character. The canonical URI should not contain & characters. Therefore, any & characters should be URL-encoded to %26.

For requests targeting apps, Atlassian products will discard the baseUrl in the app descriptor. For requests targeting Atlassian products, apps discard the baseUrl sent in the lifecycle installed callback.

Example

Canonical query string

The canonical query string is a normalization of the query parameters, that accounts for the denormalization of query parameters. In other words, query strings may have parameters in any order, may have the same parameter keys multiple times, or stray characters that have no semantic meaning. Because of this, the same parameter meaning can be expressed in many different query strings. The canonical query string factors out the differences so the queries can be compared. The rules for normalization follow.

Ignore the JWT parameter

Example

URL-encode parameter keys

Example

URL-encode parameter values

For each parameter concatenate its URL-encoded name and its URL-encoded value with the = character.

Example

URL-encoding is upper case

URL-encoded characters in query string hashes should be upper case, like %2A, not %2a.

Example

Sort query parameter keys

Example

Example

Using a complex Jira request, a query like this:

1
2
link=http%3A%2F%2Fion%3A2990%2Fjira%2Fsecure%2FIssueNavigator.jspa%3Freset%3Dtrue%26jqlQuery%3Dissuetype%2B%253D%2BBug&
startIssue=0&
totalIssues=2&
endIssue=2&
issues=issues%3DTEST-2%2CTEST-1&
tz=Australia%2FSydney&
loc=en-US&
user_id=admin&
user_key=admin&
xdm_e=http%3A%2F%2Fion.local%3A2990&
xdm_c=channel-acmodule-1564427223927602208&
cp=jira&
lic=none

Will be sorted like this:

1
2
cp=jira&
endIssue=2&
issues=issues%3DTEST-2%2CTEST-1&
lic=none&
link=http%3A%2F%2Fion%3A2990%2Fjira%2Fsecure%2FIssueNavigator.jspa%3Freset%3Dtrue%26jqlQuery%3Dissuetype%2B%253D%2BBug&
loc=en-US&
startIssue=0&
totalIssues=2&
tz=Australia%2FSydney&
user_id=admin&
user_key=admin&
xdm_c=channel-acmodule-1564427223927602208&
xdm_e=http%3A%2F%2Fion.local%3A2990

Sort query parameter value lists

In the case of repeated parameters, concatenate sorted values with a , character.

Example

QSH claim

The QSH claim is a SHA-256 hash of the canonical request as UTF-8 bytes. The hash is hex encoded with lowercase a-f characters. The claim is sent inside the JWT token body so it is eventually signed with the shared secret.

Example