RFC-94: Configurable Egress and Remotes

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

Forge currently supports the ability to define egress and remotes for loading data/resources or interacting with remote services, however utilisation requires pre-declaration within the Forge manifest (or generic wildcarded access), or prior knowledge of the location of the remote service. This project seeks to explore alternatives which enable apps to define egress and remotes through admin configuration, improving customer trust and flexibility when utilising Forge apps.

  • Publish: May 27, 2025
  • Discuss: Jun 10, 2025
  • Resolve: Jun 24, 2025

Problem

Forge Egress

When interacting with or loading remote services from Forge, apps must proactively declare egress permissions (fetch, fonts, styles, scripts, images, etc.) within their Forge manifest. Where these are of a fixed type of domain, apps can declare more refined egress permissions (i.e. *.domain.com). Where apps provide broader flexibility for customers (i.e. an app which can load images from any location), an app must declare a more generic wildcard (*).

As these are pre-registered, customers do not have any control over which locations an app could subsequent interact with. As a result of this, they must make a decision to trust apps with generic wildcards during the installation process, rather than being able to manage app permissions throughout the app lifecycle.

Forge Remotes

Unlike egress, remotes do not support wildcarding. A known fixed URL must be known to communicate with and proactively declared within the Forge manifest.

Where an app may seek to build an integration into a remote customer service which has variable domains (for example, a customer hosting Splunk in a self-hosted configuration), they are unable to integrate directly as the FQDN is not known and wildcards are not supported.

Proposed Solution

Apps will be able to dynamically declare and manage their egress and remotes post-installation. This would enable:

  • Apps which have a subset of features which require a remote/egress to gate this functionality, turning it on if/when a customer enables the required remotes.
  • Apps which do not know where a customer may need to load data from can provide an experience in which customers declare a permitted list of domains.
  • Apps which interact with external services which can be hosted on variable URLs can securely provide remote integrations.

Forge Egress

Configurable egress enables apps to add, remove and retrieve a list of urls which are applied to all external property types (frames, images, scripts, fonts, fetch, etc.)

To enable the ability to declare and interact with configurable egress, an app must for declare its support for this within its Forge manifest via a permissions.external.configurable property.

permissions:
  scopes:
    - read:project:jira
    - read:jira-work
    - read:jira-user
    - manage:jira-configuration
    - write:jira-work
  external:
    configurable: true
    frames:
      - 'assets.mysite.com'
    scripts:
      - 'cdn.mysite.com'
    fetch:
      backend:
        - '*.mysite.com'
      client:
        - '*.mysite.com'

Apps can attach or remove egress domains via UI functions when an admin is present. The app would have access to retrieve set domains when any user is present. When egress is added, the administrator will be prompted to confirm the request (see Customer Experience below).

import { permissions } from '@forge/bridge';
const domains = ['*.atlassian.com', '*.jira.com'];
function setPermittedImages (domains) {
  const configurableEgressDomainResult = await permissions.egress.requestDomains(domains);
  if (configurableEgressDomainResult) {
      //customer confirmed egress addition
    } else {
      //customer declined egress addition
    }
}
function DynamicDomainsDisplay() {
  const domains = permissions.egress.domainsDomains();
  return domains.map(domain => { ... });
}

Forge Remotes

Configurable remotes enable apps to pre-declare and dynamically register new remotes as required, providing context to support user declaration of where that remote should communicate. An optional domainPattern could also be declared to limit declarations to specific domain or url shapes where required.

remotes:
  - key: github1
    userConfiguration:
      name: 'Github'
      description: 'Enter your Github site to link to Jira'
      default: api.github.com
      supportedPatterns: 
        - *.github.com

Apps will be able to set or update remotes via UI functions when an admin is present. The app would have access to retrieve set remotes when any user is present. When a remote is set or changes, the administrator will be prompted to confirm the request (see Customer Experience below).

import { permissions } from '@forge/bridge';
const setRemote = async () => {
    const status = await permissions.remote.setRemote('github1', 'https://mysite.github.com');
    if (status) {
      //customer confirmed remote
    } else {
      //customer declined remote
    }
  }
//Retrieve Remote
const remoteDomain = await permissions.remote.getRemote('github1');
console.log(remoteDomain)

