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!

Permission schemes

Permission schemes are mapping tables between users, or user proxies, and project access privileges.

The reason why the management of project permissions are redirected through a scheme is so that the same scheme can be applied to multiple projects. You can define a project permissions template which can be re-used across projects, this allows you to re-use schemes and not have to configure each project individually.

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 administration level (under the "Directory" tab).

When you create a new user, the most important thing to look at is which groups the user is assigned to.

This, among other things, will decide which projects they can view. A new user will be automatically added to the default access groups for each product, for example:

• confluence-users

• jira-software-user

You need to pay attention to this since, as we will reveal later, the visibility of Jira projects is driven by the groups which are granted certain privileges in a project's permission scheme.

Permission schemes

Permission schemes are mapping tables between users, or user proxies, and project access privileges.

The reason why the management of project permissions are redirected through a scheme is so that the same scheme can be applied to multiple projects. You can define a project permissions template which can be re-used across projects, this allows you to re-use schemes and not have to configure each project individually.

It is possible that in one of your existing projects, the permission scheme has granted certain key access privileges such as "Browse projects" to the Jira default access group. This would be one of the possible reasons why your projects are not hidden from new users.

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.

Sandboxing projects with permissions schemes

To see your project permission schemes, go to Jira Settings -> Issues:

Select "Permission Schemes", this will show you all your project permission schemes and the projects which are attached to them:

There are a number of privileges which can be configured in a scheme, and each privilege can be assigned to one-to-many access groups.

The privileges are organized around the following categories.

• Project permissions

• You will want to pay particular attention to "Browse Projects" permission, this is the control point for project visibility

• Issue permissions

• Voters and watcher permissions

• Comments permissions

• Attachment permissions

• Time tracking permissions

And the access groups that each permission can be granted to are organized as follows:

• Project role

• Application access

• Group

• Public

• Any logged in user

• …

"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.

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 grant access privileges to specific users. 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 specific privileges 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. Pay special attention to which access groups are listed for the "Browse Projects" permission. By default that privilege is assigned to the following access groups:

• Any logged in user

• Application access group (jira-software-users)

You will need to revoke access to these groups in that scheme to limit access to the projects associated with that scheme.

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.

The Project Roles help isolate the different levels of privileges within the project itself. 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 granted to a project role within a given permissions scheme, 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 users (or 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.

Project permissions granted to Administrator project role in the permissions scheme:

Administrator project role assigned to the jira-administrators user group in Project Settings -> People.

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

Select the "Project Roles" tab and add a new Role. I called mine "Project Participants".

Create a new scheme or modify an existing scheme that you are going to re-use across projects.

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)

Revoke "Browse Projects" privilege to "All logged in users" in all your schemes.

You'll want to review each permission in the scheme carefully and assign to the appropriate project role according to your access management goals. Although the "Browse Projects" permission is the most noticeable, there are plenty of other permissions which need tweaking.

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 Atlassian Administration -> Directory (Atlassian level settings, not Jira level settings).

Go to Project Settings -> People for each project 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.