Last updated Oct 30, 2024

Using the capabilities discussed on this page may make your app not eligible for Runs on Atlassian.

Go to this page to know more about the Runs on Atlassian program. To know how to check if your app is eligible for Runs on Atlassian, go to the Forge CLI documentation.

Add content security and egress controls

Having visibility and control over the external systems that your app communicates and shares data with helps maintain the security of your app and your app users.

To do this, we require you to do the following:

Define the external domains your app will be communicating with.
Use custom Content Security Policies (CSP).

Content security and egress controls only apply to custom UI apps and the fetch method. Learn more about runtime egress permissions.

Define the external domains in the manifest file

When using the Forge platform, you need to disclose the domains outside of Atlassian cloud that your app will be sending data to and receiving data from. This includes actions being performed on the frontend of your custom UI app, for example, sending analytics payloads, or loading images from a third-party website.

To disclose the domains, you need to include new entries in the permissions.external section of the manifest.yml file of your app.

For example, to include images from a third-party website such as giphy.com, use the following configuration:

1
2
permissions:
  external:
    images:
      - '*.giphy.com'

Use custom content security policies

By default, Atlassian blocks any policies that are considered unsafe for your custom UI app. To include items, such as inline CSS, you need to declare these items in the manifest.yml file of your app. You can do this by including new entries in the permissions.content section of the manifest.yml file.

For example, to allow inline CSS in your app, use the following configuration:

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

Update the manifest file

You must define the new entries in the manifest.yml file before you deploy the app. See Permissions to learn how to define these new entries in both the external and content sections.

Modifying these entries may result in a major version upgrade of your app. Your app users may again be required to agree to the permissions of your app. See the Upgrade the app section below for more details.

Manually update the manifest file

Navigate to the top-level directory of your app and open the manifest.yml file.

In the permissions section, add and remove content and external entries as needed.

For example, add the unsafe-inline content style CSP, and *.giphy.com for the external images.

1
2
permissions:
  content:
    styles:
      - 'unsafe-inline'
  external:
    images:
      - '*.giphy.com'

In the index.html file of your custom UI app, you can now leverage the new configuration:

1
2
<html>
    <body>
        <p style="color: blue; font-size: 46px;">Hello world!</p>
        <img src="https://media1.giphy.com/media/d2jioMTLON9bDogE/giphy.gif" />
    </body>
</html>

In the above example, we're using inline CSS to modify our style, as well as include an image from a third-party website.

Run the forge deploy command to reflect these changes in your app.

Validate entries via the forge lint command

You can use the forge lint command to help detect any invalid entries in the permissions of your app. For example, Atlassian supports a limited number of external URL formats. If an invalid URL format is detected in your app permissions, the linter highlights the invalid URL, and a recommendation to fix it, as shown in the example below:

1
2
/Users/agrant/my-apps/hello-world-app/manifest.yml
38:11   error    Invalid 'external.fetch.client' permission in the manifest.yml file - 'https://example.com?test=key'. Learn more about permissions at: http://go.atlassian.com/forge-permissions.  valid-permissions-required

After fixing the URL, run forge deploy to deploy the changes.

If we detect major changes in your app, you may need to complete the Upgrade the app section below to deploy the changes.

Upgrade the app

A major version upgrade of your app may be needed for any of the following:

Changes in permissions
New egress controls
Updates to the targets of existing permissions
Addition of any CSPs in the unsafe-* category

Changes to the app’s permissions won’t take effect until the app is upgraded. If you’ve previously deployed your app and a major change is detected, you’ll need to redeploy your app.

To upgrade your app:

Navigate to your app's top-level directory.

Start the upgrade by running:

1
2
forge install --upgrade

You’ll see output that’s similar to the following example:

1
2
┌───────────────┬──────────────────────────────┬────────────┬─────────────┐
│ Environment   │ Site                         │ Product    │ Scopes      │
├───────────────┼──────────────────────────────┼────────────┼─────────────┤
│ ❯ development │ example-dev.atlassian.net    │ Jira       │ Latest      │
│   development │ example-dev.atlassian.net    │ Confluence │ Latest      │
│   production  │ example.atlassian.net        │ Confluence │ Out-of-date │
└───────────────┴──────────────────────────────┴────────────┴─────────────┘

Select the Out-of-date installation to upgrade by using the arrow keys, and then press the enter key to upgrade the version of the app installed.
Wait for the Upgrade successful message to appear.

Make sure to repeat these steps for each Out-of-date installation listed for the site that you're upgrading. After completing these steps, your app is now running with the new updates.

If you've previously shared the app via the developer console, users will need to upgrade the app via the installation link.

If you've listed your app on the Atlassian Marketplace, you’ll need to publish the new version to the Marketplace to update the egress controls of your app. After which, you'll need to ask your users to uninstall and reinstall the app via its Marketplace listing.