Forge simplified user consent (preview)

This page describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

Please read this document to understand how we will transition the simplified user consent functionality from opt-in during the Preview to default behavior at General Availability.

Overview

We want to provide users with the best experience possible when using Forge apps, especially when they’re interacting with each app for the first time. Simplified user consent eliminates the need for individual users to give consent before interacting with Forge apps.

Historically, the end-user consent experience for Forge apps has followed this sequence:

An admin installs a Forge app onto a site.
Each user, including the admin, then has to go through their own individual consent flow the first time they access the app. In this consent flow, they agree to allow the app to access the resources it requests. If they do not agree, the app will not run for them.

End user consent flow

With simplified user consent, individual users no longer go through the consent flow in most cases. This includes when they use an app for the first time and after major version changes.

Exceptions

There are some scenarios in which users will still need to individually consent. This is the case when the app requires access to the user’s non-public, personal information or needs the user to connect with a service outside of Atlassian that requires authentication. This includes:

The app specifically requests access to the user’s full profile by specifying the read:me or read:account scope, or
The app requires users to connect to a third-party OAuth service (e.g. Google Drive).

In those cases, the user is still required to go through the standard user consent flow for the app. Note that product-user scopes do not require user consent. These are product-specific scopes such as read:jira-user or read:confluence-user.

Previously, all Forge apps needed the read:me scope and it was automatically included during deployment. However, we have updated the platform so that the read:me scope is no longer required and will be removed unless specifically included in the manifest.

During the Preview period, all apps default to NOT using the new simplified user consent model. Your app will continue to work in the manner that it has previously unless you specifically opt-in.

You can opt into simplified user consent using a temporary manifest setting that will only be required during the Preview period.

Opting into simplified user consent during the preview period will result in a new major version. This is triggered by the removal of the read:me scope.

In the future we will be changing the scope removal behavior so it will only trigger a minor version change. This will be in place before we move to General Availability (GA) which is planned for September, 2023. If you want to avoid a major version upgrade you can wait for the GA release.

New manifest settings

In your app’s manifest.yml, add the following optional setting to the app section:

1
2
app:
  features:
    autoUserConsent: true

Property	Required	Description
features	No	The set of optional features that are enabled for this app.
features.autoUserConsent	No	Boolean that indicates whether this app has opted in to using simplified user consent. `default`: `false`

When simplified user consent reaches General Availability (expected September, 2023), all apps that are eligible for simplified user consent will adopt it. When simplified user consent reaches General availability, all apps that don't meet one or more of the exception criteria will adopt it.

The effect on your apps will be as follows:

New apps:
The read:me scope will no longer be added to new apps and they will automatically adopt simplified user consent. The manifest setting won’t be required.
Apps that participated in the Preview:
The manifest setting added during the preview will no longer be required. It will be removed from the app’s manifest.yml file on the next deployment which will be a minor version (assuming there are no other changes that trigger a major version).
Existing apps that didn’t participate in the Preview:
Simplified user consent will be enabled on the next deployment when the read:me scope is automatically removed. This will only be a minor version upgrade (assuming there are no other changes that trigger a major version).