Introducing two new project permissions - View Projects and View Issues

G’day Atlassian developer community!

We’re adding 2 new permissions, View Projects and View Issues, to eventually replace the “Browse Projects” permission. This will give users and admins more fine-grained control over who can view the projects and issues.

Note: We have endeavoured to make this change backwards compatible, and based on our understanding of how apps are using our REST APIs today we believe this change should not impact apps. However, this is a significant and fundamental change to Jira Cloud: the BROWSE_PROJECTS permission is close to two decades old, and the semantics of our existing permissions APIs are quite complicated. There may be impacts to apps that are difficult for us to anticipate.

To mitigate the risk of us overlooking a use-case that is important to apps, we have decided to hold off on rolling this change out for four weeks (28 days) from time of publishing. Further, we have decided to give a window till Mar’23 to make changes within your application, post which we plan to remove support for Browse Project permissions. If you have concerns after reviewing the details below, and you believe the change is not backwards compatible (that is, the functionality of your app as it is built today will break) then please let us know in the reply and we will revise our proposed timeline as necessary.

Context

As you may know, the “Browse Projects” permission has dual functionality. It is used to check

  1. if a user can view projects
  2. if a user can view the issues within the project.

In other words, it can be used to act at the Project Level e.g. permission to view the projects directory, and at the Issue Level e.g. the ability to view an issue.

Since all the other permissions either work at the Issue Level (e.g. “Edit Issues”) or at the Project Level (e.g. “Administer Projects”), the current way of working of the “Browse Projects” permission is unique and problematic.

Why it is changing?

By splitting the “Browse Projects” permission into two, we can give users more fine-grained control over Jira’s permissions. Both the new permissions will have its own distinct role.

  1. View Projects” is a project-level permission for viewing projects in Jira. It is the permission to view the projects directory page and the ability to select that project in various dropdowns such as in JQL.
  2. View Issues” is an issue-level permission for viewing the issues within a project.

Therefore, “View Issues” can be used to control who can view issues within a project and “View Projects” can be used to control who can view projects in the projects directory.

How are we rolling this out?

We will rollout the change in 2 stages:

  • Stage 1: Introduce two new permissions - View issues and View Projects - In Sept’22
  • Stage 2: Remove support for Browse projects permissions - After Mar’23

This announcement is about Stage 1. As mentioned above, we believe everything is backward compatible in this stage, i.e. both Browse Projects permission and View Issues + View Projects permission will coexist and work together. The rollout for this stage will be done in phases over next few weeks, starting with the EAP cohort.

EAP: All instances enrolled in the Jira Cloud Vendor First Release will get these changes right after this announcement. After getting sufficient feedback on this, we will give an update about when this change will be rolled out to all customers.

For Stage 2, a separate announcement will be made after 6 months , in Mar’23. During this period, we welcome feedback from you.

We strongly recommend vendors to plan for and adopt the above changes. We plan to remove support for Browse projects permission after Mar’23. We will keep the community posted if there are any updates in this plan, as mentioned in the note above.

What is changing in Jira?

  1. Current behaviour:
  • If you want users to access projects or issues, BROWSE_PROJECTS permission is used
    • eg: if you want users to get project information like description, issuetypes, project properties, BROWSE_PROJECTS permission is used
  1. New behaviour after Stage 1
  • If you want users to access projects, use VIEW_PROJECTS or BROWSE_PROJECTS permission
    • eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either VIEW_PROJECTS or BROWSE_PROJECTS permission
  • If you want users to access issues, use both “VIEW_PROJECTS and VIEW_ISSUES" or BROWSE_PROJECTS permission
    • eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “VIEW_PROJECTS and VIEW_ISSUES" or BROWSE_PROJECTS permission

After Stage 1, as a Jira ecosystem developer, you are expected to start updating your apps to use these two new permissions over the period of next 6 months. The BROWSE_PROJECTS permission will still be supported. This is because BROWSE_PROJECTS grant automatically gets copied to VIEW_ISSUES and VIEW_PROJECTS grants. Although, it is recommended to start using the new permissions.

  1. Behaviour after Stage 2
  • If you want users to access projects, use VIEW_PROJECTS permission

    • eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either VIEW_PROJECTS permission
  • If you want users to access issues, use both “VIEW_PROJECTS and VIEW_ISSUES" permission

    • eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “VIEW_PROJECTS and VIEW_ISSUES" permission

After Stage 2, as a Jira ecosystem developer, you will need to update your apps to use these two new permissions. This is because support for BROWSE_PROJECTS will be removed.

These changes will be reflected in The Jira Cloud platform REST API documentation to once we start rolling them out to everyone.

How do the changes look?

API Changes:

There won’t be any structural changes, but some semantic changes as follows:

Example 1: Let’s say a user has BROWSE_PROJECTS permission assigned in the scheme. Jira will automatically copy this grant to the new permissions VIEW_PROJECTS and VIEW_ISSUES after Stage 1.

This is how get my permissions API will behave 1.) Currently, 2.) After stage 1 rollout and 3.) After Stage 2 rollout-

  1. Current behaviour:
GET /rest/api/2/mypermissions?permissions=BROWSE_PROJECTS&projectKey=AB

The permission check depends on the grants against BROWSE_PROJECTS permission.

{
  "permissions": {
    "BROWSE_PROJECTS": {
      "id": "10",
      "key": "BROWSE_PROJECTS",
      "name": "Browse Projects",
      "type": "PROJECT",
      "description": "Ability to browse projects and the issues within them.",
      "havePermission": true
    }
  }
}
  1. After Stage 1 rollout:

