Last updated Feb 23, 2024

Security for Forge apps

Atlassian customers and admins only install apps they can trust. A key part of building this trust is security, which involves operational excellence in key areas like:

  • Authentication and authorization
  • Software execution
  • Data management

Learn more about how customers evaluate trust in cloud

This page provides a high-level overview of Forge platform security. For implementation details, check out Security Requirements for cloud apps.

Security considerations

It's important to consider building a Forge app that is secure by design. This means your app's infrastructure is ready to handle the security needs of your target customer.

When your app is secure by design, it will:

Before you build your app, consider any regulatory frameworks that it may need to comply with, such as:

Forge security principles

Forge facilitates many of the trust features that customers look for through a shared responsibility model, where security responsibilities are shared between you and Atlassian.

Atlassian is responsible for running the platform used by Forge applications. This includes enforcing what applications can and can't do.

What Forge apps can do

  • Run without interaction. For example, on a schedule, or in response to product events.
  • Be invoked directly by a web trigger.
  • Access the raw HTTP request in a web trigger.
  • Read/write all user-generated content (UGC), depending on which scopes are requested and granted.

What Forge apps can't do

  • Without reapproval by the site admin, you cannot increase scopes, permissions, and egress domains in new versions of previously installed apps.
  • App users' Atlassian login credentials or sessions cannot be accessed.
  • Unless the required scopes are granted, you cannot access Atlassian APIs.
  • Identity properties of app users (such as user permissions or passwords) cannot be changed.
  • If you intend to publish your app on the Marketplace, you cannot call product APIs for a product where the app isn't installed. For example, a Forge app installed on to Jira can't call Confluence.

Sandboxing

The Forge architecture is designed to sandbox apps to control app execution. There are two main parts to this: user interface security and the app runtime.

The new native Node.js runtime is now in preview, and will eventually replace Forge’s current runtime environment. We strongly encourage you to test your apps on this new runtime for compatibility and performance.

This new runtime introduces several changes to the way security and egress controls work. Sandboxing and snapshots (including related settings and restrictions) are no longer relevant in the new runtime as well. These changes may result in additional developer responsibilities to help uphold Forge's security.

User interface security

Forge apps that use custom UI and UI kit inherit modern security features to ensure high trust between Atlassian, developers, and users. As a result, you can create secure user interfaces by default.

How you create your Forge user interface will depend on the complexity of the interactions and visual features you need.

You can use:

Custom UI

Custom UI lets your app to display custom UI on Atlassian products. How it works:

Learn more about Custom UI security

UI kit

UI kit uses components, hooks, and event handlers to quickly build a secure user interface. How it works:

  • Apps implement functions to compose UI kit components.
  • The functions run on the server side.
  • The UI kit components are already provided, so you don't need to design and create them.

The UI kit components are always up to date with Atlassian design standards:

  • Sandboxing UI functions in the UI kit makes the rendered UI secure:
  • No app code executes in the browser.
  • Sandboxing also uses the security and isolation mechanisms that are used by the Forge back-end infrastructure.

App runtime

Controlling the app runtime is critical to security. The Forge runtime sandboxes the apps from the environment in which they execute. By running apps in isolated environments, the platform limits what apps can do. For example:

  • Apps cannot accidentally leak customer data across sites.
  • Apps cannot interfere with or modify other running apps.

To understand how this works in detail, see the diagram and notes on the Forge app sandbox below:

Diagram of Forge app sandbox

Data management

The Forge platform enables secure data management through its architecture and the way it handles data. This includes data isolation to prevent leaks as well as data handling policies for the Forge environments.

Data isolation

Data isolation for apps is necessary in a cloud environment. The Atlassian cloud products are multi-tenant, so apps need to be multi-tenant. However, this means that apps can potentially mix customer data. For example, two customers use an app that uses a global object to cache data by issue key. Issue keys are not globally unique, therefore data could leak from one customer to another.

The Forge platform prevents these types of scenarios by sandboxing apps, as described in the App runtime section. Since apps are sandboxed, app calls occur in separate instances of the app. This means that data is isolated at the runtime level, preventing data leaking.

Environments

Forge ensures that data is handled responsibly by providing different environments for app developers.

Access to user data depends on:

  • Your app enviornment
  • What Forge capabilities you use

An environment is a version of the app that has its own code, manifest, modules, outbound auth container, environment variables, and installations.

When your app is created, Forge sets up three environments:

  • development: This is your default environment. You can create and manage additional development environments. You can read logs and use tunneling.
  • staging: This environment is typically used for continuous deployment, rather than development. However, it is the same as development in terms of restrictions on reading data.
  • production: This is the environment where apps should be installed for use with production Cloud sites. You cannot use tunneling. Site admins can disable your access to logs for a production site. For more detail, refer to the Logging guidelines for Forge app developers.

Simple and secure authentication

Authentication is a fundamental part of security, but it can be complicated to implement and can open up the app to security vulnerabilities. Forge controls the app runtime, which enables it to provide managed APIs that apps can use to make secure calls to REST APIs.

Using managed APIs means that third-party code is never trusted with user credentials. API calls are automatically authenticated on behalf of the app by the surrounding Forge infrastructure. This also means that making API calls is much simpler.

OAuth scopes

Forge apps use OAuth 2.0 protocols when authenticating with:

  • Jira platform
  • Jira Software
  • Jira Service Management
  • Confluence REST APIs
  • Bitbucket REST APIs
  • Compass GraphQL API

Scopes are an OAuth 2.0 mechanism that enables an app to access the data manipulated by a REST API operation. To access an Atlassian product operation that uses OAuth 2.0 authentication, the app needs to request the scopes required by the operation in the manifest file. Scopes then provide administrators and users information about the data an app accesses. This enables administrators and users to decide whether they want to install the app. See Add scopes to call an Atlassian REST API for details.

If an app doesn't request any scopes, the app doesn't have access to OAuth 2.0 protected resources. This follows the principle of least privilege and helps to retain the trust of your users.

External providers

Beyond authentication with Atlassian APIs, Forge supports managed OAuth 2.0 authentication with external identity providers that support OAuth 2.0 authorization code grants, such as Google or Slack.

When using external providers, Forge apps act as the OAuth 2.0 client connecting to an external resource. This enables a Forge app to request information from third-party services securely using the familiar fetch function, while the platform handles getting and rotating OAuth 2.0 tokens automatically.

An app using external authentication provides a connection across multiple Atlassian products with shared authentication handled by the Forge platform. However, apps never have direct access to the OAuth 2.0 tokens. Instead, apps use the withProvider method to have the Forge platform automatically send tokens with each request.

Learn how to integrate with an external provider

More trust resources for Forge apps

For more trust resources, check out:

Rate this page: