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.

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: []

Forge apps deployed in the development environment always receive all available OAuth 2.0 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:

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'

Source	Description
`unsafe-inline`	Allows the use of inline resources, such as inline `<script>` elements, `javascript:` URLs, and inline event handlers.
`unsafe-hashes`	Allows the use of specific inline event handlers.
`unsafe-eval`	Allows the use of `eval()` and similar methods for creating code from strings.
`blob:`	Allows `blob:` URIs to be used as a content source.
`<sha-algorithm>-<base64-value>`	Allows a specific script to be executed, provided it matches the hash declared here. The only valid hash algorithms are: `sha256`, `sha384`, and `sha512`.

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'

Source	Description
`unsafe-inline`	Allows the use of inline resources, such as inline `<script>` elements, `javascript:` URLs, and inline event handlers.

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, backend and client.

Backend

The fetch.backend list declares which external domains your Forge functions can talk to. This applies to both custom UI resolvers and any other Forge functions.

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.

Example

In the example below, *.example-dev.com is allowed for all of the calls that your Forge function is making:

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

Calls made to any domain that is not defined in the manifest.yml file of your app will be rejected. Learn more about runtime egress permissions.

Client

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

Example

In the example below, connect-src *.example-dev.com is included in the CSP header for all modules using custom UI:

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

Using a wildcard such as *.example-dev.com for CSP does not include the parent domain. If you need to support both, explicitly add the parent domain as a second entry.

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'

If you are using specific styles and fonts together in your application, you must include both of them as permissions in your app's manifest file. This is because the styles and fonts are external resources that the app needs to access in order to display correctly. By including these permissions, you are granting your app the ability to access and utilize these resources, ensuring that the text and design elements appear as intended.

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'