As you start scaling with Jira, you will eventually have to learn how to do user management. It is a daunting task, not only is there inherent complexity in managing user permissions for complex systems, but the complexity is compounded by the madness-inducing hierarchy of Jira settings.
You would expect all settings to be snuggly nested within a single space in the Jira navigation tree right? Wrong! There are dozens of different places where you will be expected to make changes to see your users being configured with the right level of access.
But its not entirely Atlassian’s fault, as I always like to contemplate, the Atlassian suite of products is delightfully powerful, After all we are looking at granting users:
- Site-level privileges
- Product-level privileges
- Project-level privileges
And we are looking to do it with a potentially massive amount of users.
To streamline the herding of users, the crafty Atlassian people have devised a series of vehicles with which to change privileges without having to edit users individually. They are:
- Project roles
- User groups
- Permission schemes
In this tutorial I will attempt to make sense of user management in Jira, at least as far as to segregate users across projects. Buckle up!
The problem is that if you are doing project management on multiple projects, you don’t necessarily want the users from one project to have any visibility into any of the other projects. For example you might want to engage each of your customers in their own dedicated Jira project without letting them in on each other.
You need to segregate users across projects. And you want to do that within the same instance of Jira.
People get very confused as to how to do that because the default permission scheme that new Jira projects inherit has “browse projects” privileges granted to “any logged in user”. So no matter how hard they try to assign a group to a project, “any logged in user” can still peruse every project.
Schemes (found in Jira Settings > Issues > Permission Schemes) are blueprints for user privileges that can be shared across projects.
That’s where it gets crazy: individual privileges (for example “Assign Issues”) can be assigned to three different user proxies:
- Application access
- Project Role
But what good is assigning privileges to a specific group of users if the scheme is going to be shared across projects (project A client should not be able to see Project B and vice versa)?
So the crafty Atlassians came up with the concept of project roles. you can have scheme privileges assigned to roles and then assign groups to roles on a per-project basis! In other words Project Role is the mapping table where User Groups meet Project Privileges for a given project.
Putting it all together
A word about groups
Jira users are managed at the “site-admin” level. That is not the Jira Settings level but the level of settings above that, The Atlassian admin level (under user management).
This is where it gets a bit crazy because depending on how you have “Product Access” configured, incoming users will automatically be added to the default access group for that Product (jira-software-users). And that default access group might already have “Browse Projects” privileges in one of the the existing projects.
However, as long as you remove the “Browse Projects” privilege for jira-software-users in all existing schemes, you should leave your incoming users in that group, as it gives them default global permissions as outlined in Jira Settings -> System -> Global Permissions.
However you will want to remove the “Create Next-Gen Project” privilege from “Anyone” (guess they really want people to try the next-gen project) or risk having your users flood your carefully curated projects list with next-gen projects.
Let’s review the default groups that are already available:
- administrators means Product Administrators (Jira and / or Confluence, depending on User Management -> Product Access)
- jira-administrators means jira project administrator, as in “a group of users which are mapped to the administrator role in the default project permissions scheme”
- jira-software-users is the default access group for Jira, new users are automatically added to this group if the “New users have access to this product” switch is toggled on in User Management -> Product Access. The privileges associated with membership to that group can be found in Jira Settings -> System -> Global Permissions.
Sandboxing projects with permissions schemes
This is where it gets fun. With all your new users getting added to jira-software-users automatically, all you need to do to quarantine users to specific projects is to edit all the projects permission schemes to only grant “Browse Projects” privileges to specific users.
“Browse Projects” privilege is the control point for project visibility. If a user does not have that privilege, he will not be able to see the project even if he has any of the other privileges in the scheme.
You could do this by having a separate scheme for each project, but that wouldn’t be scalable. You want to be able to share permissions scheme across projects, but assign specific groups of users to the “Browse Projects” privilege at the project level. The way to achieve that is through Project Roles.
Revoking “Browse projects” privileges to the general public for existing projects
First thing you will want to do is evaluate what is the current level of visibility of your existing projects.
You need to find out how many permissions schemes you have, and which projects are using them. Navigate to Jira Settings -> Issues -> Permission Schemes.
Now there will most likely be 2 default schemes in there, Default Permission Scheme and default software scheme. All new projects inherit one of these two, depending on the project type. This is where the snafu happened with regards to “why it’s so difficult to hide projects from users”. In these defaults scheme, the “Browse Projects” privilege is most likely granted to “Any logged in user”.
Warning! The minute you start changing the privileges in permissions schemes which are used by existing projects, you stand the chance of locking yourself and others out of your own projects! In other words the reason why you have been able to browse all projects might have only been that you are a logged in user.
So we need to revoke “Browse Projects” privilege for “All logged in users” in all schemes, but we want to replace it with another user proxy, one over which we have much more granular control.
Restoring visibility of some projects to some users with project roles
There are three options available when it comes to granting users privileges for the projects associated with a scheme:
- User groups
- Project Roles
- Application Access
We will disregard Application Access since we have already established that this is not practical (makes all projects visible to all users). The remaining options are user groups and project roles.
User groups would work, but we would need a separate scheme for each project, then as long as we have our users separated into groups, we could grant the privilege for each group to one scheme and assign a different scheme to each project. But that wouldn’t be very elegant. Instead let’s focus our attention on Project Roles.
As you can see there is already one project role in use for the “Browse Projects” privilege, it is the Administrator role. The Project Roles help isolate the different levels of privileges within the project itself. Different roles have different permissions, the Administrator Role has special powers within the project, such as the power to delete Jira issues and delete other people’s comments. But then how, you will ask, does a Project Role get mapped to a user or a user group? How does one exercise the privileges associated with the administrator project role, if users are not mentioned anywhere in the scheme?
Well that’s where the magic kicks in. Project Settings have a People tab, where individual user groups can be assigned to a project under a specified project role! As a matter of fact that’s where the mysterious jira-administrators group comes from. At first I wanted to delete that group because I already had a Administrators group, but then I realized that when you create a new project in Jira, especially if you have already modified the Permissions schemes to no longer grant “Browse Projects” privileges to “all logged in users”, the only way to see that project is to be part of the jira-administrators group which automatically gets granted the Administrator Role for the new project.
So there you have it. All the pieces of the puzzles are laid out.
- We know that project level privileges are outlined in a permissions scheme which can be shared across multiple projects.
- We know that visibility of projects only depends on the “Browse Projects” privilege.
- We know that the way to link user groups with privileges is through Project Roles.
All that’s left for us to do is to create a scheme which grants “Browse Projects” privilege to a new custom role. And to segregate our users into separate groups which can be assigned the role on a case-by-case basis (on a per-project basis)
Bringing it home
Go to Jira Settings -> System -> Project Roles and add a new Role. I called mine “Project Participants”.
Revoke “Browse Projects” privilege to “All logged in users” in all your schemes.
Note: There are many ways you can go about modifying schemes for projects:
- You can modify the existing schemes.
- You can make copies of existing schemes (Jira Settings -> Issues -> Permission Schemes -> Copy)
- You can re-assign the project to a different scheme (Project Settings -> Permissions -> Actions -> Use a different scheme)
Grant “Browse Projects” privilege to your new project role in all your schemes.
Organize your users into distinct groups according to axis of classification that suits your needs. For example:
- Separate groups for each customer
- Separate group for your programmers according to how many projects they will need access to (you could have one group of programmers working on multiple projects, but you might have a separate group for highly sensitive projects).
Note: You do not need to grant these groups with Product Access, your incoming users will already have Jira access from their automatic membership to jira-software-users.
The creation and fulfillment of groups is done in User Management (Atlassian level settings, not Jira level settings).
Go to Project Settings -> People and assign different user groups to the “Project Participant” role for each project.
Congratulations, you have now successfully hidden some Jira projects to some users along user group lines without needlessly duplicating Permissions Schemes.