RFC-92: Forge User Impersonation

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:

  1. Further improvements to security and access control
  2. Minimization of disruption to existing apps

Proposed Solution

Overview

User impersonation involves several parties and includes the following interactions:

  1. App developers declare user impersonation access scopes.
  2. Site admins are informed about possibility of user impersonation and install the app.
  3. Apps running on Forge runtime can perform operations on behalf of users.
  4. 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:

  1. 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.
  2. Impersonation won’t be enabled for scopes controlling access to PII and sensitive information, such as read:me and read:account.
  3. 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:

  1. Does the implementation mechanism make sense for your apps?
  2. Do you see any impediments to your ability to utilise user impersonation in your Forge apps?
  3. Do you have any concerns that the current scope and limitations will prevent switching from Connect User Impersonation to Forge?
  4. Are there any features or corner cases your app depends on that are not present in this RFC?

Your comments are greatly appreciated!

12 Likes

For what it’s worth, our apps provide JSM request capabilities for customer users within Microsoft Teams and rely on using JSM APIs (e.g. Request API) with user impersonation for portal users.

This method returns all customer requests for the user executing the query.

We would need to be able to impersonate customer users with Forge remotes. Alternatively these kind of APIs could accept an accountId parameter, so we can use it on app auth.

So it would still be a blocker to remove Connect for our app.

5 Likes

Thanks for the RFC. The suggested solution for Forge Remotes looks pretty much exactly like what we already have with Connect user impersonation, so I don’t see any big problems for those.

I have a question on this limitation, though:

Could you please clarify how this applies to Confluence? According to the REST API docs (both v1 and v2) no user related APIs seem to require these scopes. Our connect app’s frontend uses the V1 /api/user/current API in order to resolve the current user’s email address. We need this to remain working (or have an alternative) once migrating the frontend to Forge Custom UI.

Thanks!

6 Likes

Hey @jens,

There is a relationship with simplified user consent which supports user impersonation. More details about these scopes can be found in more details section of the changelog when simplified user consent was introduced.

The scopes used by the API you’ve noted is detailed in this changelog as well:

Note that product-user scopes do not require user consent. These are product-specific scopes such as read:jira-user or read:confluence-user .

5 Likes

Thanks for the RFC!

We would need the User impersonation for JSM customer users (portal only users). This is preventing us to adopt Forge for Refined Sites for JSM.

Will the cost budget be same as in Connect?

Can you share how short the token expiry will be? Connect has 15 minutes I believe.

4 Likes

Are there any features or corner cases your app depends on that are not present in this RFC?

Our existing connect app relies on a lot of background execution tasks that utilise user impersonation for APIs such as (but not limited to):

  • Project permission/Global permission validation on a per user basis
  • Issue/Request access on a per-issue and per-project basis
  • Service Desk access for customer accounts

For each of the endpoints we rely on, we do not see a scalable alternative that supports the same validation against multiple non logged in users (Especially across large instances with tens of thousands of users - some of the search APIs do not provide us with a fast solution to achieve what we want without user impersonation.

Only a subset of JSM users can be impersonated. For example, external portal users won’t be impersonated.

This is a blocker for us to migrate off of the existing connectModules.

Are there any features or corner cases your app depends on that are not present in this RFC?

One thing not mentioned is the Forge behaviour for parity with: AC-1014 (If we can make asApp requests for the following endpoints, then a large volume of our user impersonation requirements can be swapped to asApp calls:

  • /api/{v}/user/search
  • /api/{v}/groups/picker
  • /api/{v}/user/permission/search

+1 this. We would be happy to supply a user/customer accountID to perform user impersonation (Failing this, having the ability to request a Token for a customer account to allow user impersonation would be a must). Without FRGE-971, we will still rely on historic user impersonation from Connect.

1 Like

Our apps using Connect user impersonation also need FRGE-971 - impersonation of JSM customer users:

1 Like

This RFC talks about not supporting impersonation of certain special user types for Jira. Since it is unstated, can you confirm if this impersonation feature will work as expected for Confluence guest users?

I am aware that Confluence guest users cannot (yet) directly access Forge apps. I believe this is a separate question though, since the Forge back end may still need to impersonate a guest user, even if the guest user has not used the app (or cannot use the app, pending resolution of the above ticket).

This is also a blocker for me to move off Connect (both for guest users being able to use the app, as well as impersonation of guest users).

5 Likes

Hi @janette,

Thank you for your feedback. We are having an active discussion around JSM portal user support internally, but I can’t yet share anything specific.

Will the cost budget be same as in Connect?

  • Yes, for both Forge Runtime and remotes the impersonated requests will be counted under App+User budget.
  • For the impersonation token creation - we don’t have the final numbers for rate limits and quotas, but they will be based on the current Connect usage.

Can you share how short the token expiry will be? Connect has 15 minutes I believe.

We are finalising the number as well, and it will be close to 15 minutes.

Please let me know if this doesn’t work for you.