Install Lifecycle and Shared Secret Use Case Clarifications

Hey team,

I am working on my add on handshake functionality so I can build it and forget it when it comes to the JWT token generation and validation. In the end I will have a nice little framework to handle that infrastructure functionality.

I am storing my security context and able to generate tokens. Sweet. (QSH was a bear)

Over the weekend I see this blog post:

It’s a great heads up that if you are building add-ons, account for this sooner rather than later.

So I am diving into hardening my installation handshake functionality and want to account for ALL uses cases and I run across the use case section on

First Install. No problem.

This is easily understood and I am implemented.

Second and subsequent installs.


What use case would I see second and subsequent installs? Is the same as the “First install after being uninstalled?”

Is this a use case where an uninstall occurs but the uninstall/disable call doesn’t register/is handled? Is this to handle the ‘UPGRADE’ use case defined in the blog post?

Maybe I don’t have context or maybe I am bleary eyed from a long day or maybe I am not the only one clear on this use case.

Please advise.


Hi @aarron.szalacinski, in general, the lifecycle works as follows:

  • Only the very first request for each tenant to /installed is not signed
  • Each subsequent request will be signed with a JWT

This means if you get a request to /installed and there is an Authorization header with a JWT you should already have a security context in your database to validate the request. If you don’t, then the request should be rejected.

Also, if a tenant uninstalls an add-on you shouldn’t remove the security context but instead just mark it as uninstalled. This will allow you to verify a possible future /installed request from that same host.

By requiring all requests but the first one to be signed the attack vector is reduced to the absolute minimum.

Have a look at the Atlassian Connect Spring Boot implementation or my own Scala-based implementation.

I hope this helps.


So if I am reading your response correctly, then the second use case doesn’t mean SECOND & SUBSEQUENT INSTALLS… it should read SUBSEQUENT calls to the add-on… correct?

OR, to reiterate my question…

What is an example of the use case of when a Second and Subsequent Install would occur?

Thanks for the response @tbinna. If your response clarifies the documentation is wrong, then maybe we can get that changed and I will mark this as the answer with a recap.


You are right, but I don’t think the documentation is wrong either. This documentation is only talking about add-on lifecycle events, which is one of installed, uninstalled, enabled, and disabled. In that sense, it covers all the scenarios.

Regarding the use case of a second/subsequent install: I think in a production scenario generally there isn’t a subsequent install before an uninstall happens (except for the migration to single shared secret you mentioned). However, when you develop and make changes to the add-on descriptor you would have to re-upload the descriptor (re-install the add-on). In this case, you would get a subsequent install that now should be JWT-signed.

Just as a disclaimer, that’s how I understood the documentation and the Atlassian Spring Boot implementation. Maybe someone from Atlassian can confirm or correct/clarify if I am wrong. @rmassaioli?

1 Like

Ah… add-on updates on my end!

Good call Tobias! I feel as if that is the likely answer and in agreement that until Atlassian weighs in to clarify.

I can dive back into my work.

Thanks @tbinna


I think everything you stated is right except for maybe this statement. I can’t find any documentation that supports this. Here’s a page that talks about updating cloud apps.

Hi there,

With this topic I finally understood new things.

I am currently doing App to Jira Cloud. And got that I need to store installed and an another file on my server and not just rewrite the installed file in enabled, disabled or uninstalled life-cycles.

But when my App come to be completed then it is required to delete installed file when the customers uninstalls my App?