Where an app may interact with multiple remote services, where they are unaware of how many the customer needs to configure, the can dynamically register a configurable remote.

mutation RegisterDynamicModule($input: RegisterModuleInput!) {
  registerModule(input: $input) {
    success
    errors {
      message
      code
    }
  }
}
{
  "input": {
    "key": "github2",
    "type": "remote",
    "userDefined": {
      "name": "Second Github",
      "description": "Another one",
      "domainPatterns": "*.github.com"
    }
  }
}

Customer Experience

When an app requests either dynamicRemotes().setRemote() or dynamicEgress().addDomain (or similar), an Atlassian-owned modal would be displayed to the present administrator to approve egress to the domain/s. If an admin is not present, then the modal would not be displayed and the request would fail.

Depending upon the context in which the update has occurred, the app may need to invoke router.reload() to reload the page with new CSPs. We will leave this behaviour up to the discretion of the app.

Beyond the app-defined experiences, administrators will also be able to view and manage defined configurable egress and remotes within Connected Apps.

Marketplace signals and program eligibility

Configurable egress / remotes enable partners to deliver more flexible apps which increase customer trust by enabling them to better understand and control how their data is managed. With that said, the ability to share data remotely would preclude these apps from being eligible for Runs on Atlassian in the program’s current definition and state.

This RFC will not explore the impacts of the utilisation of this capability on RoA or other marketplace signals at this time.

Asks

While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:

  • Whether this unlocks new use cases for you on Forge which were previously inaccessible?
  • Does this implementation make sense for your app/s?
  • The implementation proposed to configurable egress applies to all egress types. Is this acceptable, or would you prefer a more granular approach?
  • Can you foresee any significant constraints of this implementation? Are there things which you would not be able to achieve which should be unlocked through this?
  • Is there anything you believe we are missing, or which should be reconsidered in the above proposal?
14 Likes

Thanks for the RFC @SeanBourke!

I’m not sure how useful these configurable egress and remotes will be, if it doesn’t qualify for RoA. We will have to weigh the additional overhead and effort for customers to setup a remote integration against the minor advantage of not having to declare generic remotes in the manifest. Explaining this technical detail to customers will probably be challenging without being backed by clear signals provided by Atlassian like RoA.

In addition, we’d have to migrate existing customers to utilize configurable remotes, which doesn’t seem worth it without having clear advantages.

IMHO, given that many app vendors are waiting for many other Forge blockers to be resolved, it might be worth reconsidering the priority of this RFC’s effort because of the marginal advantages it provides.

21 Likes

Hey Sean, thanks for sharing this RFC.

Optional/configurable egress is definitely a key feature for many apps, and your proposed approach seems reasonable and well thought out.

My main concern is RoA: if using configurable egress disqualifies an app from RoA, then it may be easier to just use a wildcard and avoid the overhead of managing egress configs.

I know that RoA is not in scope for this RFC, but without considering it, any app that potentially might use a configurable egress would rather just allowlist everything and be free to add all kinds of analytics and external tools without having to bother with major version updates when adding other egresses to the manifest – which would incentivise people to be less transparent with their data sharing!

18 Likes

Thanks for the RFC @SeanBourke,

the suggested approach looks very flexible and would be very useful for some of our apps.

Having this would hopefully resolve a blocker when later on converting apps from using remotes to RoA, depending on the impact on the latter. Therefore similar as to the others this RFC is mostly relevant for us in the context of RoA, so I’m looking forward to further updates on that topic.

Some questions for now:

  • The last screenshot has an “Add URL” button. Does that mean admins could also configure egress without apps implementing UIs / functions for it?

  • The RFC seems to suggest that apps can pre-configure remotes but not egress entries. Am I understanding it right that if we already know some egress destinations required by many customers, then we’d need to build a user interface to assist users with the setup?
    If yes, then it would be great if we could provide a description text for each domain in the requestDomains call, so that customers understand later on (after a year or so) why they had added specific URL.

Thanks,
Jens

5 Likes

Hi Sean,

