Action required: Update scopes for Forge and OAuth 2.0 (3LO) apps

Announcements
, ,
1

UPDATE: Granular scopes rollout has been paused, please see the Changelog announcement for more details

Hi, I am Julia Daehne, Ecosystem Product Manager at Atlassian. One of my main focus areas is app security which we know is a big requirement for our existing Cloud customers, and those who are still planning to move to Cloud.

What’s changing?

We will be rolling out the availability of new scopes for Forge and OAuth 2.0 (3LO) apps built for Jira platform, Jira Software, Jira Service Management, and Confluence Cloud over the next day. During this time, you will see details about these new scopes in Forge CLI and the developer console.

These new scopes help app developers limit what data their app requests from a customer’s Atlassian instance and provide customers with greater visibility into what data apps have access to. If you are a developer of OAuth 2.0 (3LO) or Forge apps, you should receive an email notification from Atlassian about this announcement in the coming weeks.

On January 26th, you may have noticed some of these elements started to appear, however we made the decision to roll back the release of new scopes after discovering several technical issues. This is not the experience that we want our developers to have, and we are committed to better communication and transparency with new feature releases. These issues have been addressed, and we can now share details about this release.

What action do I need to take, and by when?

Forge and OAuth 2.0 (3LO) apps must use the new scopes by August 23, 2022 , within the standard Atlassian 6-month deprecation timeframe. If you have not updated your scopes by August 23, 2022 , and your app is still using old scopes, it may not function as expected for new customers who attempt to install your app.

We understand that updating your app’s scopes impacts your workload as you weigh this request against other platform work. We believe this work will be worth the effort as data security continues to be top of mind for Atlassian customers.

Why are scopes changing, and how does this benefit me as a developer or partner?

The new scopes allow finer control over app access to data. This improvement brings Forge and OAuth 2.0 (3LO) apps better in line with data management and security best practices. Keeping data access permissions at the minimal level reduces the risk that app developers take on, and increases security for app customers.

How do I update my app scopes?

For Forge apps For OAuth 2.0 (3LO) apps
1. Ensure your Forge CLI is version 2.1.0 or later. Please refer to this documentation to upgrade to the latest Forge CLI package.

2. Run forge lint --fix to add the new scopes to the manifest.

3. Remove the deprecated scopes from the manifest file. 		1. Review your app to determine all of the operations used.

2. Consult the relevant REST API reference documentation to determine the scopes needed for each operation and create a list of scopes.

3. Update the scopes in the developer console.

You can save your progress and come back later to continue updating your scopes.

Use the following reference documentation to help you update your scopes:

How will updating my scopes impact my customers?

  • For Forge apps:

    • Once you have completed the process of updating your app’s scopes and saved your changes, a new version of your app will need to be made available.
    • Admin users must update to the latest version of the app.
    • Once they do, each user of your app will see a reauthentication pop-up the next time they use your app that will display what actions your app takes and the information it needs to access (example shown below).
    • The pop-up will link to an FAQ web page where customers can learn more.

  • For OAuth 2.0 (3LO) apps:

    • Once you have completed the process of updating your app’s scopes and saved your changes, users of your app will see a reauthentication pop-up the next time they use your app that will display what actions your app takes and the information it needs to access (example shown below).
    • The pop-up will link to an FAQ web page where customers can learn more.

Screen Shot 2022-02-09 at 5.22.01 pm
Screen Shot 2022-02-09 at 5.22.01 pm1472×1534 233 KB

How can I ask questions and provide feedback?

Please ask questions and provide feedback directly on this community post.

Thank you for taking the time to read this update, and for your help as we look to enhance app security.

FAQ

Q. What if I can’t update my scopes all in one go?
A. You will be able to save your progress and come back to continue updating your scopes at any time throughout the 6-month deprecation period window.

Q. Will this change how the customer is licensed for applications?
A. No, there will be no changes.

Q. Which apps are affected by this change?
A. This change will affect Forge and 3LO apps.

Q. What happens if I am not using version 2.1.0 or later of the Forge CLI?
A. If you have not upgraded to version 2.1.0 or later of the Forge CLI and your app is still using old scopes, forge lint will throw a permission-scope-required error. The error message will state that granular scopes (e.g. read:comment:jira in the example below) are required. Please upgrade to version 2.1.0 or later of the Forge CLI package.

error    Jira endpoint: GET /rest/api/3/issue/{issueIdOrkey}/comment requires "read:comment:jira" scope  permission-scope-required

Q. I am seeing an error like the one below when I run forge deploy . What do I do?
A. Please upgrade to version 2.1.0 or later of the Forge CLI package.

Error: Your version of Forge CLI is no longer supported.
Run npm install -g @forge/cli to update to version 2.1.0 or later of the Forge CLI package.

Q. I am seeing a warning like the one below when I run forge lint . What do I do?
A. Please upgrade to version 2.1.0 or later of the Forge CLI package.

Warning: Your version of Forge CLI is out of date. We recommend you update to version 2.1.0 or later to get the latest features and bug fixes.
Run npm uninstall -g @forge/cli followed by npm install -g @forge/cli to update from an older version to the latest version.

