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 Atlassian app Fetch APIs, and 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.

Connect apps that have adopted Forge modules may declare legacy Connect scopes here - these will be inserted by the @atlassian/connect-to-forge tool as part of a descriptor conversion. These can be listed alongside OAuth 2.0 scopes (e.g. when incrementally adopting Forge OAuth 2.0).

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

If your app needs to use offline user impersonation (e.g. to impersonate a user from a scheduled trigger), you will need to specify the scopes as a map instead, and specify allowImpersonation: true on scopes your app will use for offline user impersonation. Other scopes can either be an empty map or a map with allowImpersonation: false, for example:

1
2
permissions:
  scopes:
    read:confluence-content.summary:
      allowImpersonation: true
    write:confluence-content:
      allowImpersonation: false
    write:jira-work: {}

Platform and Atlassian app 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.

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

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

• Bitbucket Cloud scopes for Forge apps
• 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 Forge UI app is allowed to access. This section also covers 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.

External permissions support the following types for each entry in the list of domains: String | EgressPermission | Remote

Egress permissions

You can use the EgressPermission type to define egress permission as an object, as well as to include a category for egress permissions for your app.

The EgressPermission type has the following properties:

Apps use analytics data to identify trends and insights, which can be used to improve app performance. These trends and insights can fall under different categories, such as web analytics and Atlassian app analytics. In the context of Runs on Atlassian, you must not mark tools that don't capture analytics data as analytics egress.

We enforce a policy in order to prevent abuse. Refer to Analytics tools policy for Forge apps for more information.

Remote

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 ways to declare an external URL for your fetch back end:

• Direct listing
• As a remote back end

Direct listing

This involves listing the domains directly in the fetch.backend or fetch.client section. You can define these directly as as string or as an EgressPermission object. You don't need to specify individual URL paths, such as example-dev.com/path. Adding one domain allows access to any URL on that domain.

EXAMPLE AS A STRING

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

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

EXAMPLE AS AN OBJECT

1
2
permissions:
external:
  fetch:
    backend:
      - address: "*.example-dev.com"
        category: analytics
        inScopeEUD: false

1
2
permissions:
external:
  fetch:
    client:
      - address: "*.example-dev.com"
        category: analytics
        inScopeEUD: false

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.

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"

Allow for popups from frames

Popups from embedded iframes are blocked by default for security reasons. To allow for them, the following permissions must be applied to your app:

1
2
permissions:
  external:
    fetch:
      client:
        - address: '*'

This will automatically add the allow-popups and allow-popups-to-escape-sandbox directives to the iframe sandbox attribute. This enables external links to be clickable and open in new tabs using anchor tags <a> or window.open(your_url).

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"

1
2
permissions:
  external:
    scripts:
      - address: "https://www.example-dev.com/script.js"
        category: analytics
        inScopeEUD: false