What is changing?
After some time using a per-app secret model, Connect will be returning to a per-installation secret model.
Why is it changing?
Historically, Connect used a different secret for an app in every installation (unique secret per-tenant/per-app secret model). The initial installation of an app would be unsigned and contain the secret for all future interactions, which would be signed. This included any subsequent installs, even where those installs changed the app secret.
We had long wanted to address the problem of the unsigned initial install, as it remained a weakness of the installation process. Our initial approach to solving this problem was to move to a per-app secret model where an app would have the same secret for every installation. The vision was that the app secrets would be made available to apps out-of-band and not passed in the install payload at all. The first step in this transition was to change to the per-app secret model but continue to distribute the app secret in the install payload. So apps would continue to operate as they always had, but the secret sent to the app would be the same across all tenants.
The retention of the installation protocol allowed Connect to fallback to a per-installation secret if there were any internal problems fetching an app’s standard secret. Overall, no guarantee was yet made to apps that the secrets being sent to the app would be the same for all tenants.
As this was rolled out a few problems emerged with this approach. The secrets were still maintained in the tenant’s data store. This meant that rolling a secret would become logistically difficult. Some proportion of the tenant population would be on the old version of a secret and the remainder would be on the new version. For some transitional time we would have required apps to accept payloads signed with either secret. While this is not insurmountable, the renewed focus on ecosystem security also raised concerns about the disclosure of an app’s secret. Such a disclosure would now affect all tenants with that app installed. The increase in so-called blast radius was considered to be undesirable.
The recent introduction of signed installs, signed using an asymmetric key, has addressed our concerns around the unsigned initial install in a different way. An app can now trust that the initial app install is coming from Atlassian. It should also alleviate the problem of secret synchronization loss, where Connect and an app do not agree on the secret in operation for a tenant. The signed-installs solution allows us to return to the per-installation secret model with its significantly reduced blast radius for secret disclosure.
What do I need to do?
As we have not changed the current installation protocol, most apps should still be storing and maintaining secrets on a per-installation basis. For these apps, no change is necessary. Connect will continue to operate as it has done historically.
If you have updated your app to assume the app-secret is the same across all tenants you will need to change back to managing secrets per-installation and storing that information in your app’s installation record for the tenant.
All current app installs will have their secrets rolled and apps will receive a new install payload with a new secret. Receiving follow-up install payloads for existing installations is quite normal in the Connect environment and is used whenever an aspect of an install needs to change. You should ensure your apps correctly handle such installs.
When will this happen?
As this change requires the signed-installs change to be fully rolled out to ensure a secret change is being sent from Atlassian, this change will be rolled out following the final rollout of that feature. Current target is to have it rolled out to all apps before the end of November.