Introducing Token Scopes for Jira and Confluence on Premise

[#1]

Have you ever been worried that scripts and API connections to external sources can compromise the integrity of your Jira and Confluence databases? Are you managing access of hundreds or thousands of users to Server or Data Center instances?

If that’s the case, then you know how busy the API can get.

We have built scopes into our very young API Token Authentication app for Jira and Confluence for you: they will make token-based authentication an even more secure alternative to the use of passwords.

How does it work? We have decided to keep it dead simple.

Just choose whether a token can be used for any API method, or only to read from the database.

How token scoping secures access to the Jira & Confluence API

If you’ve ever interacted with an OAuth flow I’m sure that you’re perfectly aware of how central the notion of token scoping is for delegating authorization to third-party apps.

We’re essentially talking about the same function – but instead of OAuth, token scopes will let you specify which methods can be used in API calls using the Jira Server REST API or the Confluence Server REST API.

Read-only

Supported methods

• GET
• HEAD
• OPTIONS

When should read-only tokens be used

This scope should be used for scripts and connections that only need to take information from Jira and share it somewhere else.

For whom are read-only tokens

Sometimes it can be a good idea to stop non-technical users from tampering with Jira and Confluence data by allowing them to create only tokens with this scope. Read the section on Forcing regular users to create read-only tokens below to learn how to do this.

Examples of read-only applications

Notifications and reports are the best example of what you can do with read-only tokens.

However, some simple integrations may also benefit from this. For example, if you want to automate the creation of new cards in the Trello boards that you use with freelance designers whenever a design-type issue is created in Jira.

Read & Write

Supported API methods

All methods are supported in Read/Write tokens. Specifically, this means that all the DELETE, POST, and PUT endpoints in the REST APIs can be called in addition to the list above.

When should Read & Write tokens be used

This scope should be used only for any scripts, integrations or connections with a business logic intended to improve, change or somehow enhance how your Jira (or Confluence) works.

For whom are Read & Write tokens

You may be interested in enabling only by folks with a sufficient understanding of 1) how your processes are currently run 2) what could make them better and 3) how APIs are built, for example being able to tell the difference between the PUT and POST methods.

If that’s the case, you can resort to the app’s permission schemes so that only power users can create read/write tokens, either for themselves or for others. More on that later.

Some examples

The possibilities here are endless, so I’ll just mention some of the actions that are possible with the ability to change data in Jira:

Edit a filter for a JQL search to get exactly the issues you need to work with

• Create or update issues
• Add votes to issues
• Even create new projects

Creating tokens with scopes

Since 1.5.0, the decision to apply one scope versus the other has to be taken every time a new token is created.

Forcing regular users to create read-only tokens

Scopes are applied per token, not per user. However, we have included an option to restrict who can create read/write tokens.

To apply it, navigate to the Permissions tab in the app configuration, then select the box Users may only create "Read Only" tokens.

When the option is activated, only the users with the permission to create tokens on behalf of other users will be able to select the read/write scope when creating a token (either for them or for somebody else).

In summary:

• Users with the permission to 1) create tokens and 2) use them will only be able to create read-only tokens for themselve .
• Only the users with the additional permission to create tokens on behalf of others can apply the read/write scope to the tokens that they create.

Audit Logging of authentication events

There’s also good news for the monitoring nerds! If you’re in charge of controlling the utilization of your Atlassian stack, you will now have the ability to view all API Token authentication events in the app’s audit log.

The audit log will give you interesting insights, like:

• Identifying failed authentications
• Tracking forbidden events, for example when calling a POST method with a read-only token
• Having centralized historical data of 3rd party apps connecting to your instance

Give a try to API Token Authentication 1.50 and check it out for yourself!

API Token Authentication for Jira

API Token Authentication for Confluence