Thank you very much for sharing this RFC and for all the ongoing work on configurable egress and remotes.
The ability for an instance administrator to independently configure the list of allowed external addresses (remotes) for an app, without requiring the developer to release a new app version, is of fundamental importance and would cover virtually all integration scenarios.
This is especially critical for keeping all app logic and integration capabilities within the Atlassian environment (“runs on Atlassian”), without the need to move business logic or data processing to an external backend.
In this way, the app remains fully compliant with Atlassian Cloud architecture and security requirements by staying within their infrastructure.
At the same time, the control and responsibility for these settings would remain with the Atlassian instance administrator, who can independently decide which external sources to trust in their environment.

Is our understanding correct that such a capability is planned, and that administrators will indeed be able to add or modify remotes through the UI or in some other way?
Or will the final list of allowed addresses always be determined solely by the app manifest provided by the developer?

Thanks again for your attention and for moving the platform forward!

1 Like

Thanks for the RFC!

This change is very much welcome. We would love to use this as a feature-toggle for letting our users set up a Slack integration. Only a subset of our users want this, so it makes a lot of sense to only open up slack egress for these users.

There are also certain customers that would like to send email through our app, and we would very much like to let them use their own SMTP or IMAP servers. We don’t want to use forge remote if we don’t have to. This is unfortunately not possible in forge since only the HTTPS protocol is supported. Maybe this is the right time to configure allowed protocols as well as domains?

How would this work on the backend in the forge resolvers? Will the set domains be available through the getAppContext function? or do we as developers have to save this in storage ourselves in the cases where we would want to use it in a scheduled trigger?

3 Likes

Will the permission control enable a Jira admin to set something like *?

images:
      - "*"
1 Like

Strong agree with Ben. Without the benefit of an RoA qualification, this is extra work (and risk around Atlassian breaking UIs) for no reward as far as I can tell.

11 Likes

Thanks for the detailed RFC!

I agree with the previous comments that RoA capability is really a must for this idea to succeed.

A few additional questions for clarification:

  • Will adding “configurable: true” to the egress section provoke a major update? (For app vendors, the right answer should be: “no”.)

  • Will adding a configurable remote definition provoke a major update? (Same correct answer here.)

  • Does each configurable remote support only a single remote endpoint, or can multiple be established? For example, does an app need to explicitly declare remotes named github1, github2, github3, ad infinitum, if the app needs to interface with multiple sites using the same pattern?

  • How does Atlassian propose that these features be displayed in terms of trust signals in the Marketplace, such as in the “Review and Install” screen?

  • There would ideally be some notion of pre-configured/default egresses that are enabled by default, as well as pre-configured/default remotes, also enabled by default, perhaps with an admin slider toggle to disable it on the installation screen.

The use case for the last bullet would be an existing Connect app that includes features such as email sending through an external service, or the Slack connection mentioned earlier.

Most users who are migrating from Connect would want their existing features to continue to work as previously designed, but a minority of security-conscious customers might want the option to disable them, and the vendor might also want to qualify for RoA. (Maybe this is simply an “optional: true” attribute on an existing egress/remote?)

In the scenario proposed here with UI-based add-an-egress screens, most admins will not bother to go through the workflow (and many admins will not even realize that the workflow exists), so the app feature to send email or ping Slack would simply go missing for the majority of customers. This is especially a concern for an automatic Connect-to-Forge migration where there is no admin interaction.

I write this assuming that there will eventually be an adjustment to the RoA program, or more specifically, that it adopt the definition of RoA being something vaguely like: “an app with no egress, except those egresses specifically permitted by the admin”. This allows apps with existing external-based features to join the program, and the admin can then decide which optional features should be disabled to ensure the desired privacy level.

10 Likes

So the idea is we publish two versions of all apps for everything that could use egress? One without optional egress to make it RoA for lsolated cloud, etc, and one with?

2 Likes

What might be useful here is a different type of badge, like “RoA with Governed Remotes” or something of that ilk. To your point in the RFC, the customer wants to have visibility and control over the remotes, limiting them to only what is needed. They don’t want RoA for RoA’s sake…they want that visibility and control; today they have little to none.

5 Likes

Hi Ben,

While the idea of configurable egress and remotes is useful, I agree with the comments above - without being able to qualify for the “Runs on Atlassian” badge, this is, indeed, extra work with not so many benefits - not having the ROA badge will, most probably, impact sales down the road.

2 Likes

