Data security policy developer guide

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.

App access rules

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.

Example: Confluence

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:

• Data that is not covered (exempt): App access to this data will not not blocked by an app access rule.
• Data that is covered (not exempt): App access to this data may be blocked by an app access rule.

Example: Jira

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.

Best practices for in-app messaging

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.

• You can see if your Confluence app is impacted by using the Confluence Data Policies REST APIs.
• You can see if your Jira app is impacted by using the Jira Data Policies REST APIs..

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.

• For data security policy event information for Forge apps, see Data security policy events
• For data security policy event information for Connect apps, see Data security policy events for Connect

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:

• Confluence Admin page (Connect)
• Confluence Global page (Forge)
• Confluence Global settings (Forge)
• Confluence Homepage feed (Forge)
• Jira Global page (Forge)

We recommend:

• Informing users that the results may be incomplete.
• Informing users that the results are impacted because of their organization's policy, and not the app itself.
• Ensuring the message is easily visible.

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.

Examples: Confluence Space Report app

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.

Example: Confluence in-app messaging

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.

Example: Confluence blocked results

This example shows a Confluence Page Filter app where two of the search results are unavailable due to an app access rule.

Examples: Jira Project Report app

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.

Example: Jira in-app messaging

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.

Example: Jira blocked filters

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.

Data Policies REST APIs

Confluence data policies REST APIs

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:

• GET Get data policies for the entire workspace, /wiki/api/v2/data-policies/metadata
• GET spaces with data policies, /wiki/api/v2/data-policies/spaces

Get data policies for the entire Confluence workspace

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.

Get Confluence spaces with data policies

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.

Confluence data policies for existing REST APIs

When an app uses an existing Confluence REST API to read a resource, but is disallowed by a data security policy, we return a custom response header.

The custom response header will be in the format Atlassian-DataSecurityPolicy: app_access_blocked, and this will be applied to the following REST APIs:

• GET Get page by id, /wiki/api/v2/pages/{id}
• GET Get blog post by id, /wiki/api/v2/blogposts/{id}
• GET Get database by id, /wiki/api/v2/databases/{id}
• GET Get Smart Link in the content tree by id, /wiki/api/v2/embeds/{id}
• GET Get folder by id, /wiki/api/v2/folders/{id}
• GET Get whiteboard by id, /wiki/api/v2/whiteboards/{id}

Jira data policies REST APIs

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.

• GET Get data policies for the entire workspace, /api/v3/data-policies
• GET projects with data policies, /api/v3/data-policies/project

Get data policies for the entire Jira workspace

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.

Get Jira projects with data policies

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 for Connect

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:

• container: A container is a Confluence space or Jira project.
• object: An object is metadata or user-generated content, such as a page, blogpost, whiteboard, database, or issue. Every object is associated with a container.

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 change
• app_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 change