RFC-29: App Access Rule - Revised followup to New Data Access APIs

Just like @BorisBerenberg I believe that this will increase our support cost a lot even if we implement the appropriate api’s since we’ll get support tickets of "Why can’t I find this [project|this issue|board|filter] in your app. We get this to some degree today and spend a fair bit of time debugging with the customer with limitations in the the various search api’s that we have access to (granted we’ve gotten really good at it now and have good documentation now).

While we will more than likely put in appropriate warning messages etc - there will be corner cases and there will always be end users that skip the warnings and in-app messaging.

Can we get an understanding of what the in-app experience is for the end user/container owner/instance admin? Ideally there will be tools such as the “Why can’t I see my field” tool on issues for this type of thing (Why can’t app X see this item). And documentation - the more documentation Atlassian can provide the better so we can deflect the end user to this.

Will this feature be available in the developer canary instances?

It is for this use case (i.e. apps which present to a user the set of containers in a workspace) that we are providing an API endpoint to retrieve containers and whether they are blocked by policy or not.

For individual objects (the same use case but presenting to a user a set of objects rather than containers) we believe the overhead of evaluating policy for every object in the view is impractical. For this reason we are providing an API endpoint to retrieve an indication of whether policy is in effect at all within the workspace.

In both cases the purpose is to give the app enough context to know whether to display messaging to the end-user.
And of course if an app is blocked by policy from rendering at all then the UI will render an explanatory message.

If these APIs are insufficient for your use cases then we welcome additional concrete examples. :slight_smile:

This reply is in response to ongoing expressions of concern about Cloudevents. In conjunction with the explanatory note about Cloudevents in this RFC I will explain by way of example show how the use of Cloudevents should be completely transparent to Partners, who should be able to work with plain json objects as usual.

Schema diff

If we were to ignore Cloudevents entirely (while still including event schema properties we feel are desirable), an example AppAccessToObjectsBlocked event would look like this;

{
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects.v1",
  "id": "7a6796c0-746d-4504-92cd-819eca234306",
  "time": "2023-10-24T08:08:08Z",
  "data": {
    "site": { 
      "url": "https://site_name.atlassian.net"
    },
    "blockedObjects": [
      {"type": "page", "id": "12345"},
      {"type": "page", "id": "23456"},
      {"type": "page", "id": "34567"}
    ]
  }
}

If we then add whatever is necessary to align with Cloudevents, an example AppAccessToObjectsBlocked event (and what we propose in this RFC) then looks like this;

{
  "specversion": "1.0",
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects.v1",
  "source": "com.atlassian/ecosystem.app_policy",
  "id": "7a6796c0-746d-4504-92cd-819eca234306",
  "time": "2023-10-24T08:08:08Z",
  "data": {
    "site": { 
      "url": "https://site_name.atlassian.net"
    },
    "blockedObjects": [
      {"type": "page", "id": "12345"},
      {"type": "page", "id": "23456"},
      {"type": "page", "id": "34567"}
    ]
  }
}

These two event schemas are clearly very similar.

The specific changes are;

  1. The http Content-Type header value changing from application/json to application/cloudevents+json.
  2. Addition of a specversion property - which may be ignored if not relevant to the event consumer.
  3. Addition of a source property - which may be ignored if not relevant to the event consumer.

We can now make the following observations;

  • The effective change to json schema made in order to align our event schema to the Cloudevents specification is the addition of two properties - which may be completely ignored.
  • If an app’s http request handler does not register a Cloudevents content type parser it will fallback to the json parser that will already be registered for Atlassian webhooks.
  • Every one of these schema changes are completely transparent to the app. An app can perform ordinary json parsing of the event payload, as it does today for all other Atlassian events.

Binary content mode

While we have withdrawn the proposed binary content mode, it seems this was misunderstood and so it may help to clear this up.

Cloudevents ‘Binary Content Mode’ simply means the event metadata and data are not carried together; metadata is carried via transport headers and data in the message payload.

For http webhooks this means the id, type, time properties are carried as http headers, and the data property is the http message body. It is not binary encoding, it is binary (two-pieces) transport. (As opposed to ‘Structured Content Mode’ which keeps event metadata and data together in the payload.)

Broader rollout

To be clear, we have not committed to evolving all existing event schema to align with Cloudevents, and there is no intent to do so. While consistency of event metadata in schema would be wonderful we believe mandating this would be an enormously disruptive change.

