Define work item security for company-managed projects with schemes

15 min

Advanced

By the end of this lesson, you’ll be able to:

Describe the purpose of work item security
Create a work item security scheme

What is a work item security scheme?

Work item-level security specifies which users, groups, and project roles can see work. Jira admins use work item security schemes to define these security levels for each project. Users who have work item-level security can use the Security Level field in a work item to restrict who can see it.

You’d use work item security if you want:

Only the user in a specific field (like Reporter) to be able see that work item.
Only a defined list of people to see certain work items.
Only certain users to see work items so other project members don’t see clutter.
Only certain users to see newly created work.

👉 For example: There are two groups of users in the Sales project: Customers and Partners. A Jira admin configures two security levels, called Partners Only and Everyone, in the work item security scheme for that project. Whenever a project user creates a work item, they can set the Security Level field to Everyone, which means anyone in the project can see the work item, including customers. Or, users can set the Security Level field to Partners Only, which means customers won’t be able to see that work item.

A diagram of security levels. The Partners Only level contains only partners. The Everyone level contains both Partners and Customers.

To access the work item security schemes in your site:

In the upper-right corner of Jira, select the Settings icon (represented by a gear).
Under Jira admin settings, select Work items.
From the sidebar, under Work item attributes select Work item security schemes. This is the Work item security schemes admin page.

Unlike other schemes, there aren’t any default work item security schemes in Jira. By default, permission schemes control how users interact with work in a project. If users have the Browse Projects permission in the project’s permission scheme, they can see all of the work in that project. Work item security schemes enable you to restrict access to work more granularly.

Configure a work item security scheme

Create a work item security scheme

You’ll first need to create a work item security scheme before you can configure it.

To create a work item security scheme:

On the Work item security schemes admin page, select Add work item security scheme.
Enter a name and description that accurately and clearly describes the purpose of that work item security scheme. This will help you and other Jira admins associate the appropriate schemes to projects.
Select Add.

After you create it, the work item security scheme will be entirely empty.

If you already have a work item security scheme that’s similar to what you want to configure, you can copy and modify it. On the Work item security schemes admin page, next to the scheme you want to copy, select Copy.

Add security levels

Next, you’ll want to add security levels to your work item security scheme. Security levels define who can view a work item. You should name each security level clearly and accurately. Project users (with the Restrict Work Item Security permission) use these names to determine the correct level of security to apply to end users.

👇 Project users will select security levels on work, so label them clearly.

A work item in Jira. The security level dropdown is selected. There are two levels called Everyone, and Partners Only.

Every work item security scheme must have at least one security level.

To add a security level to a work item security scheme:

On the work item security scheme's admin page, under Add Security Level, enter a name and description for your security level.
Select Add Security Level.

You can delete security levels if you no longer need them. However, you need to move all work items that use that security level to use a different level before you can delete it.

Add users, groups, and project roles

You’ll associate security levels with users, groups, or project roles to define who can see work for each security level. This step is very similar to granting permissions in a permission scheme, except you’re granting access to work with different security levels. You can add multiple users, groups, or project roles to each security level.

To add users to a security level:

On the work item security scheme's admin page, next to a security level, select Add.
Select who you want to add to that security level. You can only add one at a time.
Select Add.
If you want to add another user, group, or project role to that security level, repeat this process.

If you don’t add anyone to a security level, all users in the project won’t be able to see work with that security level. You likely won’t want to do this.

You should use project roles whenever possible instead of groups. Company-managed project admins can assign groups and users to project roles for their individual projects. This enables you to share work item security schemes more easily as project admins can customize them to their needs.

👉 For example: Benjamina is a Jira admin. She wants to create a security level that restricts work to only project admins. Rather than use a group, or list all project admins individually, she adds the Administrators project role.

Also, as a best practice, add Jira admins and project admins to all security levels. Otherwise, they won’t be able to troubleshoot and help other users.

You can’t completely hide work from Jira admins. Jira admins can always add themselves to a security level in any work item security scheme and get access to those work items.

