Display conditions
Permissions

Remotes

When using Connect or external authentication, or when invoking a remote backend from a Forge app using the Forge remote, the external domains that the app communicates with are listed in the remotes section of the manifest.yml file, and are referenced by key.

Properties

PropertyTypeRequiredDescription
keystringYes

A key for the remote, which other modules can refer to. Must be unique within the list of remotes and have a maximum of 23 characters.

Regex: ^[a-zA-Z0-9_-]+$

baseUrlstringYesBase URL of the remote resource.
operationsarrayNo

Indicates the purpose of the data being egressed. For now, this property only accepts four values:

  • storage: app egresses data to be stored on a remote location.
  • compute: app egresses data to be processed (but not stored) on a remote compute service.
  • fetch: app uses a remote endpoint for client fetch permissions
  • other: data is being egressed for logging, diagnostics, or any purpose other than storage, compute, or fetch.

If a remotes entry contains no operations property, Forge will assume that the app is egressing end-user data to be stored on a remote back end. See Data residency for more information.

authobjectNoAn object that defines the authentication tokens to be provided to the remote endpoint
auth.appUserToken.enabledbooleanNo

If true and the remote endpoint is invoked within a user's login session, Forge includes an appUserToken in the Forge Invocation Token it sends to the remote app.

This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the user in whose login session the app is running.

Specifically, the API will have only as much access to the site's data as that user does. For example, if the user does not have permission to see pages in a particular space or issues in a particular project, the API won't provide them access to that space or page, either.

Forge modules that run outside of a user's login session, such as an app lifecycle event or product event are not associated with a user and cannot send an appUserToken to the remote app.

If an endpoint opts to enable remote user token access, the read:app-user-token scope must also be specified in the Permissions section of the manifest.

auth.appSystemToken.enabledbooleanNo

If true, Forge includes an appSystemToken in the Forge Invocation Token it sends to the remote app.

This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the generic "bot user" for the app.

If an endpoint opts to enable remote system token access, the read:app-system-token scope must also be specified in the Permissions section of the manifest.

storagestringYes (if operations property contains the storage value)

Indicates whether you are egressing end-user data to store it on a remote location, through the inScopeEUD boolean.

See Data residency for more information.

Data residency

Forge apps that don't contain a remotes declaration automatically become eligible for PINNED status. This is because Forge can safely assume that the app is not storing any in-scope End-User Data on a remote back end.

When an app contains a remotes declaration, Forge will (by default) assume the app is storing in-scope End-User Data on a remote back end. Storing in-scope End-User Data on a remote back end will make your app ineligible for PINNED status.

If your app contains a remotes declaration but does not store in-scope End-User Data on a remote back-end, your app can be eligible for PINNED status. However, you’ll need to declare this explicitly:

  • If your app stores data on a remote back end, declare this through the storage property. If the data you’re storing remotely isn’t in-scope End-User Data, use the inScopeEUD: false boolean to indicate this:
    1
    2
    remotes:
      - key: remote-backend
        baseUrl: "https://backend.example.com"
        operations:
          - storage
        storage:
          inScopeEUD: false
    
  • If your app egresses data that will not be stored in a remote back end, you can declare this in operations through the compute or other properties:
    1
    2
    remotes:
      - key: remote-backend
        baseUrl: "https://backend.example.com"
        operations:
          - compute
          - fetch
          - other
    

  • If your app uses a third-party service for runtime egress permissions and doesn’t store data on a remote back end, declare this in operations through the fetch property:
    1
    2
    permissions:
      external:
        fetch:
          backend:
            - remote: remote-backend
    remotes:
      - key: remote-backend
        baseUrl: "https://backend.example.com"
        operations:
            - fetch
    
    In this case, your fetch.backend list will use the remote back end’s key instead of the actual URL. You can use other for instances where you egress data for real-time logging, diagnostics, and other similar cases. See Permissions for more information about configuring the fetch section.

In these cases, Forge will be satisfied that your app is not storing in-scope End-User Data on a remote back end. As a result, your app will be eligible for PINNED status in the admin's Data residency interface. This also means that when your app is installed on a product with the PINNED status, so will your app:

App pinned to same location as product

See Data residency for more information about the PINNED status (for both products and installed apps).

Major version upgrades

Manifest file updates that add new remotes entry or expand an existing remote’s scope will result in a major version upgrade of your app upon deployment. This ensures that whenever an app starts egressing data to a new back end, admins can review and re-consent first before updating. Such manifest file updates include:

Manifest file updateDescription
Adding a new remotes section

The app uses a new remote back end, and admins need to be explicitly notified whenever this happens.

Changing the baseURL of an existing remotes entry The app now technically egresses data to a new remote back end.
Setting inScopeEUD: true to the storage property of an existing remotes entryThe app is now storing in-scope End-User Data on a remote back end.
Removing all the operations and storage properties of an existing remotes entry The remote back end no longer states any purpose for the data being egressed. As a result, Forge will automatically assume that the app could be egressing in-scope End-User Data to the remote back end for any purpose (including storage).
Adding a new purpose to an operations propertyThe remote back end’s scope is now expanded, since it is being used for an additional purpose.

For now, only the following changes trigger a major version upgrade:

  • Adding a new remotes section with a baseURL not previously defined in a fetch.backend declaration
  • Changing the baseURL of an existing remotes entry

All other manifest file updates from this list will only result in a minor upgrade until further notice.

As such, if you are interested in making your app eligible for PINNED status later, we recommend that you update your manifest file as needed now.

Minor upgrades

Removing a remotes entry or any update that decrease an existing remote’s scope will only result in a minor upgrade. Such manifest file updates include:

Manifest file updateDescription
Changing the storage property of a remotes entry from inScopeEUD: true to inScopeEUD: falseThe app previously stored in-scope End-User Data on a remote back end, but now it doesn’t. This reduces the scope of the back end.
Removing one or more (but not all) purposes from an operations propertyThe remote back end’s scope is now reduced, as it is no longer being used for a specific purpose.
Moving a URL from a fetch.backend declaration to the remotes sectionThe remote back end hasn’t changed in scope, it is now simply declared in a different way. See Data residency eligibility and Fetch for related information.

Minor upgrades are automatic, and will not require any action by users or admins.

Example

The following example shows two remotes (remote-backend and loggingserver) that do not egress in-scope End-User Data to be stored remotely:

1
2
permissions:
  scopes:
    - "storage:app"
  external:
    fetch:
      backend:
        - remote-backend
remotes:
  - key: remote-backend
    baseUrl: "https://backend.example.com"
    operations:
      - storage
      - fetch
    storage:
      inScopeEUD: false
  - key: loggingserver
    baseURL: "https://logging.example.com"
    operations:
      - other

Rate this page: