Custom domain - app installation callback

[LaisZagattiPedro]

Hey there! I’m having some issues after installing the app from the marketplace with the installed callback, when the customer has a custom domain in place.
The initial call (atlassian_connect), we get the baseUrl and displayUrl. Then for the installed_callback, we only get the displayUrl for that account. Because of the lack of the baseUrl, we get some issues on our end where we can’t find that account, since we can’t rely only on displayUrl since this can change.
Is there any guidance for this case? Should the installed_callback also include the baseUrl in its payload as well?

[SeanBourke]

Hey @LaisZagattiPedro,

When a customer has a custom domain enabled, you should receive the following properties in the installation lifecycle event payloads:

• clientKey - This is the unique identifier for the customer’s installation.
• baseUrl - This is the primary domain and should be utilised to create API requests.
• displayUrl - For Jira or Confluence, this is the custom domain configured for end users to access the product.
• displayUrlServicedeskHelpCenter - For Jira Service Management, this is the custom domain configured for customers utilising the service desk.

@LaisZagattiPedro

Then for the installed_callback, we only get the displayUrl for that account.

Could you please confirm which callback this is?

[LaisZagattiPedro]

Hi @SeanBourke , thank you for the info!
The installation lifecycle is correct, we do get all the properties you mentioned.

After the installation, we get a callback when the user clicks on ‘Get Started’ from the App in Marketplace. The payload contains the param.xdm_e, which its value is the custom domain (same as the displayUrl from the installation lifecycle), and there is no other information related to the baseUrl. Should the baseUrl be present here or am I missing something?

[SeanBourke]

Hey @LaisZagattiPedro,

The clientKey should be used as your identifier for the installation and customer instance. When you receive the JWT request from Connect, the claim will include an iss issuer property which correlates to the clientKey you received in the initial installation hook.

[KartavyaGoswami]

Thanks @SeanBourke for looking into this. I really appreciate it.

I am investigating this issue with Lais and we are using clientKey for identifying customer instance.

But this issue is related to post installation redirect where Atlassian user clicks on Get Started button and then gets redirected to our site.

When user clicks on Get Started button, they get redirected to our site with the following query params.

cp      no value
cv      1001.0.0-SNAPSHOT
jwt     secret_jwt_token
lic     none
xdm_c	channel-kartavya-test-app__link-jira-app
xdm_deprecated_addon_key_do_not_use	kartavya-test-app
xdm_e	https://my-domain.atlassian.net

Because of the limited info that we get in query params here, we have to use xdm_e param (which is basically primary domain) to find the customer instance in our database and then use sharedSecret of that customer instance to validate JWT token of this incoming request.

And currently during installation, we are storing baseUrl and clientKey in our database but we do NOT store displayUrl.

Until recently, xdm_e param would always be the same as baseUrl so things were working as expected. But one of our customers is using custom domain for their Atlassian instance. Therefore, baseUrl and displayUrl values are different for their instance.

And in this case during post installation redirect, we are getting displayUrl as xdm_e param. (However, we do not store displayUrl ) so we cannot find a customer instance using that xdm_e param and customer cannot continue.

So, I would like to know,

1. Should we start storing displayUrl as well and use that as a fallback during post installation redirect when we cannot find a customer instance which has the same baseUrl as xdm_e param value ?

2. I know app receives an installed lifecycle callback with a new baseUrl for Site rename. If customer ever changes their displayUrl, the same callback will be sent to app? If not then how can we know that displayUrl has been changed?

[SeanBourke]

@KartavyaGoswami

Because of the limited info that we get in query params here, we have to use xdm_e param (which is basically primary domain) to find the customer instance in our database and then use sharedSecret of that customer instance to validate JWT token of this incoming request.

The JWT you receive in this request when decoded should also include an iss property which will map back to the clientKey you received in the initial installation payload.

@KartavyaGoswami

Should we start storing displayUrl as well and use that as a fallback during post installation redirect when we cannot find a customer instance which has the same baseUrl as xdm_e param value ?

It can beneficial to store this for additional reasons - for example, you may need to validate it when setting CSPs, or if you display the Jira URL anywhere in your app, it may be beneficial to display the URL which users are familiar with.

@KartavyaGoswami

I know app receives an installed lifecycle callback with a new baseUrl for Site rename. If customer ever changes their displayUrl, the same callback will be sent to app? If not then how can we know that displayUrl has been changed?

When a customer enables / disables a custom domain, you will receive an updated installation hook for their site which will include the most up to date displayUrl.