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.

Property	Type	Required	Description
`key`	`string`	Yes	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_-]+$`
`baseUrl`	`string`	Yes	Base URL of the remote resource.
`operations`	`string`	No	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.
`storage`	`string`	Yes (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

Data residency features will be added to Forge soon. For now, you can start preparing your app to take advantage of these features immediately when they become available. See Data residency for details about these features.

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 update	Description
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` entry	The 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` property	The 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
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 update	Description
Changing the storage property of a remotes entry from `inScopeEUD: true` to `inScopeEUD: false`	The 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` property	The 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` declaration to an existing `remotes` section	The 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