Select a default security level

If you want, you can make a security level the default for this scheme. All newly created work in associated projects will have this security level by default, unless a user manually selects another level. Work items created by users who don’t have permission to add a security level will have the default security level.

The default security level should likely be the most inclusive security level. Otherwise, it will conflict heavily with the project’s permission scheme.

👉 For example: The default security level should almost always include the same users, groups, or project roles who have the Create Work Item permission in the project’s permission scheme. Otherwise, users will create work items and then never be able to see them again.

To set the default security level:

On the work item security scheme's admin page, next to a security level, select Default.

If a work item security scheme does not have a default security level, the work item security level on new work will be set to None. This means the Security Level field is empty and anyone with the Browse Projects permission for that project can see the work item.

Associate a work item security scheme with a project

To apply a work item security scheme, you need to associate it with one or multiple projects. Only Jira admins can associate work item security schemes with projects.

To associate a work item security scheme with a project:

Open the project in Jira.
In the sidebar, next to the project name, select More actions (represented by ···), then Project settings.
In the project settings sidebar, select Work items, then Security.
In the upper-right, select Actions, then Select a scheme.
Select your scheme, then select Next.
If you’re changing which work item security scheme a project uses, you’ll need to associate work in the project with security levels from the new scheme.
Select Associate.

If you want new projects to use an existing work item security scheme, select the Share settings with an existing project text box when you create the new project. If you don’t select this box, by default, new projects don’t have any work item security schemes.

👇 If you select this checkbox when creating a company managed project, then choose a project with a work item security scheme, your new project will use that work item security scheme.

Screenshot of Jira showing a user creating a project. There’s a checkbox at the bottom of the screen labeled “Share settings with an existing project.” Under the checkbox, you can choose a project to share settings with.

Add the Security Level field to work items

The Security Level field is how project users select who can see each work item. You need to configure the Security Level field to appear on the work you want to secure, or your work item security scheme won’t be effective. This relies on other schemes and configurations for the project.

To make sure the Security Level field is available on work:

Ensure the project’s screen schemes include the Security Level field for the necessary work types in the right place.
Ensure the project’s field configuration schemes show the Security Level field for the necessary screens and apply to the necessary work types.
Ensure the project’s layout for work items doesn’t hide the Security Level field when it’s empty (unless this is the behavior you want).

👇 You can identify the schemes for a project in different areas of the project settings sidebar, like Types, Screens, and Fields.

Screenshot of Jira showing project settings. The sidebar is highlighted, with pages like Types, Layout, Screens, Fields, Collectors, Security, and Components. On the main page, there is information on the issue type screen scheme and the screen schemes for the project as well as options to edit them.

If you don’t include the Security Level field on screens, the value for the field will be the default security level, if you set one.

If you hide the Security Level field in your field configuration scheme, the field won’t have any value.

If you hide the Security Level field after some work items had a value set, the work items keep that value. When you show the field again, the original value will be there.

Validate the work item security scheme with the permission scheme

Work item security schemes and permission schemes need to work cohesively, or you may not get the behavior you want.

👇 Click the tabs below to learn what you need to validate with the permission scheme.

Only users with the Set Work Item Security permission in a permission scheme can set the security level on a work item.

This permission is empty by default. If you want users to set security levels on work, you’ll need to grant the Set Work Item Security permission to specific project roles, users, or groups.

A user who has Set Work Item Security permission can only set or select a security level that includes them.

Impact of work item security in Jira

A secured work item is not visible anywhere in Jira to a user who is not in the work item's security level. For users outside the security level, secured work won’t be:

Returned in search results or saved filters
Counted in reports or dashboard gadgets
Listed in Work Item Links (though there will be an entry in Work Item History and Activity Stream that users can’t select)
Hyperlinked in text fields (like descriptions or comments)
Included in notifications

Subtasks inherit their parent work item’s security level.

How was this lesson?

next lesson

Troubleshoot work item security

Ways to troubleshoot work item security
Let’s explore some examples!

Go to next lesson