Q. If I am transitioning my app from Connect to Forge during this 6-month timeframe, how will it affect me?
A. When you are transitioning from Connect to Forge you will transition to the new scopes so there is no additional migration step.

Q. If my customer does not reauthenticate my app when the pop-up appears, what will happen?
A. The app update will only become available once the user has approved the changes.

Q. Will Atlassian support old scopes and new scopes for a period of time?
A. Yes, old scopes are supported throughout the deprecation period.

Q. Do I need to do this once for all of my apps or once for each app?
A. Once per app.

Q. How else can my customers see what data my app is accessing?
A. At this point in time, this pop-up message to notify users will be the only way. However, in the future, updating your scopes will allow us to enable other ways for customers to gain transparency into the data your app has access to.

8 Likes
5

Thank you for the detailed announcement, @JuliaDaehne.

Would you mind clarifying the following point:

For OAuth 2.0 (3LO) apps:
Once you have completed the process of updating your app’s scopes and saved your changes, users of your app will see a reauthentication pop-up the next time they use your app that will display what actions your app takes and the information it needs to access (example shown below).

I do not think this is correct. With OAuth 2.0 (3LO) apps there will be no pop-up unless we add such a functionality explicitly to my app. I do not see how else there would be an Atlassian-triggered pop-up.

I think the information on the following questions is missing for 3LO apps:

  1. How do I coordinate setting the new/migrated scopes live and updating the authorization URL? If the new scopes are live, will an auth flow using the old scopes fail?
  2. What happens to existing grants once I have set the new/migrated scopes for my app live? Do they still work until the end of August or are they broken?
  3. Assuming exiting grants are still working after setting the new scopes live: What would the migration process of existing grants look like? And, how do we know a user has migrated/reauthenticated?
    I assume with 3LO apps we are on our own to handle this (there will be no pop-up unless we implement something like that). Can we call the accessible resources endpoint (which returns granted scopes) to check if the user has reauthenticated or still has the old scopes?
3 Likes
6

I’m going through and looking at the rest calls we’re making. Some of the rest end points have a long list of scopes for a single rest call. Do we need to add all of them or just any of them (I’m assuming all of them) - what’s the expected behavior if we leave one out by accident (trying to establish how much of a headache we’re about to have).

Also - there are some rest end points in the docs that don’t list oauth scopes:
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-values--apps-/#api-rest-api-3-app-field-value-post

Are those coming?

7

Yes you would have to check your app’s old scopes and see what new granular scopes refer to the old one. You then select those scopes that your app needs to function (may or may not be all). Once you updated the scopes you click the URL at the bottom of the screen to authenticate your app and check if all is working as it should.

As for custom fields: manage:jira-configuration has now become read:custom-field-contextual-configuration:jira and write:custom-field-contextual-configuration:jira
https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/?_ga=2.196521711.252804868.1645480835-1908867173.1644901529

8

Sorry if “pop up” was misleading. What it means is that once you have completed the process of updating your app’s scopes and saved your changes, users of your app will need to go through a re-authentication process the next time they use your app. The re-authentication screen will display what actions your app will take and the information it needs to access.

When you update your app scopes new consent is always needed. If you are still using the auth URL for the old scopes after you moved to new granular scopes it will fail as it checks what scopes have been given to the app

You should be able to use Link

9

@JuliaDaehne Hmm, so in simple terms, this means as soon as we set the new scopes live all the existing grants will be invalid, API requests with tokens issued based on the old grants will fail and users need to reauth to make it work again.

Wow, this is creating a big headache for us, in particular, because once we enable the new scopes it’s doomsday for all customers at the same time. To make matters worse, our OAuth connection is shared in the third-party system, i.e. it will be not just one user that’s affected but whole teams.

5 Likes
10

@tbinna I’m sorry to hear this is making life hard for you guys. This is certainly not what we intended with this change. Security is a big concern for our customers and Granular Scopes is one of our key security initiatives to address this. Therefore we are hoping that re-consenting to new scopes won’t be too disruptive for customers and instead be seen as an important step towards more app transparency and security

11

Sorry,
I don’t think I explained myself properly.

If I have 2 rest end points A and B.

Rest end point A has me add the following scopes:
ScopeA
ScopeB
ScopeC

Rest end point B has me add the following scopes
ScopeB
ScopeD

Later down the line I decide that I don’t need to use rest end point B but I get too carried away with removing the scopes and remove both ScopeB and scopeD from the manifest.

What happens with rest end point A? What does atlassian think should be happening? Is it going to fail totally or am I just going to have lost the data that ScopeB would have retrieved?

As far the custom field note - the oauth scope is missing on some of the rest end points - will they be added?

1 Like
12

The thing is: Oauth2 is already a mess in multi-instance scenarios.
Users need to choose which instance they want to consent for in all cases.
We cannot default and we do not know what instance has been approved by the user afterwards.

