Per-installation sharedSecret rotations

Hello Community!

In the announcement about getting back to per-installation secrets @HanjooSong mentioned sharedSecret rotations and we have some questions to clarify what does it mean.

All current app installs will have their secrets rolled and apps will receive a new install payload with a new secret

  1. Do you have any exact date when it will happen?
  2. What does it mean technically? Would you just send installation hooks with a new sharedSecret?

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.

  1. Does it mean that after you will get back to issuing per-installation sharedSecrets we should be prepared for receiving a new sharedSecret even if one was already issued for a tenant (per-installation one)?
  2. How often could that happen? Is it only on app updates (or every update)? Do you do any periodical rotations (how would it look like)?
  3. If the app will receive a new sharedSecret for a tenant would that mean that the previous one will expire? What is the expiration period?

We currently rely on the fact that once the app is installed for the first time we store the sharedSecret and we don’t update it when the tenant updates the app (or auto-update happens). From the announcement, it seems like we need to prioritize some changes, so it would be really helpful if you can explain what we should be prepared for.

Is that documented anywhere (I mean the rotation policy)? When we were building the app earlier this year we just found that the sharedSecret will be the same for all instances. I would consider if that could be also misleading for others.

Thanks for your help in advance.
Adam

1 Like

In general, it is highly recommended to always update the tenant information you receive the lifecycle events. For instance, the information could also have changed based on site import, the base URL could change, etc, etc. There is a good reason for always updating this information, regardless of the changes to the shared secret.

2 Likes

Hi @AdamMazur
Thanks for pointing out that the sharedSecret description from the link you shared can be misleading, I will have them updated as soon as possible.

In my opinion the correct statement for the current behaviour should’ve been

  • sharedSecret will be eventually consistent for all instances

And moving forward, the description will be updated to

  • New secret will be shared for each installation event

To answer your questions

  1. Do you have any exact date when it will happen?
  • We have already started the rollout, carefully by enabling each apps one by one. But if your app has not adopted the signed-install change, your app is not expected to receive a per-installation based secret yet.
    This means you can technically have this “per-install based secret” feature disabled until the remediation due date of the signed-install AMS ticket if you have one. (If you have already opted-in to signed-install feature but want to request a separate extension for the per-install based secret change, please let me know or create a DEVHELP ticket)
  1. What does it mean technically? Would you just send installation hooks with a new sharedSecret ?
  • There will be 2 stages for this rollout.
    First, your app will start receiving different secrets for each upgrades and installs.
    Second, a background task will find all existing installations with the legacy secret, and send installation hooks to your app server over the next 24 hours.
  1. Does it mean that after you will get back to issuing per-installation sharedSecrets we should be prepared for receiving a new sharedSecret even if one was already issued for a tenant (per-installation one)?
  • Yes, when an app gets upgraded(or a customer manually removes and re-installs the app) new secret will be generated and shared via install hook.
  1. How often could that happen? Is it only on app updates (or every update)? Do you do any periodical rotations (how would it look like)?
  • There is no plans for scheduling a periodical rotation, but if the secret needs to be rotated due to a security reason the process will be the same - an install hook will be sent with a new shared secret.
  1. If the app will receive a new sharedSecret for a tenant would that mean that the previous one will expire? What is the expiration period?
  • Previous one will be expired immediately.

Thanks!

1 Like

Hello @HanjooSong. Thank you very much for your detailed answer. You covered everything.

It would be great if you update the documentation on the mentioned site!

If I may suggest something: It would be great to update the " Signed installation callback requests" section on the Security for Connect apps. When we were building the app we were relying heavily on the information on that page. We were considering updating the sharedSecret on updates, but since we haven’t found that you rotate it on that page (and we did some experiments where we were checking if we receive the same sharedSecret on updates and we found that the secret is always the same), we decided that it’s not needed.

We opted-in for signed-install last week, so we need to make changes quickly, which could not be an option. I will create a DEVHELP ticket where I will request a separate extension for the per-install based secret change)

Thanks again!