Action Required: Deprecating support for passing Connect JWTs as a query string parameter to Atlassian APIs

What is changing?

As per Understanding JWT for Connect apps, the Jira and Confluence APIs today allow Connect apps to provide authentication JWTs as either an Authorization: JWT header in requests, or as a ?jwt= query string parameter.

Following this deprecation period, Atlassian APIs will no longer accept Connect app JWTs as a query string parameter. This change does not affect how Jira or Confluence provides the Atlassian product JWTs to Connect app modules/iframes.

Why is it changing?

Accepting sensitive JWTs as a query string parameter presents a problem as the query string is often saved in web browser history, passed through Referers to other web sites, stored in web logs such as intermediate proxy servers.

What do I need to do?

If your app provides its Connect JWT to the Atlassian APIs as a query string parameter, you must update it to pass the JWT via an Authorization: JWT header.

By when do I need to do it?

We’re removing ?jwt= query string support from the Jira and Confluence APIs by Feb 1, 2022. After this date, the Atlassian Jira and Confluence APIs will no longer inspect the ?jwt= query string parameter and requests from your app may fail with a HTTP 401 response.

13 Likes

Nice!

There is one use case I can think of that currently only works with query string JWT: downloading attachments from Jira. There is currently no API for this, so the only way for Connect apps to do this is to do a GET request to /secure/attachments/{id} with the JWT as a query string parameter.

Would it be possible to either open up the media API or provide another means for apps to download attachments?

5 Likes

Good point! There’s a new API that went out for Confluence last week: New Download attachment REST API endpoint

For the existing API, the recommended approach is:

  • If your app server needs the attachment, specify the JWT via header; or
  • If the end user needs the attachment, rely on session authentication. E.g. redirect them to https://<site>.atlassian.net/secure/attachments/... if they’re logged in, the attachment will download.
5 Likes

Is that API also available for Jira? Because as far as I know, there is no existing API available for Jira to download attachments.

Hi @remie ,

I think you can download Jira attachments by specifying the JWT in an Authorization header rather than a query parameter. Have you given it a go?

Regards,
Dugald

4 Likes

Ah yes, you’re right, that works :tada:

3 Likes

@cmacneill it would be good to add a stronger deprecation notice to the documentation https://developer.atlassian.com/cloud/confluence/understanding-jwt/#creating-a-jwt-token

1 Like

@cmacneill should we expect that Atlassian is also going to make this change when passing JWTs to our apps?

3 Likes

I’m also interested in this. I suspect this doesn’t just include passing JWTs to Atlassian APIs.

Does this mean we can no longer pass Context JWTs to our apps in a query string?

The ACE documentation currently says:

In order to secure your route, the token must be part of the HTTP request back to the add-on service. This can be done by using the standard jwt query parameter:

<a href="/protected-resource?jwt={{token}}">See more</a>

The change Conor outlined is solely for app → Atlassian JWTs (not Atlassian → apps). Many, if not all, of the JWTs via query strings are passed to apps via the web browser. For example, iframe modules are rendered as with <iframe src="https://app.example.com/your-module-endpoint?jwt=<...>" />. In this case there’s no opportunity for us to pass the authentication credentials via a header.

Other Connect modules (like product events, web triggers, etc) already pass the authentication JWT as an Authorization header. Let us know if you’ve found one that doesn’t, but regardless they’re not included in this announcement.

1 Like

Thanks for that suggestion. I’ve added a warning box regarding the deprecation of JWT in query strings.

2 Likes

@cmacneill @zsims Thank you.

What about app → app? When you are passing a JWT token from the frontend of your app to one of your own APIs in a query string and calling addon.checkValidToken(). Will this still be permitted as per the ACE documentation?

I don’t see any issues in this scenario. The deprecation here only applies to incoming requests to the Jira and Confluence APIs

2 Likes