RFC-91: Role-based access control in Confluence - Roles API & the access Apps can set with it

General Request for Comments (RFC)
, , ,
1

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.

Project Summary

The project addresses the integration of role-based access control (RBAC) in Confluence, focusing on its impact on apps and the ecosystem. The proposal suggests restricting apps from creating, updating, or deleting custom roles to prevent issues related to role limits per site. We are seeking feedback to determine if apps can continue updating user access using default roles and whether product admins should configure roles for apps to use.

  • Publish: 25 March 2025
  • Discuss: 8 April 2025
  • Resolve: 22 April 2025

Problem

Role-based access control (currently in EAP with customers and partners) in Confluence provides space access based on the roles assigned to users, groups, and user classes. All space-level access decisions will eventually be driven by role assignments and not individual permission assignments like they are today.

With the introduction of role-based access control, there will be four default roles available out of the box and Confluence product admins can create additional custom roles as needed. Product admins can create, update and delete custom roles through the UI or the REST APIs we will be providing. There will be a limit to the number of custom roles allowed per Confluence site, and we are trying to determine whether apps should be allowed to create roles.

Proposed Solution

We are considering preventing apps from creating, updating and deleting custom roles. This will prevent apps from changing any existing custom roles, and will allow apps to use only the four default roles and any additional existing product-admin created custom roles when assigning a role to a user, group or user class.

The reason we are considering this approach is because the number of custom roles allowed per site will be limited. If apps are relying on the ability to create custom roles, the apps may not work correctly on sites where the custom role limit has been reached.

Asks

We are trying to understand whether the apps that update user access today via permissions will still be able to make the necessary permissions updates needed using the default roles. Would it be reasonable to have a product admin configure roles for the app to use?

2

This doesn’t impact us, but I expect Atlassian will get absolutely roasted for this by customers. Would love to hear what is driving this limit.

1 Like
3

@LawrenceHui can you elaborate a bit more on how the custom role works?

If there are 20 users who all have the same set of permissions that do not match any of the four default roles, is that considered 20 custom roles? Or is it considered 1 custom role?

1 Like
4

Restricting us from creating an app-specific custom role may significantly complicate things for our customers.

The core features of our archiving app, Better Content Archiving, rely heavily on specific space permissions (e.g., create/delete page or blog post, archive page). To simplify permission management, we’ve created a dedicated screen where customers can easily review missing permissions across all spaces and grant them as needed.

I have a few questions:

  1. Will roles be the only option for managing app permissions on a space in the long run, or are they just a convenience, allowing us to continue assigning custom permissions to spaces for our app?
  2. Am I correct in understanding that apps will be able to use the Set space role assignments REST API to assign an appropriate role to themselves on spaces? In other words, even if an app cannot create or modify roles, will it still be able to programmatically assign a user-chosen role to the corresponding app user, on a specific space?
5

Thanks for your feedback! The custom role limit is being driven by a couple of things.

Simplifying the system

Admins (particularly at larger, more complex organizations) have told us they want a system that’s simpler to manage at scale. This means a focus on clear, consistent, and predictable access patterns across the entire site. Limiting the number of permissions configurations in a site helps prevent configuration sprawl.

User-friendly and scalable interfaces

Limiting the total number of roles available ensures that dropdown selectors are easy to use and understand and that performance and scalability aren’t compromised.

If there are too many roles, the overall performance of Confluence drags and there is a higher cognitive load on the people managing access at the space level (e.g. how do they know which role to choose in which situation if there are hundreds of them?)

6

A role has a specific combination of granted permissions. If you had 20 users with identical permissions configurations that don’t match any of the default roles, you could create 1 custom role with that configuration and assign it to all 20 users and they’d have the same access.

7

Roles will eventually be the only option for managing space-level access. You will not be able to assign space-level permissions like you are today, you will have to assign a role at the space level to the app.

Your understanding is correct, an app will be able to use the REST API Set space role assignments to assign an existing role to a principal in a space.

8

Yes, but… if I look at the proposal on CAC it seems like Atlassian is creating “custom roles” during the migration for every user that does not have one of the four default roles. Will these Atlassian-defined custom roles count towards the role limit? And if so, how will they be counted?

9

Thanks, @LawrenceHui! The “Manager” default role seems like a good fit for our app’s use case so we won’t need to create/update custom roles. One last question: do you have a rough estimate of when the “individual permission based” approach will be removed from the API?

10

Will the roles also influence restrictions set on individual page? Our app manages page restrictions, such that only specific people are allowed to edit a page.

1 Like
11

When the roles experience is enabled for a site, if a user or group’s access does not match one of our 4 default roles, we will be setting their access as “custom access”.

Custom access is not a custom role. It’s an access state that provides a bridge between Confluence’s current permissions model and the new role-based system so that no people lose access when roles are rolled out. Custom access does not count towards the custom role limit.

12

The exact timeline is still being finalized, but it will be after the GA of roles for Confluence. We plan to give customers and partners several months warning ahead of the deprecation.

1 Like
13

Roles will influence who has the ability to edit content and manage content restrictions in a space. This is already the case with the current permissions model. For a person to be able to edit the page, they will need to hold a role in the space that allows them to edit content (the same way they need to hold the individual permission to do so today).

The introduction of roles will not impact individual page restrictions or how those are managed. That will still be managed at the content level as they are today.

1 Like
14

Hi @LawrenceHui will the “app accounts” themselves be granted one of the new roles on spaces. Or is there an app specific role being created, something similar to how Jira works?

Thanks
Chris

15

App users with the default space admin permissions will be granted the default Admin role in the same space. Any app user without the default space admin permissions will be treated like all other existing users in the each space, needing their access updated from “custom access” to a role. There are no plans to support app-specific roles.

2 Likes
16

Thank you everyone for the feedback! We will now close this RFC, take your feedback on board and will return soon to update you on how we’re moving forward.

19

Thank you everyone for the feedback! After review, we have decided to proceed with preventing apps from creating, updating and deleting custom roles.

Apps will not be allowed to change any existing custom roles, and will have to use one of the default roles or any existing custom roles created by product admins when assigning a role to a user, group or user class.