So the issue is that we’re having to implement these and then guide the customer to troubleshoot things to make sure that they’re seeing these items. This increases support costs since we’ll be having to do hand holding with every customer (and every vendor has to implement the feature).

The ask(s):

  1. Please provide standardized troubleshooting tools for the end user to see why something isn’t available to an app (but they can see it).
  2. Please provide standardized documentation explaining how this works and who they should be contacting to fix.

Us implementing the api’s will work somewhat but without #2 - we’re left having to teach the users how to resolve things.

The issue for us is that we won’t know about the “hidden” containers since we might not ever have seen them before.

1 Like

If you are questioning the App Access Rule initiative itself, this is being provided to meet Customer demand - we acknowledge App Access Rules do result in additional complexity and implementation costs for both Atlassian and our Partners.

If you want to make this claim then show us the data. What % of customers and what % of revenue will be impacted by this feature. Show us that it’s worth it.

2 Likes

Hi Boris,

Thank you for raising your concerns.

Note that the App Access Rule feature has been requested by our mutual enterprise customers as a necessary step for them to adopt more apps or as a requirement that needs to be met in order for them to move to cloud. Some of our largest customers are yet to migrate to cloud. They have identified apps to be business critical and would not move without them, eagerly waiting to get increased control over what apps can access in their environment.

based on my experience with the Allow Access UI in Forge, I conservatively expect this to change to double our support costs

Can you elaborate a bit on this, is it that the end user consent flow initially introduced for Forge apps have caused an increase in your support cost or the removal of it?

have a significant negative impact eval to net new conversions

As I mentioned above, we’ve heard from our customers that the “all or nothing” access that apps currently have deters them from using apps in cloud. As such, we expect this rule to help more customers feel confident installing cloud apps who may not otherwise install them today.
I’d like to unpack the support concern a bit here… With the app access rule in place, apps will still be allowed access in all spaces by default. A customer must actively enable an app block for them to experience any change to functionality, which they should expect once they’ve taken action to block an app.

We are also working on proactively notify end users in-product that their admin has blocked an app in places where the app functionality may be impacted (some examples mentioned here), so this should also limit support impact on partners.

Thanks heaps in advance!

Cheers,

Angelina

Hi @JustinThirkell,

Thank you for the clarification.

I’m just afraid that you are missing the bigger picture here. Obviously we understand that this is just going to be delivered as plain JSON. And obviously we can work with CloudEvents SDK. This is not a technical issue we are discussing.

The point is: you are working on this for what? 6 months? A year? According to CDAC you only joined in June this year. The Atlassian Marketplace Partner community consists of partners working with Atlassian architectures for more than a decade. We’ve seen every tech fad come and go within Atlassian, often introduced by engineers that recently started. Those engineers got promoted away and after a year are working in other teams pursuing other Shiny New Things.

You are introducing a new architecture for a very little small subset of the entire Atlassian Cloud ecosystem. You are even very open about this being specific for just this very little small subset:

And in a year, you will be gone. And this little inconsistency within the context of the entire Atlassian Cloud ecosystem will remain. At some point, CloudEvents might be upgraded. It might change. It might become deprecated. And another engineer comes along who will think “why are we using this? We should be using the AwesomeEvents standard instead”. And they migrate. And we follow along to pursue yet another fad.

And you will be gone. And we will be here. Just like we’ve done for the past decade(s).

This is why I’m appealing to you, no begging you, to look beyond your nice little project working with this Shiny New Thing and be open to ALL. THE. FEEDBACK. you received that ask you not to do this.

3 Likes

I totally get this. My question is how many have requested this? Is it 1%? Is it 10%? Is it 100% of people to whom you have suggested the idea in the first place? But they didn’t ask for it till they were told it would be possible?

Without these numbers, it’s hard to understand if the juice is worth the squeeze. Given that Atlassian is a data driven company, I feel like it would help for vendors to be on the same page with the opportunity this brings as Atlassian.

The recent change improved the situation after years of impact on both net new customers (eval → new churn highest of any of our apps) and support costs (nearly 100% of our support tickets were caused by this UX).