Thanks, @SeanBourke

  • This does unlock use-cases for us.
  • The implementation appears to make sense. An improvement would be more validation options - making it easy to ensure users add the right thing, or have added the right thing.
  • A more granular approach to configurable egress is certainly preferred (in part to forestall questions and concerns from customers).
  • No significant new constraints
  • No gaps not already mentioned.
2 Likes

Hi all,

I’d like to learn more about Configurable Egress and Remotes. Specifically, where would you be egressing to, and for what reasons? Are you directing traffic to your own services or to third-party destinations? Could you share some example scenarios?

Thanks,
James

2 Likes

We use a third party cloud service called ProductFruits. It’s like Pendo and allows us to do in-app messaging and on-boarding. It’s making a huge impact for us.

We utilize Snyk and MixPanel as well.

tors 29 maj 2025 kl. 07:37 skrev James Dumay via The Atlassian Developer Community <notifications@atlassiandeveloper.discoursemail.com>:

3 Likes

We connect to multiple OpenID provider endpoints, which are specific to each customer (i.e. not the generic Google or Github generic endpoints). We also connect to our own remote.

2 Likes

Our main will have to be a RoA app, going down the route of a second, zero egress, app isn’t cutting it, the macro name change is unworkable. However, the revenue change is forcing us to jump.

We embed draw.io diagrams from cloud storage, GDrive, OneDrive, etc. The auth has to be through a known domain server. Currently, the idea is to create another forge app that does have optional egress that all 60k installs of the main app have to install and then ask them all to migrate those embedded diagrams.

We have diagram generation via OpenAI, that’ll have to go, it can’t be done within Forge.

There’s no web socket support, so we lose real-time collaboration, falling back to a slowly, polling update. I can continue the list.

Our only way to avoid a support meltdown when this is launched is to ensure it’s a manual admin update and write “DO NOT PRESS UPDATE” in the release notes.

The only solution for us is if the host can enforce RoA for apps which optional egress and switch all that egress off. So, if the app is on isolated cloud (for example) an app vendor would have to tick “works with zero egress” on the app and enforces that the optional egress are no longer optional. Same for public cloud, the user either sets zero egress per app or for all apps.

4 Likes

We have three different use cases across our apps.

  1. Users embed content into an application from an arbitrary URL. We currently have an allow list functionality we could deprecate in favor of this functionality once it comes to the table.
  2. Users embed content into an application from an arbitrary URL provided by a service we ourselves pre-approve. Think Bitbucket, Github, Gitlab, etc.
  3. We send emails on behalf of users. This means connecting to our own default outbound email processor, or customer configured ones.

Note from my team:

I think what we need from this RFC is the ability for Admins to auto approve all these egress requests. Based on usage, only 1% of our customers use the whitelist feature. This tells me that our customers don’t really care about blocking certain URLs at all. What this RFC suggests will be annoying to the other 99% of customers, ie they will need to approve a ton of requests. So I think if they can offer an auto approve feature for Admins, that will be useful for us.

Btw, our roadmap for the future contains a number of items similar to what @daviddrawio has outlined so +1 to everything he wrote.

4 Likes

This is great news for the Table Filter, Charts & Spreadsheet app as it unlocks our move to Forge. I agree with others that RoA is a must-have for this feature. Otherwise, it will be easier for us and customers to set a wildcard in the fetch permission.
Our use case: an end user enters a URL of their services into the app, the app fetches CSV data from there, and shows the user the data. From the app’s point of view, it can be any URL, and we can’t predict what it can be. So now we need to specify the wildcard in the fetch permission.
A good solution for our case would be to specify a default wildcard in the fetch permissions - it will make no friction updating the app then. This fetch permission will be marked as configurable - it can be changed to specific domains or URLs, or even disabled completely by an admin.
Given that the admin controls egress, it should be considered as RoA. And I think the term “data egress” does not apply to the case when the customer’s data doesn’t leave the customer’s perimeter. Restricting data exchange won’t bring safety to customers - they will move that data even manually if they need it to be done (which is not safer because of human error). I think Atlassian and vendors should let customers use their trusted tools / resources / systems / whatever if they need it. In total, it gives the safety and flexibility customers need.

2 Likes

Forgot to add: we need to send emails to users.
Currently we use an external email processor.
It would be great if Atlassian would open an API endpoint, such that we can send an email to a given accountId through Atlassian.

6 Likes