Introducing API Token Authentication for Bitbucket Server and Data Center

Expert Review: Why API Tokens for Bitbucket?

Our good friend Rodney Nissen, aka the Jira Guy, recently reviewed our API Authentication apps. His final judgment was very positive:

It’s an App that when I think of what it can do, I have a hard time thinking of how to improve it. Like SAML SSO, it does what it does better than anything else in the marketplace, but it still gives you the control and flexibility to configure it to work how your teams need it to.

Robust and flexible are two overwhelming adjectives when it comes to evaluating software. You can pretty much read them between the lines when Rodney looks at the major differences in how Atlassian implemented tokens for Bitbucket, compared to how our app does it:

Well, from a user perspective, they are very much similar. So your users might not care one way or another. However, from the admin’s perspective, API Tokens shines through as the more polished product.

Let me explain. For the Personal Access Tokens, the only thing you can do (as an admin) is set an expiry date policy on Tokens. That’s it. Need to revoke a particular Token? Better get that user on the phone.

This is a very important point. When admins are not involved in creating the tokens, identifying which token corresponds to what connection can be quite challenging. Particularly if authentication events are not being logged and there is no real nomenclature around token names.

And what would an admin be able to do instead with resolution’s app? According to Rodney, quite a bit.

Compare that to the permissions, policies, searching, and revoking you can do as the admin with the API Token App, and it’s clear what makes it the better option. For example, you (as an admin) can search for that user, see the logs about how their token was used, and then revoke that specific token without getting the user involved. 

For large organizations who put a high value on making their API ecosystems secure, the native personal access tokens in Bitbucket leave too many open doors for malpractice and poor connection hygiene.

Let’s now have a closer look at the differences between both implementations of access tokens for Bitbucket, before we review what they still have in common.

Differences between Bitbucket personal access tokens and resolution’s API tokens for Bitbucket

Difference 1: Token permissions

In Bitbucket, every user can natively create personal access tokens for themselves. In addition to that, admins can revoke existing tokens. That’s about the end of the story. Administrators cannot, for example, create personal access tokens for other users.

With resolution’s API Token Authentication, there is a very simple and at the same time flexible structure of permissions around three different sets of actions:

• Using tokens
• Creating tokens
• Creating tokens on behalf of other users

 

Companies can easily implement their desired approach to API security. They only need to assign these permissions to different groups. For example:

• a company that wants to implement a policy of strict delegation may give users the ability to only use tokens, while only admins can create and revoke tokens, either for themselves or for other users.
• a different company may decide on a looser approach and assign permission to use, create and revoke own tokens to all users. In addition to that, it could make sense to assign the ability to create tokens for other users to power users (for example, senior devs or product managers) in addition to admins.

Difference 2: Ability to revoke tokens

Let’s look a bit deeper into the particular case of revoking tokens. It’s a good illustration of how both approaches work.

Personal access tokens in Bitbucket can only be revoked by admins. If I want to revoke a token I have created, I need to ask an admin.

On the other side, if I can create a resolution API Token, then I can also revoke it. This means:

• the permission to create tokens includes the ability to revoke them
• the permission to create tokens for other users also includes the ability to revoke them

Again, assigning groups to these permissions implies that the application is extremely flexible and allows each company to work how they see fit.

Difference 3: Advanced network settings

The older brothers of API Token Authenticator for Bitbucket already included interesting security options that aren’t possible with personal access tokens in Bitbucket.

• Restrict API Tokens so they are only accepted if coming from specific IP addresses and ranges. This can be used to whitelist connections from authorized cloud vendors like Salesforce and from your own servers.
  • when running Bitbucket behind a reverse proxy, admins can adjust the app config so that the client IP address making a request with an API Token is read from a different header. This makes it possible for IP address restrictions to work as intended also in that setting.
• Disable password authentication. If you want your users to stop using their passwords to access the API, this is an interesting option!

Similarities between Bitbucket personal access tokens and resolution’s API tokens for Bitbucket

As you have seen, for an admin, the resolution API Token Authentication app provides much more control over who can access the Bitbucket API.

That said there are important similarities. And that’s good, because a user coming from Bitbucket’s personal access tokens can start using API tokens transparently. As the Jira Guy says, bot apps are very much similar from a user perspective.

Similarity 1: Tokens can do what the user can do

For starters, a token will have the same permissions of the user who creates it.

For example, if Mary Smith can fork a repository in project A but not in project B, Mary’s token can be used to fork a repository in project A, but not in project B.

Similarity 2: Token scopes

On top of the user permissions, you can restrict what a token can do even further.

Here’s where the approach differs a bit.

• With resolution’s API Token Authenticator for Bitbucket, you can two types of scopes:
  • Read only permits GET, HEAD and OPTIONS requests
  • Read & write also permits PUT, POST, DELETE
• From Bitbucket, the permission options for personal access tokens are a bit more intricate

Bonus Trick: You can also restrict who gets to create read&write tokens with the options above.

The verdict: When do you need resolution’s API Tokens for Bitbucket?

Now you know the major differences and similarities between both approaches to API authentication with tokens in Bitbucket. But what does this mean for you as an administrator?

If you’re behind a relatively small instance of Bitbucket with very educated users that know what they’re doing and understand the risks of every connection to the Bitbucket API; and if you’ve never had to revoke a personal access token that had been compromised, then you may just go ahead with the native options.

But if you’re watching over a Bitbucket installation where the activity is starting to scale and there is a need for stronger monitoring of which users are connecting to which external services; if there have already been cases of compromised tokens that needed to be revoked, and the process was more painful than it should have been; or if you want to enforce stricter security policies, including that certain users have to request tokens from admins; then it sounds like the time is ripe for evaluating API Token Authentication for Bitbucket.

Start your evaluation

• Start your evaluation of API Token Authenticator for Bitbucket now from the Atlassian Marketplace.
• Evaluate API Token Authentication for Jira or API Token Authentication for Confluence

Keep reading

• Learn more about the apps in our documentation!
• Find out about other alternatives to personal access tokens
• Understand why no-code platforms can’t hash your password before they store it