My gut feel is that this is technically true but practically false. This is going to get packaged into Access or Premium or something as an upsell functionality. As a result, there will be proactive marketing and communication informing customers about this functionality, even if they never asked for it. My guess is it will also be highlighted to existing customers via emails / change logs / etc. Now you have a large population of customers who don’t actually NEED it, but will enable it anyways because it’s security and that’s the thing we do now.


This RFC focuses on our technical ability to work with Atlassian at an API level once this scenario happens, but my concern is that even before this comes to us, the UX of how this is configured on the customer side, and the UX of how they can troubleshoot it, will be poor. This isn’t a hypothetical concern, Atlassian has a history of poor UX for complex configuration challenges. And also a history of shipping half finished products and then not delivering on the important features for supportability. In addition to the Forge example, in Access we have 5 years for audit logs: https://jira.atlassian.com/browse/ACCESS-577

I am not saying this functionality can’t be implemented well. I am saying that the evidence I have implies it won’t. And, recent evidence supports that when it’s done wrong, it will take years to resolve and vendors will be the ones paying the cost in the meantime.

As such, to my original question, please help us understand what % of customers actually need this. I want to model out if there is an actual financial positive scenario here, or if I need to open headcount for support and start reducing R&D headcount in our 2024 hiring plan.


Taking a step back to look at this problem from the customer perspective rather than the technical one, this feels to me like customers fall into a few groups:

  • I don’t trust vendors, Atlassian should host 100% of everything (solved with Forge)
  • I trust Atlassian, I also trust vendors, but not with everything (solved with this issue, or Forge)
  • I trust vendors with everything (status quo)

Based on this, Atlassian should focus on getting Forge to be the best platform for us and help us get to there so we can support the superset of customers rather than expanding serious effort and onboarding serious risk to only appease a subset of enterprise customers. Even assuming this implementation goes well, the best case scenario is we have to build support for this, and then we have to migrate to Forge anyways down the line.

2 Likes

Hello @JustinThirkell,

I would first like to echo a couple of things already mentioned in previous comments. The first being the question of if this will be available to app vendors before the feature reaches our customers? The second one being the concern of increased support to educate our customers in why our app isn’t showing an Atlassian entity. As @danielwester suggests it would be nice if Atlassian could provide tooling instead of each vendor doing their own implementation/support effort.

We have not decided how we will handle this update internally yet, but we store data in our DB that is connected to Confluence pages. Our app display Confluence pages in a customised site so we have data for likes, feedback on the content, meta data for display in social media etc. in our database. If we would go with the option of removing this data when the app no longer has access, then there wouldn’t be a way to restore it if the customer unblocks our app. Another option would be to keep the data forever, with the drawback of having data stored that is never used and that it might not be what the customer expects when blocking our app. There are of course also more complex solutions to make the customer decide what to do or to keep the data for a while and remove it if the app isn’t unblocked in that time (but there’s no unblock event so it would be difficult to implement). I’d like to hear Atlassian’s input on how you suggest we deal with data stored in the app but connected to Atlassian entities that might be blocked.

Thanks!

1 Like

@remie the tone of your comments is getting very close to ad hominem. Usually you are fairly good at avoiding deriding specific individuals, so please continue to focus on the proposed changes rather than the individual proposing them.

As to your concerns, I do agree that API inconsistencies make aspects of our platform unintuitive and harm the developer experience. While I’m proud of the depth and breadth of the Atlassian platform (and the amazing things that you and other partners build on top of it), we do not yet have a consistent approach to technical API considerations across the board.

This is an area we are exploring, alongside more standardised approaches to partner API collaboration (such as this very RFC process). However to set expectations, it will be some time before we have a consistent set of standards defined and longer still before it is rolled out across Atlassian’s broad API surface area. For eventing, CloudEvents is a possible standard that we will evaluate and may align on more broadly on in the future, but that commitment is outside the scope of this RFC.

For now, the most effective way to use the RFC process is to provide feedback on the specific application of CloudEvents to this API. Please do continue to share constructive criticism on this front. If there are further concrete issues with the API that would inhibit its adoption beyond concerns about consistency and the technical concerns regarding CloudEvents and ARIs that have already been articulated, we would love to hear them.

2 Likes

Hi @AndreasEbert,

I am unsure how my response relates to locked custom fields, but happy to clarify anyway.

Note that in the context of the App Access Rule both locked and not locked fields will behave in the same way.

How an app can create locked custom fields