So what you are planning to do, when invalidating all tokens:
User will force to relogin, needs to remember which is the correct instance for this scenario, make sure it doesn’t select the wrong instance by accident. One mistake would ruin all links that has been created so far.
And the re-consent needs to be done for each instance in each scenario.

If security comes first and for whatever reason there is no grace period for existing customers (or just grant all matching scopes based in the previous consent) you might want to consider adding more controls in the oAuth2 flow, so we as partners are able to create a good customer experience. E.g. default the instance or know what instance has been consented to.

We know what consent is missing and could guide the user if you would provide the possibilities to do so.

3 Likes
13

What happens with rest end point A? What does atlassian think should be happening? Is it going to fail totally or am I just going to have lost the data that ScopeB would have retrieved?

Want to second what Daniel says. It is not clear to me how you think about scopes. Do I need all scopes to access a specific resource? What happens if I have a subset of scopes - will I get the subset of potential information?

14

We have already asked them to re-consent last month when the token changes were made. Now we have to do it again. I don’t understand why there is no grace period.

We have customers all over the globe so there isn’t a convenient time for us to make the change and get everyone to re-consent. This means some customers are guaranteed to end up with failures. This is not going to go down well with our customers.

Can Atlassian re-consider applying an appropriate grace period to ensure a smooth transition for our customers? A grace period of a few of weeks (from app owners updating the scopes to users re-consenting) wouldn’t impact your security concerns. This can all be done before the Aug deadline.

5 Likes
15

Hi @FatmehShuman I understand where you’re coming from. Please note that there is no need to update scopes right away. You have up to 6 months to do so

16

Hi @danielwester thanks for clarifying the question: when you don’t have the required scope to call the endpoint, the endpoint will throw an error… so it will fail (ping @andreas.schmidt )

As for the rest end points in the docs that don’t list oauth scopes: it looks like there are no scopes required to hit this endpoint but I will re-confirm with Product team and get back to you

17

@JuliaDaehne the concern here is not that we do not have time to update the scopes. The concern is that once we have updated the scopes and set them live our app breaks for all customers immediately.

To make matters worse, as Andreas mentioned in his post, the reauth process is very fragile for many reasons. This is also a problem for us. If users reauth the wrong way the integration will not work as expected and lead to additional support requests.

The suggestion would be to at least allow users to use their existing grant (once we have updated and published the new scopes) for some time until the app actually breaks. This is to give them time to reauth when they are ready.

Hope the request is clear. Happy to clarify further otherwise.

5 Likes
18

Going to echo @tbinna and @FatmehShuman here in that this is going to create a massive problem for us and our customers in the way this rollout has been communicated to be carried out so far.

I don’t think anybody here is arguing that moving forward with trying to make things more secure with granular scopes is a bad idea or arguing against it. Some apps (like ours) have hundreds of customers with automations that run in the background largely untouched by the people that initially authenticated and created them. Getting them to re-authenticate with each and every domain they have setup is going to be a nuisance in and of itself, but given enough time to proactively message each user, explaining that it is required in the spirit of improved security on Atlassian’s part, is a pill they will hopefully swallow easily. Especially if they are given enough time to seamlessly do so.

With what you have described here, unless I am misunderstanding, it seems like there is no way we are going to be able to do that proactive messaging and allow our customers to seamlessly re-auth without breaking the app for everybody. Once we go into our 3LO app and update and save the new granular scopes, instantly all our customers existing grants and their tokens will no longer work until they go and re-authenticate. All the existing running automations for every single one of our customers will be broken. Atlassian has to understand this is a terrible experience for vendors and their customers.

As @tbinna and @FatmehShuman have suggested, when saving the new granular scopes in our app configs, instead of instantly invalidating all existing grants, allow those grants to still be valid and work for an extended grace period until the tokens no longer work and all customers would then have had to re-authed. This way, once we save the new scopes, we have that period of time to reach out to each of our customers to instruct them to re-authenticate at their leisure at a time that is convenient to them (since our app allows for the building of background automations, we will probably have to remind customers more than once over an extended period of time before they actually act).

Thanks, I hope that helps clarify. Also happy to expand on this or talk about it further if needed.

3 Likes
19

Hi @danielwester confirmed: it’s handled internally by Jira. so no scopes are required by this endpoint

1 Like
20

Just a feedback, i can’t tell if the situation is still the same.

I tried the forge lint --fix after the official announcement to automatically fix my manifest scopes and nothing happened.
I was using the cli version 3.0.0

21

Can that be documented on the rest documentation? Cause not having “no scopes required” (or equivalent) will get really confusing real quick when we have to start guessing which scopes are required.

22

That’s really unfortunate. I really feel that Atlassian isn’t thinking a about the developer experience it seems.

Fast forward 3-6 months on any forge app when they things there’s a scope that can be removed - all rest api’s and their documentation has to be reviewed. I won’t even go into the entire concern of what Atlassian decides a scope should be added to a rest end point.

While I understand that Atlassian had to get the feature out - it seems that in the long run the developers on the platform will pay the price.

Any chance that there is some feature/utility to safely identify which scopes are not used?

2 Likes
23

Yes we can do that. Thanks for bringing this up @danielwester