What’s changing?
Bitbucket is changing the way in which UI components of Connect applications communicate with Bitbucket’s API. We are making changes to ensure that users are aware of (and can deny) when an Bitbucket application is attempting to access their user data. Please note, this approval is not granting the app access to their personal repositories (that is repositories outside of the installation workspace). It does however give the app the ability to perform actions on behalf of the user in repositories accessible to the workspace the app is installed into (If the appropriate scope has been granted).
Once the access is granted, there is no further impact on the application.
Why is it changing?
The current implementation assumes user approval, and could be used to maliciously gain access to user data.
What’s actually changing?
The Connect javascript library provides an easy way for Connect apps to make authenticated requests back to Bitbucket on behalf of the current user. There are a two different types of requests: request and proxyRequest, and the changes impact requests made by both.
When the above functions are invoked Bitbucket generates an access-token which is used to authenticate the requests. Previously theaccess-token were generated without the explicit approval/acknowledgement of the user.
With the new changes, when a request is made a access request dialog will prompt the end user to review the permissions and either Allow or Deny the access. This happens prior to the access-token being generated. The user’s response will be persisted, and future requests will be appropriately allowed or denied. This is consistent with how the approvals and denials work for Bitbucket’s OAuth implementation.
Personal applications will not require reviewing of permissions of the access request.
The approvals and denials that a User has authorized are listed (and can be revoked) from the Bitbucket settings page Personal Settings → App Authorization. If the user revokes an approval or denial, the next time the a Connect JS request is made the Access request dialog will be prompted again.
For Shared Applications
If a vendor updates their Application with increased scopes, any existing approvals (For all users) tied to the old version of the Application will be revoked. This will cause the Access request dialog to prompt the user the next time a request is made to Bitbucket from the Connect JS.
Once a user has approved access of a shared application, that approval will persist and be respected for any other installations of the same Application.
For classic add-ons
Classic add-ons do not have a consolidated way of pushing updates to installations, It’s up to the admin of the workspace to “update” the installation. As such, if a user accesses the same classic add-on installed into two different workspaces, the user will have to approve the access to both independently of each other. If one of the classic add-ons is updated, only approvals tied to that particular installation of the add-on will be revoked.
Note - Denials will persist even when the Application or Classic add-on is updated. The user has to manually revoke this denial via Log in with Atlassian account
What do vendors need to do to support the changes?
As users are now given a choice to either allow or deny the request access, vendors applications will need to be updated to catch and appropriately handle the case of the request user denying access.
Requests made to Bitbucket using the JS request or proxyRequest functions allow an error callback to be attached. This handler provides a json object, which provides a concise error message for that request. There are three error codes that are pertinent to this new work, that should be handled appropriately:
- USER_DENIED_ACCESS - This error code is produced after the user presses the Deny button
- USER_ALREADY_DENIED_ACCESS - This code will be returned for every subsequent request made (whilst there is a denial present)
- ACCESS_TOKEN_REQUEST_FAILED - The error code is produced if the user fails to press the Approve or Deny button with in a period of time
Javascript example
Below is a javascript code snippet which makes a GET request to 2.0/users and handles the pertinent error codes and pops a message box in Bitbucket notifying the user.
Please note you don’t have to popup this message box, this example is here to highlight how to catch the error codes. Please feel free to handle this however you see fit.
/*
Ideally the below on_error handler should be attached to every AP.request made by
your App. However, if your application makes a request on window.load, attaching
the error handler to this request will cover 99% of the cases.
*/
function on_error(data){
var error_code = data.code.toUpperCase();
var error_codes = ["USER_DENIED_ACCESS",
"USER_ALREADY_DENIED_ACCESS",
"ACCESS_TOKEN_REQUEST_FAILED"];
if(error_codes.includes(error_code)){
AP.require("messages", function(messages){
var title = 'Access to App has been revoked';
var msg = 'Please visit Bitbucket Settings -> Manage Authorizations to revoke denial.';
var message = messages.error(title, msg);
});
}else{
//Got a normal error, handle appropriately.
}
}
function query_user_api(){
AP.require('request', function(request){
request({
url: '/2.0/user',
success: on_success,
error: on_error
});
});
}
What do users need to do to support the changes?
As an end user, all that’s required is to actually review the access and either Allow or Deny the request. This action will need to repeated when Applications you have installed (or installed in workspaces you access) get updated.
You can manage your approvals/denials in Bitbucket Personal Settings → App Authorizations Log in with Atlassian account
Testing the changes
There are two Bitbucket labs features which can be toggled by users and vendors to test out the new functionality. These can be toggled by users in the Bitbucket Personal Settings → Labs section Log in with Atlassian account.
- Explicit Addon OAuth Token Authorization For Vendors
- Explicit Addon OAuth Token Authorization
These two features work in conjunction to each other. For the new changes to be enabled both the vendor and the requesting user need to have the appropriate lab enabled. If this combination of lab features isn’t met the legacy behaviour will continue.
For Shared Applications
The vendor of the Application should enable the lab feature: Explicit Addon OAuth Token Authorization For Vendors. Please note that once enabled: This will cause ALL installations of ALL applications owned by this user to start supporting this new functionality.
Test user/s should then enable the lab feature: Explicit Addon OAuth Token Authorization.Once enabled, the test users can visit an installation of the Shared Application and should have access to the new functionality.
For classic add-ons
For classic add-ons, there is no way to enable this feature for all installations. We instead need to toggle the vendor lab on a per installation user basis. To do this install the classic add-on in a test users workspace, and toggle the lab feature: Explicit Addon OAuth Token Authorization For Vendors for that user. Please note once enabled: This will cause ALL classic add-ons installed into this account to start supporting this new functionality.
Test user/s should then enable the lab feature: Explicit Addon OAuth Token Authorization. Once enabled the test users can visit the installation and should have access to the new functionality.
When will this change take effect?
The change will be rolled out no sooner than June 1st, 2020.
