We're struggling to implement Forge Remote Auth reliably

Forge Adopting Forge from Connect
,
1

We’ve discovered that the installationId is not a reliable identifier because it can change without any lifecycle events.

The siteId (or cloudId - naming is inconsistent everywhere) is more reliable as it does not change between installations or data recovery, so we are having to re-implement our Forge Remote Auth layer to use siteId.

However, the Connect install lifecycle event does not include the siteId so we’re having to fetch it from https://customer-name.atlassian.net/_edge/tenant_info which is only documented in the Backup Management REST API docs, and elsewhere on Atlassian support, but is not mentioned anywhere near the Forge Remote docs.

The next problem is that the Forge Invocation Token does not include the siteId, so in order to look up tenants by siteId instead of installationId we’re having to extract the siteId from the undocumented aud claims on that token. EDIT: the siteId only exists in the aud claims if we get an appSystemToken in the request from the scheduled trigger. It is not present in FITs at all.

The Forge installation requests do not contain the baseUrl (EDIT: I’m talking about https://customer-name.atlassian.net here) which we need for historical reasons documented elsewhere, and the REST APIs for obtaining it may or may not be accessible due to eventually consistent Atlassian permissions systems.

Finally, we used to use a REST API that I cannot find the documentation for anymore (/rest/atlassian-connect/1/addons/${addonKey}) in order to check whether an app’s license was still active, because there are no webhooks relating to license expiry/activation. In the Forge world I believe that the canonical way to identify whether a license is still active is to check when the last scheduled trigger request was received, but the only documentation I can find relating to this suggests we should consider the app to be uninstalled.

It feels like we’re implementing multiple workarounds in the dark because Atlassian’s Forge Remote docs do not give us any confidence that the current implementation is “official” and therefore subject to the normal deprecation policies and changelog announcements.
Equally, the information that we need to build a reliable system is just not present in all of the places we need it to be so we’re spending a lot of time implementing additional lookups and fallback mechanisms.

My requests:

  • please can Atlassian document clearly the relationship between the various identifiers and under what circumstances they may change, on this page
  • please can you make siteId and baseUrl a first class property/attribute of Connect lifecycle requests and Forge Invocation Tokens
  • please can you update https://developer.atlassian.com/platform/forge/remote/calling-product-apis/ to document how long an appSystemToken is valid for, so there is a contract with app developers
11 Likes
RFC-124: Evolving the Marketplace Trust Program
2

I share most of these concerns (and we are also using the same workaround on the Connect side to get the cloudId).

In the context of Forge Remote via ACE, I see that the cloudId is seemingly available through context.forge.context.cloudId. I admittedly did not dig far enough to see if this is being natively provided somehow through the FIT or if this is backfilled in the ACE middleware. (I do not see it in the ForgeSettings, but it must be coming from somewhere? Maybe through the same claims you found?)

On the other topics, there is an existing feature request to provide the siteUrl and displayUrl for most back-end contexts (FRGE-1961). I am unsure if this overlaps your FRGE-2010 request or not (did you mean the baseUrl as in the required endpoint for API requests?).

While discussing the stability of Remote, do not forget the ticket related to the apparent unreliability of the TTL of user impersonation tokens (ECO-1215), which might provoke further problems.

2 Likes
3

I’ve edited the original post to clarify that by baseUrl I mean siteUrl - the one with .atlassian.net at the end of it.

And amongst the frustration I forgot to say that we’ve had a lot of really valuable help from Atlassian in Slack channels and Zoom calls which has definitely made things easier, and yet we’re still in this position.

And another edit: the siteId/cloudId is not in the FIT. It’s only present in the appSystemToken.