Looking at Forge fields, fields created by the custom field module are indeed locked (as described in the Field lifecycle section of the documentation). Conversely, fields that admins create from custom field types aren’t.

How an app can an app update an existing custom field as locked by our app

It’s not possible to change this on a whim, all custom fields are locked by default, and all fields created from custom field types aren’t. I am afraid those are not configurable.

Hope this helps,

Angelina

@AngelinaIgnatova, oh, maybe I misunderstood your post on RFC-25 where your screenshots show text about “fields associated with an app”. That is what I mean with “locked custom fields”. Please correct me if I have the terminology wrong here.

Anyway, if I understand you correctly then these fields associated with an app are only available for Forge apps, not Connect apps, right? Your links point to the Forge docu, but I don’t see similar pages about such “locked” fields in the Connect documentation :confused: Since our app is a Connect app, we would need it for Connect.

Thanks for any clarification.

1 Like

HI @BorisBerenberg,

Hi Boris,

Note that earlier this year 37% of server/DC customers surveyed (n=266) indicated that they need to be able to identify which cloud apps give them more control of where the data is stored, and what sensitive data (PII, UGC) apps have access to. We see this as a strong signal that customers will feel more comfortable moving to cloud if they can exercise more control over the content apps can access.

Hope this helps.

Cheers,

Angelina

1 Like

Hi @danielwester, hope you have been well.

We hear your concerns about the potential confusion that the App Access Rule may cause to customers. We are also mindful of the end user impact and have implemented (and continue to implement) custom block section messages that we believe will positively affect the end user experience.

We will be updating the documentation to clearly explain how the feature works and how it will impact the end users of apps. Through the policy creation flow we are encouraging org admins to inform their end users how the App Access Rule will affect their experience:

We are informing users that their organisation admins are in control of the app blocking and encouraging them to reach out to their org admins in effort to reduce the likelihood of end users reaching out to you.

Here are a few examples of what end users will see when interacting with apps:

Confluence

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.

App Pages & Space settings

All UI modules that would be displayed within the context of a space will not appear if the app has been restricted from accessing that space, as custom block messages at those interaction points would have been too overwhelming for end users. However, when end users reach out to their site admin to enquire about a change in the app behaviour, site admins will be able to easily identify which apps belong to an active policy as those apps will appear with a tag in Connected apps in Admin hub and Manage apps in the Universal plugin manager.

Jira

Custom fields would be hidden for any blocked apps, however product admins will be able to use the “Find your field” tool to troubleshoot

Layout

If either of: Issue Action, Issue Activity, Issue Context, Issue Glance, Issue Panel, quick add button are hidden as a result of an active App Access Rule, a message will display for admins initially. We can expand this message to all users if we hear that you are receiving an increased amount of support requests specifically for hidden items:

Project settings page and project page

Note that we will not be introducing any changes to the workspace modules, it will be up to the app owners to decide whether/how you want to handle the changes to the end user experience.

Hope the above brings more clarity about how we are addressing the end user experience. As aways, we welcome any feedback.

Cheers,

Angelina

2 Likes

Hi @julia,

Thanks for raising your concerns with the App Access Rule.

Will this will be available to app vendors before the feature reaches our customers?

The short answer is yes, we plan to give partners a chance to test starting by the end of this calendar year, well in advance of the GA release for customers.

Note that this quarter we would be looking to expand our Customer EAP by inviting Confluence cloud customers who have already created policies using other data security rules. The EAP will still be focused on Confluence only for now, but it will include apps built on Connect and it will be open to any Confluence Cloud customer who wishes to test the feature.

In the same time we want to give you a chance to test out how the App Access Rule affects your apps’ end user experience and how you would take advantage of the APIs to stay informed about polices that affect your app access to data. So keep an eye out for a chance to sign up in the change log in the coming weeks. Additionally, we are also considering rolling out the feature to the Canary developer instances.

Early next quarter we are looking to add the Jira family to the App Access Rule.

It would be nice if Atlassian could provide tooling instead of each vendor doing their own implementation/support effort

I have provided more details about what Atlassian is doing to inform end users, product and site admins about how the App Access Rule works and why they are seeing changes in the apps’ behaviour. Keen to hear if there are any major gaps that you can notice?

If we would go with the option of removing this data when the app no longer has access, then there wouldn’t be a way to restore it if the customer unblocks our app.

