Atlassian is adding the ability for customers to block app access to data using data security policies with app access rules. App access rules may affect your app by blocking its access to certain data. This guide provides an overview of potential impacts to apps and how to address them.
Apps that cannot be blocked by app access rules
Marketplace apps that use Atlassian API tokens or Atlassian credentials to access data cannot be blocked by app access rules. In accordance with our Security requirements for cloud apps, apps must not collect or store credentials belonging to Atlassian user accounts such as user passwords or user API tokens. However, partners can notify Atlassian and receive a temporary waiver for this requirement.
By default, installed apps can access data in any Confluence spaces and Jira projects. Data security policies with app access rules allow organization admins to block app access in specific spaces and projects.
App access rules block the ability for apps to access certain data. In other words, some data is blocked and other data is not blocked. Broadly speaking, an app access rule blocks apps from accessing user-generated data. However, some exceptions, such as space key and name or project key and name cannot be blocked.
One way to think about this is to use an analogy: a Confluence space or Jira project is a container full of objects, where any one object belongs to a particular container. Some objects are user-generated content, such as pages, blogs, issues, comments, attachments. Other objects, like space or project metadata, workflow schemes, screen tabs configuration, audit records, and templates are associated with a particular space or project.
For an overview of what is and isn't covered, see App access rule coverage summary. For a detailed list of data coverage, see App Access for Confluence Cloud REST APIs and App Access for Jira Cloud REST APIs.
When creating an app access rule, an organization admin may select up to 15 spaces (containers) per policy. The image below shows an example scenario where Space B is subject to an app access rule. In this scenario, an app cannot access the page, blog, or custom content in Space B, but it may still access the space name, space key, audit records, and templates.
The Confluence REST API documentation includes a new section indicates which data is blocked or not blocked by app access rules using exempt and not exempt:
When creating an app access rule, an organization admin may select up to 15 projects (containers) per Jira product instance (workspace), per policy. Up to 15 Jira product instances can be included in one policy. The image below shows an example scenario where Site B is subject to an app access rule. In this scenario, an app cannot access the issues in Site B, but it may still access the project name, project key, audit records, and templates.
The Jira REST API documentation will soon be updated with information regarding which data is blocked or not blocked by app access rules. For now, developers should refer to App Access for Jira Cloud REST APIs in the Jira support documentation.
When an organization blocks your app, the impact on your app varies depending on what modules your app implements and what APIs your app implements.
In some circumstances, your app will be hidden entirely when it is blocked. In other circumstances, your app will still be visible, but may not be able to access data that is important for your app to function.
Your app can also receive notifications of changes to app access rule policy settings that indicate your app has just been blocked from accessing a Jira project or issue, or Confluence space or page by subscribing to platform events in your Forge or Connect application.
Subscribing to event notifications at the container (Jira project or Confluence space) or object (Confluence page, blogpost, whiteboard, database, or Jira issue) level may be useful if your app caches any related user-generated content, so that it can adjust what it displays in line with current app access rules.
Apps can receive a large number of events when registered for object-level data security policy events. We recommend that your app subscribes to object-level data security policy events only if notifications at the space or project level are applicable to your app's use cases.
It is important to ensure that your customers are aware that some data may not appear as normal to mitigate the risk of increased support requests.
If your app accesses and displays data to the user that may be blocked, such as spaces, pages, or issues, we recommend informing your customers that certain data may no longer be visible. Apps that search and display results across multiple spaces are most likely to be impacted. For example, your app may be impacted if you implement any of the following modules:
We recommend:
For Forge apps, you may want to make use of Common UI kit components such as the SectionMessage, Tooltip, or Tag, or see the UI Kit 2 documentation for information about UI Kit 2 components. Optionally, you can make the message dismissible.
This example shows an app displaying a Space Report that includes results from spaces that are blocked by an app access rule. In this scenario, the Administration, Banking, and Management spaces are blocked. The app displays a section message indicating that the results may not include some data due to policies set by the organization and that users should reach out to their organization admin if they have questions.
Using a similar approach, this version of the Space Report uses both a section message and tags to indicate that certain spaces are blocked.
This example shows an app displaying a Page Search that did not return any search results as a result of an app access rule. In this case, the app contains messaging indicating that the lack of results may be due to the organization's policies.
This example shows a Confluence Page Filter app where two of the search results are unavailable due to an app access rule.
This example shows an app displaying a Project Report that includes results from projects that are blocked by an app access rule. In this scenario, the Administration, Banking, and Management projects are blocked. The app displays a section message indicating that the results may not include some data due to policies set by the organization and that users should reach out to their organization admin if they have questions.
This example shows an app displaying an Issue Search with JQL that did not return any search results as a result of an app access rule. In this case, the app contains messaging indicating that the lack of results may be due to the organization's policies.
This example shows a Jira Issue Report app where one or more projects are selected as a filter. In this case, the projects that are blocked show a tag to inform the user that those projects are blocked, as the user adds additional projects to the filter.
The Confluence Data Policies REST API includes two endpoints that allow you to check if a Confluence site has data security policies in place and which spaces are affected:
/wiki/api/v2/data-policies/metadata
/wiki/api/v2/data-policies/spaces
Use this endpoint to determine if the Confluence site has any data policies enabled. The response is
a single field called anyContentBlocked
, that returns true
if a data security policy is enabled
for the site. Otherwise, it will return false
.
For apps that deal with spaces (or a list of spaces), this endpoint is useful for determining which spaces are affected by data security policies. It returns a list of spaces and indicates if a data security policy affects each space.
This endpoint is similar to the GET spaces.
However, the GET spaces with data policies
also returns a response field called dataPolicy
that has a single field called anyContentBlocked
.
This returns true
if the particular space has data security policy enabled for it. Otherwise,
the space's dataPolicy.anyContentBlocked
will return false
.
The Jira Data Policies REST API includes two endpoints that allow you to check if a Jira site has data security policies in place and which projects are affected.
These APIs are available to Jira Software, Jira Service Management, and Jira Work Management applications.
/api/v3/data-policies
/api/v3/data-policies/project
Use this endpoint to determine if the Jira instance has any data policies enabled. The response is
a single field called anyContentBlocked
, that returns true
if a data security policy is enabled
for the site. Otherwise, it will return false
.
For apps that deal with projects (or a list of projects), this endpoint is useful for determining which projects are affected by data security policies. It returns a list of projects and indicates if a data security policy affects each project.
Data security policy events are generated when an app's access to certain data within Confluence, Jira Cloud, Jira Service Management, or Jira Software has been blocked by an administrative policy. Currently, the only data security policy blocking access to data is the App access rule.
App access events are triggered by policy changes, including policy creation, deletion, or modification, or when content is moved to a location subject to policy controls. They are NOT triggered by changes in app installs or uninstalls. Therefore, if an app is installed after policies have been created, no notifications are sent out that app access (by that app) is blocked.
If your app needs to determine which items are blocked or not blocked as of when the app is first run, you can use product-specific APIs to obtain that information. See Data Policies REST APIs for more information. Items already blocked to an app on install will not appear in subsequent search or any other data retrieval results, nor will the app be able to update them.
This event documentation uses the terms container and objects in the following way:
Connect apps for Jira or Confluence can register webhooks to receive the following data security policy events:
app_access_to_objects_blocked
: sent when containers in the product instance in which the app is running
are blocked by a policy changeapp_access_to_objects_in_container_blocked
: sent when objects in particular containers in the product
instance in which the app is running are blocked by a policy changeRate this page: