RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines : keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
- Publish: 01 Jun 2023
- Discuss: 15 Jun 2023
- Resolve: 29 Jun 2023
Hi Developer Community,
If you’ve been joining our Marketplace Roadmap webinars or following Atlassian’s developer blog, you may know that we’re working to bring admins more control when it comes to apps in cloud. One such initiative is a new control for org admins to block cloud app access to certain Jira projects or Confluence spaces. We believe this will help address concerns around “all-or-nothing” app access, and generally improve app migrations and app adoption amongst our more privacy-sensitive customers in cloud.
We are planning to start testing this feature with customers via an early access program (EAP) in the coming quarter, and have shared some details with a small group of partners to better understand how their apps may be impacted. Understanding potential impacts on your app’s behaviour will help us better prepare to support you and your app’s users. With this post we want to ensure we get feedback from a wider audience.
We have included specific questions below where we’d like your feedback on this feature. Please let us know what you think in the comments.
Problem
Over the last few years, Atlassian and many Marketplace Partners have invested heavily in improving customer trust in cloud products and apps. However, customers continue to express concerns about how apps handle their data in cloud. Concerns about app data privacy and security can lead customers to drop apps during migration, or reconsider installing new apps in cloud.
One specific concern we hear from customers is that they can’t control the information apps have access to on their site. When an admin installs an app in Confluence or Jira, the app has access to all the spaces and projects on the instance. If a customer has sensitive information in Confluence or Jira that they’d like to protect (ie: financial data, M&A plans, competitively sensitive internal roadmaps, etc), they can only install apps that they feel are secure enough to access this sensitive information.
Proposed Solution
To address this concern, we’re working on a new administrative control that we are referring to as “App Data Access Controls” in our Cloud Public roadmap. To start with, this feature will allow org admins to define a policy to block apps from accessing selected Confluence spaces and/or Jira projects. Customers can enable or disable this control by selecting “block app access” or keep the default “allow app access” in the app access section of their data security policy.
Selecting “block app access” will prevent any apps from accessing the space(s) or project(s) under the policy. These rules can be updated by admins over time, and will be applicable to apps built for Jira and Confluence on Forge, or with Atlassian Connect or OAuth 2.0 (3LO) frameworks.
Later, we plan to introduce additional, more granular options for Atlassian Access subscribers who will be able to restrict access for specific apps from the list of their installed apps.
Ultimately, we expect this feature to increase customer confidence when installing apps in cloud. This should make it easier:
- for on-premise customers to migrate to cloud and bring their apps with them, and
- for cloud customers to install more apps
Here are some mock-ups of the new customer experience:
Mock up of a data security policy summary.
Mock up of app blocking options for a subscriber without Atlassian Access.
Mock up of app blocking options for a subscriber with Atlassian Access.
While we are aiming to ensure our APIs handle this feature as gracefully and transparently as possible, we recognise that many apps have been built with the assumption that, once installed on a site, the app has access to all projects and spaces on that site. Hence, apps may need to be updated in order to avoid presenting confusing or broken experiences to users. We are also evaluating implementing new APIs to allow apps to programmatically determine when data access is updated after a customer applies a new policy.
We are currently running customer research to establish what level of notification admins and users expect to see when an app is blocked. For our targeted EAP in Q3 FY23 we plan to mimic the “app uninstall” experience, however showing app block specific messaging to end users.
Note: this feature does not impact app licensing or billing. Apps will continue to be priced based on the number of licensed users for the host product, irrespective of any app data access policies that are applied.
New App Data Access APIs
We are evaluating two mechanisms to allow apps to detect whether their access to certain data has changed:
- New product trigger events for Forge apps and webhooks for Atlassian Connect apps to be notified when a policy change causes a space or project to become inaccessible or accessible(e.g.
SPACE_RESTRICTEDandSPACE_UNRESTRICTED). - New REST APIs accessible to Forge, Atlassian Connect, and OAuth 2.0 (3LO) apps to retrieve a set of opaque identifiers (e.g. numeric identifiers or UUIDs) for inaccessible spaces.
Note that these APIs will likely target spaces or projects - you will not receive individual webhooks or events for objects within restricted spaces or project, or be able to check the permissions of individual objects. This may present challenges if you are storing space-related data without a reference to the space that data originates from.
Are these new APIs sufficient for your apps to be compatible with this app blocking feature? Are they necessary, or could your app operate without them? If either prove to be unnecessary we may deprioritise them.
Impacts to existing APIs and platform features
Below is a list of our plans for how various extensibility features of our cloud developer platforms will handle app blocking. We would greatly appreciate your review and feedback on these proposed changes, and especially any concerns you may have on adverse impacts to your apps.
Impact to REST APIs
- For REST APIs that return a collection of spaces or projects such as Confluence Cloud APIs and Jira Cloud APIs, any restricted containers will be omitted from API responses.
- For REST APIs that search across multiple spaces or projects to return a collection of entities (such as pages, comment or issues fields, issue comments), any entities that belong to restricted spaces will be omitted from API responses.
- REST APIs that return a single space (example) will instead return a 404 response if the space or project exists but is restricted. This response will be identical to the API’s behaviour where the space does not exist.
- REST APIs that read an entity that resides in a space (such as a page, comment, blog etc) will return a 404 response if the space it belongs to is restricted. This response will also be identical to the API’s behaviour where the space does not exist.
- REST APIs that modify an entity that resides in a restricted space or project will return a 403 response.
- An app access block check will also impact API performance for many product APIs. There will be some impact even in cases where the customer does not have active policies applied. We are aiming to minimise the impact, but do not have concrete figures to share at this time. We will know more once we are starting internal testing.
- In order to minimise the impact on performance, we are also making some trade-offs to consistency. This means that APIs may return inconsistent results for a short period after policy changes occur. For example, a search API may return references to spaces or projects that your app no longer has permission to view for a brief period after a policy is updated.
Will you need to make changes to your apps to adapt to the new API behaviours?
Do you foresee your app’s feature set or user experience be negatively impacted by the above changes?
Are there any specific REST APIs you are particularly concerned about the impact to?
How sensitive is your app to API latency?
Impact to GraphQL APIs
This section only applies to OAuth 2.0 (3LO) apps, as Confluence’s GraphQL APIs are not yet accessible to Atlassian Connect or Forge apps.
- For queries that return a collection of results, such as findSpaces, any restricted spaces (or pages, blog posts, or comments within a restricted space) will be omitted in the API response.
- For queries that return a specific item, such as space or blogPost, will return a null response, signifying that the item was not found (or similar) or contained within a restricted space.
- For mutations that attempt to update a restricted space, or create or update an item within a restricted space, such as createPage, will fail with a 403 error.
Similar to our questions about REST, will you need to make changes to your apps to adapt to the new API behaviours? Are there any specific GraphQL APIs you are particularly concerned about the impact to?
Impact to content properties
Content properties for Atlassian Connect will continue to expose content property values to CQL and JQL, though content from restricted spaces will not be returned to apps performing CQL queries.
Do you have any concerns about a blocked app’s impact to content properties?
Impacts to App Events
All app events (webhooks for Connect, product events for Forge) relating to restricted spaces and projects or entities that are contained within a restricted space or project, will not be sent.
Note: as policies can be updated by customers at any time, app events will only be dispatched whilst a space or project is visible to an app. This means apps may receive an inconsistent set of app events for a particular entity. For example, an app may receive a space_created event without a corresponding space_deleted event, or vice-versa.
For Connect: Webhooks will no longer be emitted for restricted spaces or projects.
For Forge: Product events will not be sent.
Will you need to make changes to your apps to adapt to the new app event behaviours? Do you foresee your app’s feature set or user experience be negatively impacted by the above changes?
Impact to Macros
All Confluence macros that would be displayed within a restricted space will instead display an error message to users indicating that the app has been blocked by a policy in place of the macro. Additionally, macros from blocked apps will not be discoverable in the macro browser within the context of a restricted space.
Do you have any concerns about an app block’s impact on macros?
Impact to other UI modules (web items, web panels, etc.)
All UI modules that would be displayed within the context of a space or project will not appear if the app has been restricted from accessing that space. For Forge this impacts all Forge UI Kit components.
Do you have any concerns about an app block’s impact on other UI modules?
Frequently asked questions
How should apps determine when a space becomes inaccessible or accessible as the result of a policy change?
Use the APIs described in the “New App Data Access APIs” section above.
How should apps treat stored data relating to spaces or projects that become inaccessible as the result of a policy change?
We can not make any specific recommendations to partners about retention of customer data (or data derived from customer data) after additional data controls are applied. App developers must make their own determination based on their app use-cases, the needs of their users, and any related agreements they have established with their customers. Due to the dynamic nature of legislation and regulations relating to how data is handled in different jurisdictions, it is impossible for Atlassian to share specific guidance on this matter. However, we will try to be as transparent as possible as we learn more about customer expectations in this area.
One approach partners may wish to consider is aligning your app data lifecycle for blocked apps to be similar to how you handle app uninstallation.
How should apps handle a space or project becoming accessible as the result of a policy change?
Similar to the question above, we are not able to make specific recommendations, as it will depend on your app and the needs of your users.
However, one approach partners may wish to consider is aligning this experience with how your app behaves after being freshly installed or after a fresh space import.
How should apps handle user experiences that are presented outside of a space or project context, but collate or display space or project data?
While extension points within a space or project are blocked automatically, you should consider the impact of app blocking on user experiences that your app presents outside of spaces or projects. To avoid confusing users, you may wish to align the data presented in these contexts with the spaces or projects that are currently accessible to your app.
This should be mostly automatic if your UI is purely driven by Atlassian product APIs and you are not storing or caching data, as any spaces or projects that are not accessible to your app will be filtered out of API responses. One caveat here is that some combinations of APIs may be only eventually inconsistent, as noted in the Impact to REST APIs section above.
It may not be automatic if you are caching or storing data relating to a space or project that you accessed prior to a policy being applied. In these cases, you may wish to avoid displaying this data to users to avoid giving the mistaken impression that your app is still accessing restricted spaces or projects.
My app interoperates with other Marketplace apps, how do I tell if they have restrictions applied that are different to my own?
We have no plans at this time to create an API to share how policies impact other apps installed in the site. If you are building features that interoperate with other apps, please ensure that they are resilient to differing space visibility across apps, or fail gracefully where consistent visibility across both apps is required.
Do you have any additional questions about how to handle app blocking in your app? Please add your comments in this CDAC post
