RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Project Summary
This RFC aims to gather feedback on initial implementation of offline user impersonation for apps built on Forge.
- Publish: 15 April 2025
- Discuss: 29 April 2025
- Resolve: 13 May 2025
Problem
Atlassian Connect offers the User Impersonation feature, which unlocked a lot of unique use cases. Forge, as the successor of Connect, provides the ability to perform actions on behalf of present (i.e., via Forge UI) users. However, it doesn’t support interactions with product APIs on behalf of users who are not present (are offline). Such interactions are required by apps that use scheduled triggers, product events, and other background interactions. This RFC outlines the first iteration of offline user impersonation functionality.
The solution for the problem should meet these key criteria:
- Further improvements to security and access control
- Minimization of disruption to existing apps
Proposed Solution
Overview
User impersonation involves several parties and includes the following interactions:
- App developers declare user impersonation access scopes.
- Site admins are informed about possibility of user impersonation and install the app.
- Apps running on Forge runtime can perform operations on behalf of users.
- Apps running outside Forge (remotes) can request an authorization token that can then be used to directly call Atlassian APIs on behalf of users.
Manifest Changes
To enable user impersonation, app developers will be required to declare user impersonation scopes in the app manifest. The manifest will allow to apply the allowImpersonation flag to specific scopes. The application of the flag will define a subset of existing scopes that can be used on behalf of users. This will ensure the impersonation token has only necessary scopes. The application of the flag will not restrict existing app permissions.
Example of a permissions section of a Forge manifest:
permissions:
scopes:
'report:personal-data': {}
'storage:app': {}
'read:connect-confluence': {}
'write:connect-confluence': {}
'read:custom-content:confluence':
allowImpersonation: true
'write:custom-content:confluence':
allowImpersonation: true
'delete:custom-content:confluence': {}
When user impersonation is added to existing scopes, the app deployment will trigger a minor version upgrade. This in turn will ensure seamless distribution of the new version of the app.
App Installation
Site admins will be informed about the possibility of impersonation (either or both online and offline) in the Permissions section while installing the app. See an example wording below:
Adding impersonation scopes to existing apps will not require any actions from site admins because offline impersonation token will have only a subset of already declared app scopes.
Usage in the Forge Runtime
When the impersonation scopes are declared in the manifest, the apps running on Forge runtime can use the existing asUser().request<product>(), passing an optional user parameter. A request here may look like:
const response = await api
.asUser('123:123123')
.requestJira('/issues');
Calling Atlassian APIs from Forge Remotes
After the app with new impersonation scopes has been deployed, its registered remotes will be able to start requesting impersonation tokens. These tokens will be accepted by all Atlassian APIs available for Forge. The following example GraphQL query can be used to request impersonation tokens:
query asUser {
offlineUserAuthToken(
userID: "123:123123")
{
accessToken,
expiry
}
}
This query will expect appSystemToken for authorization. appSystemToken is obtained during installation, via scheduled triggers or on demand via new token refresh functionality.
The remotes are expected to use impersonation tokens for small time-bound groups of interactions; hence, the tokens will have a short expiration time. When the token expires, the app will be able to use the same query and a valid appSystemToken to request a new impersonation token.
Our supported Connect Frameworks (Atlassian Connect for Node.js Express and Atlassian Connect for Spring Boot) will offer a library function that will wrap this call, for convenience.
Rate Limiting and Cost Budgets
User impersonations in Forge Runtime and via an authorization token will fall under App + User cost budget with corresponding limits applied.
Authorization token generation will be subject to a separate limit. It will be based on the usage observed for similar Connect endpoints and communicated later.
Limitations
For the first iteration of this functionality, the following features are left out of scope:
- The authorization token will only be used with APIs supporting OAuth and Forge-compatible scopes. The APIs that require Basic or other authentication methods are out of scope.
- Impersonation won’t be enabled for scopes controlling access to PII and sensitive information, such as
read:meandread:account. - Only a subset of JSM users can be impersonated. For example, external portal users won’t be impersonated.
Impersonation of any app user accounts won’t be allowed due to security considerations.
Asks
We invite application developers and users of the Atlassian Ecosystem to share feedback about this RFC and help us identify and prioritize further improvements to user impersonation on Forge:
- Does the implementation mechanism make sense for your apps?
- Do you see any impediments to your ability to utilise user impersonation in your Forge apps?
- Do you have any concerns that the current scope and limitations will prevent switching from Connect User Impersonation to Forge?
- Are there any features or corner cases your app depends on that are not present in this RFC?
Your comments are greatly appreciated!