Permissions

The permissions section of the manifest.yml file controls your app's access to remote resources.

Scopes

The scopes list declares which OAuth 2.0 scopes are required by your app when using the authenticated Product Fetch APIs, and Product events.

The scopes list also declares which OAuth 2.0 scopes are required by an app that uses Forge remote to pass auth tokens to a remote back end.

Define each scope on a new line. Your app should use the minimum set of scopes required. For example:

1
2
permissions:
  scopes:
    - 'read:confluence-content.summary'
    - 'write:jira-work'

If your app requires no OAuth 2.0 permissions, you must provide an empty scopes list as in the example below.

1
2
permissions:
  scopes: []

Platform scopes and product scopes

Certain platform features, such as the App storage API, are authenticated using OAuth 2.0. For a list of scopes required by these features, refer to Forge scopes.

Product scopes enable a Forge app to request a level of access to an Atlassian product. You can find details about each product operation's required scopes through that product's REST API documentation (specifically, in the operation's Oauth scopes required field). For information about each product event's required scopes, see our events documentation.

For more details about each product's OAuth 2.0 (3LO) and Forge scopes, refer to the pages below:

• Bitbucket Cloud scopes for Forge apps (EAP)
• Compass scopes
• Confluence scopes
• Jira Cloud platform scopes
• Jira Software Cloud scopes
• Jira Service Management Cloud scopes

Content permissions

The content section declares which Content Security Policy (CSP) options are required by your app when using custom UI.

Scripts

The scripts list declares which sources are allowed for an app's script-src policy.

Example

In the example below, script-src 'unsafe-hashes' is included in the CSP header for all modules using custom UI:

1
2
permissions:
  content:
    scripts:
      - 'unsafe-hashes'

Styles

The styles list declares which sources are allowed for an app's style-src policy.

Example

In the example below, style-src 'unsafe-inline' is included in the CSP header for all modules using custom UI:

1
2
permissions:
  content:
    styles:
      - 'unsafe-inline'

External permissions

The external section declares the external resources that your custom UI app is allowed to access.

In addition, it also covers which external website your Forge function is allowed to communicate with. This covers both Custom UI resolvers and any other Forge functions.

In each section, you can add a list of external domains, which end up as a source in an equivalent CSP directive.

Valid domain formats

External domains follow CSP protocols and must be in one of the following formats:

• An https or wss URL, such as https://www.example-dev.com.

  Adding a site URL means that all resources to this site are allowed – you don't need to add * at the end.

• A valid domain name, such as www.example-dev.com

• A wildcard domain name starting with *, for example *.example.com. This includes all nested subdomains below the specified domain name. Wildcards can be used with subdomains, for example *.static.example.com to limit to just the static subdomain.

• A generic wildcard to support every domain: *

External domains must not contain any invalid special characters. You can check your domain with the following regex pattern:

1
2
^(\*\.)?[.a-zA-Z0-9_\-\/:~#%]+$

Fetch

The fetch section has the following configurations:

There are two methods for declaring an external URL for your fetch back end:

• Directly: this involves listing the domain/s directly in the fetch.backend or fetch.client section. When you do, you don't need to specify individual URLs, such as example-dev.com/path. Adding one domain allows access to any URL on that domain. For example:

  1
  2
  permissions:
  external:
    fetch:
      backend:
        - '*.example-dev.com'
  

  1
  2
  permissions:
  external:
    fetch:
      client:
        - '*.example-dev.com'
  

  Using a wildcard for a backend or client (for example, *.example-dev) does not include the parent domain. If you need to support both, you need to explicitly add the parent domain as a second entry.

• As a remote back end: this involves declaring the URLs in a separate remotes section, where you can explicitly define its purpose (in this case, as a fetch back end). Upon declaring the remote back end, you can refer to its key in your fetch.backend or fetch.client list. For example:

  1
  2
  permissions:
  external:
    fetch:
      backend:
        - remote: remote-backend
  remotes:
    - key: remote-backend
      baseUrl: "https://example-dev.io"
      operations:
        - fetch
  

  The fetch setting in the operations property defines the purpose of the remote back end. You’ll need to do this if you want your app to be eligible for PINNED status for data residency purposes. See Data residency eligibility for more information.

Fonts

The fonts list declares which external sources are allowed for an app's font-src policy.

Example

In the example below, font-src https://www.example-dev.com/fonts.css is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    fonts:
      - 'https://www.example-dev.com/fonts.css'

Styles

The styles list declares which external styles are allowed for an app's style-src policy.

Example

In the example below, style-src https://www.example-dev.com/stylesheet.css is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    styles:
      - 'https://www.example-dev.com/stylesheet.css'

Frames

The frames list declares which external sources are allowed for an app's frame-src policy.

Example

In the example below, frame-src https://www.example-dev.com/embed/page is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    frames:
      - 'https://www.example-dev.com/embed/page'

Images

The images list declares which external sources are allowed for an app's img-src policy.

Example

In the example below, img-src https://www.example-dev.com/image.png is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    images:
      - 'https://www.example-dev.com/image.png'

Media

The media list declares which external sources are allowed for an app's media-src policy.

Example

In the example below, media-src https://www.example-dev.com/video.mp4 is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    media:
      - 'https://www.example-dev.com/video.mp4'

Scripts

The scripts list declares which external sources are allowed for an app's script-src policy.

Example

In the example below, script-src https://www.example-dev.com/script.js is included in the CSP header for all modules using custom UI:

1
2
permissions:
  external:
    scripts:
      - 'https://www.example-dev.com/script.js'