The permission check depends on the grants against VIEW_PROJECTS instead of BROWSE_PROJECTS permission. Although you can still use BROWSE_PROJECTS.

We recommend you to change the API call to pass VIEW_PROJECTS instead of BROWSE_PROJECTS when check is done using project key or project id.

GET /rest/api/2/mypermissions?permissions=VIEW_PROJECTS&projectKey=AB
{
    "permissions": {
        "VIEW_PROJECTS": {
            "id": "-1",
            "key": "VIEW_PROJECTS",
            "name": "View Projects",
            "type": "PROJECT",
            "description": "Ability to view projects.",
            "havePermission": true
        }
    }
}

Similarly, we recommend you to change the API call to pass VIEW_PROJECTS and VIEW_ISSUES instead of BROWSE_PROJECTS when check is done using issue key or issue id.

GET /rest/api/2/mypermissions?permissions=VIEW_PROJECTS,VIEW_ISSUES&issueKey=AB
{
    "permissions": {
        "VIEW_PROJECTS": {
            "id": "-1",
            "key": "VIEW_PROJECTS",
            "name": "View Projects",
            "type": "PROJECT",
            "description": "Ability to view projects.",
            "havePermission": true
        },
        "VIEW_ISSUES": {
            "id": "-1",
            "key": "VIEW_ISSUES",
            "name": "View Issues",
            "type": "PROJECT",
            "description": "Ability to browse issues within a project.",
            "havePermission": true
        }
    }
}

After Stage 2 rollout:

BROWSE_PROJECTS permission no longer supported. As a result, the permission check will return an error saying Unrecognized permission.

GET /rest/api/2/mypermissions?permissions=BROWSE_PROJECTS&projectKey=AB
{
  "errorMessages": [],
  "errors": {
    "BROWSE_PROJECTS": "Unrecognized permission"
  }
}

The recommendation is to make sure all the code references to call the API are using VIEW_PROJECTS and VIEW_ISSUES permission.

UI changes:

Here are some screenshots from the Permission Schemes page that indicates the changes mentioned above.

Browse Projects has a “Deprecated” tag with it, and View Projects has “New” tag with it.
Note: Although Browse Projects permission is marked as “Deprecated”, it can still be used, until it the support is completely removed after Mar’23

View Issues lie under the Issue Permissions category, with a “New” tag with it

Thank you in advance for working through these changes and for your continued support.

If you have any concerns or questions about these changes please don’t hesitate to reply below.

Best,

Varad Pingale

Jira PM

6 Likes

Hi Varad,
I was wondering if you could share how this will affect project entity properties? Will they require VIEW_ISSUES permissions (since some of them could be “content based”) or will they be readable based on the VIEW_PROJECT permissions?

If it’s the later - will you be introducing another mechanics for project based issue entity properties that is attached to the VIEW_ISSUES permissions?

Thanks,

/Daniel

5 Likes

Love to hear that this coming, very much looking forward to our users being able to see available projects, so they can request access to them, rather than being in the dark about what projects are in Jira.

1 Like

I have a few questions coming from the perspective of a Jira Cloud admin.

  1. Does the Jira Cloud admins have to update the all the permission schemes manually or the updates will be done automatically with a tool? This is a challenge for sites with a lot of permission schemes. It is an administrative nightmare to get inputs from project owners to decide on the new permissions.

  2. Is the Permission Helper going to be updated for this?

  3. Is Jira Cloud Migration Assistant (JCMA) going to be updated for this? Will it affect the migration of Server instance to Cloud?

  4. Thinking aloud, will it be easier to retain BROWSE_PROJECTS permission as it is and introduce VIEW_PROJECTS as a new permission? This permission can be granted to allow users who does not have BROWSE permission but need to view the projects.

3 Likes

Hi Daniel,

I will check with my dev team and get back to you soon.

Meanwhile, we have rolled this out to the EAP cohort as mentioned in the post. In case you are part of that, I would request you to try out these scenarios.
Thanks

Hi, Thank you for the questions

  1. The updates will be done automatically. So admins for sites with lots of permissions don’t have to worry about it.
  2. Yes, Permission helper will be updated for this
  3. I will check it and get back to you soon. As of today, we believe it won’t impact the JCMA, but I’ll still make sure and reply back.
  4. We had considered that as an option, although we wanted to avoid confusion by not keeping 2 permissions that behave similarly. I will keep you posted if there are any updates on this.
1 Like

As a Jira admin and vendor i had the same thought as huasoon that leave browse projects as is and just add the new view projects privilege.

Much smaller change and non breaking. Also prevents need to check 2 separate privs because (to me) the browse project/view issue implies the user can see the project.

Is there a use case where a user would need view issue and NOT view project?

My 2 cents
Chris

1 Like

Hello Varad,

Today, Sept’23 I’ve tried:

  • https://<mysite>.atlassian.net/rest/api/3/permissions - no VIEW_ISSUES permission.
  • https://<mysite>.atlassian.net/rest/api/3/mypermissions?permissions=VIEW_ISSUES - error “VIEW_ISSUES”: “Unrecognized permission”

Is the stage 1 postponed?
Ondrej

I guess Sept’22 meant somewhere in September 2022, not 22th of September. Just saying.

1 Like

@stefan_hc @VaradPingale Aha I am sorry, my misunderstanding, so I’ll wait till October’22.

1 Like