In the documentation we are advising customers that data stored by apps may get deleted by partners and may not be restorable should customers decide to disable/delete any app access rule polices.

Another option would be to keep the data forever, with the drawback of having data stored that is never used and that it might not be what the customer expects when blocking our app.

We can not make any specific recommendations 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, Atlassian cannot share specific guidance on this matter. However, we would be looking to obtain more feedback from customers regarding their data retention expectations and will make sure we share our findings with you.

Cheers,

Angelina

1 Like

This feels like an almost willful misinterpretation of the customer feedback to justify an extreme feature design. If this is really the best data to justify this feature, I would request an executive escalation and review of this.

1 Like

@AngelinaIgnatova ,
That’s great (and for those apps that are directly blocked - awesome!)

But in our case and anyone else that makes heavy usage of search (both in confluence and in jira) - the big headache will be troubleshooting (and explaining) why an issue/board/etc isn’t showing up. This is the area where I feel a lot of us vendors would be looking to Atlassian to also help out.

Scenario - customer puts in a ticket of “Your app isn’t showing anything from project Y in your general page - please fix”. How would we go about troubleshooting this? (assuming that it’s blocked by the app access rules but the customer putting in the request doesn’t tell us and isn’t a site admin - we don’t have a project based link etc).

Thanks,

/Daniel

4 Likes

@AngelinaIgnatova I second the concerns raised by @danielwester.

To give an example: our app Version & Component Sync allows project administrators to synchronise releases and components between projects.

They do this by selecting the target project from a list:

In the current version of this RFC, we will still be able to populate this list because we will continue to have access to the project level. This means that the user will not be limited when creating a link for release / component propagation. However, once the link is created, the actual synchronisation will not work because we will not be able to access the project releases/components.

So we will either have to check app access for each project in that list to see if it is eligible for synchronisation (slow, cumbersome, lots of API requests), or allow the user to finish setting up their project only to alert them of our failure to synchronise.

And that is just during project link creation. What happens if app access is blocked whilst there are already projects actively synchronising?

We have Enterprise customers who are synchronising 200+ projects, often spanning multiple PM’s. It will take a long time before they will notice that one project is no longer getting version/component updates. In the few cases in which we have had this in the past, this led to serious data integrity issues.

Due to the nature of Atlassian being very protective of end-user data it is extremely difficult for us to notify the appropriate person that app blockage will impact synchronisation.

The issue isn’t in the easy parts, but in the 1% of use cases in which partners are doing complex operations. This is where our support requests and angry customers will come from.

3 Likes

Hi @tpettersen,

To be honest, I actually took a lot of consideration in that post. The personal nature of the remarks was deliberate, not to disqualify @JustinThirkell, but to also highlight that Atlassian can’t have her cake and eat it.

Either Atlassian is operating as an entity and engineering decisions are made with consideration of a bigger picture, or Atlassian teams operate holistically and autonomous.

If it is the former, I would be able to appeal to a larger body that can evaluate these decisions and override the team. However, as per your comment, this is not the case

we do not yet have a consistent approach to technical API considerations across the board.

That means that we appeal to individual teams, and we apply a thin layer of veneer of decency by pretending that authors are just representatives of a larger organisation, avoiding ad hominem remarks by always referring to “Atlassian” instead.

But when our feedback is dead on arrival, with no possible escalation policy, there comes a point in which I feel that a heartfelt appeal to the individual becomes inevitable. Because whether we like it or not, Atlassian does have a “not invented here” problem, and it does have a huge employee turnover problem, and it does have an OKR problem. That is not something individual Atlassian are to blame, but sometimes they need a reminder of this, because Atlassian also has a lack of internal partner advocacy problem.

So whilst I never meant to offend @JustinThirkell, I do think there are times in which it is important for individual Atlassian engineers to understand the impact of their decisions upon an ecosystem that was there long before they started and will be there long after they are gone.

1 Like

Hi @remie , I’m unclear why the API we propose to (get the status of provided containers won’t work for the use case you describe.
We were expecting that when you call the API that you would pass in an array of project identifiers that you want to check access for, not call the API separately for each project. Does that help with your use case?

Also, it’s worth noting that while this API is described in this post as a graphQL resource and as a resource in the OpenAPI contract, I have just discovered that the short example of the RESTful resource was being parsed as part of the OpenAPI contract - I have fixed this now and it is rendering properly here. Sorry about that!