Best Practices in Jira Administration – API Tokens

12 November 2021
Comments are off for this post
Best practices in Jira Administration with API Tokens

One of Jira’s strengths is that it allows 3rd party integration via REST API calls. By providing the username, password and Base URL, it is possible to 3rd party apps to query or update Jira automatically.

In this article, we will share why using API Tokens is a better and safer option than using Password Authentication.

The Power of Passwords

Besides entering passwords on the Jira login screen, it is also possible to provide the passwords on 3rd party applications or scripts to execute REST API calls.

Some of the use cases are like

  • Create issues from Slack
  • Send alerts to Microsoft Teams
  • Update Jira issues with Commits information from GitHub
  • Integrate with your in-house systems

If the password fails in the wrong hands, it is possible that

  • Wikileaks of your confidential data
  • Your Jira system can slow down drastically due to excessive API calls which affects the usage of other users

Benefits of using API Tokens over Passwords

By using API Token, it improves the security of your Jira instance

  • Safer – The API Token has a certain level of password complexity which defends against dictionary attacks
  • Isolation – It distributes the risk by having a different API token for each 3rd party integration. It is possible to revoke/reset the token for that application without any impact to other applications.
  • Differentiation – With a different mechanism, it is possible to apply more stringent checks on the usage of API Tokens (e.g. restriction by IP address range)
  • Control – It restricts ordinary users from using their credentials to do REST API calls 
  • Availability – For sites running on Single Sign On. Users will not know their passwords other than their Windows passwords
  • Validity – It is possible to set the expiry date of the token

API Token Authentication for Jira

We like the API Token Authentication Jira because it offers the following features:

Disable basic authentication with user passwords

It allows basic authentication with API Tokens. Currently, it is not possible to use the Jira Data Center’s Personal Access Token together with the username on 3rd party websites. 

Personal Access Tokens cannot be used for Basic authentication that is commonly used by 3rd party websites

Warning: If you disable Basic Authentication with passwords in the System Wide settings, you also can’t authenticate on non REST endpoints with API Tokens directly. You can still do that by reusing a session you got from authenticating with an API Token.

Able to limit usage to particular IP ranges

It is possible to limit the usage of the API token to the IP address of the internal system. You can ensure the REST API calls are coming from your trusted network.

You can limit by ip range for API token usage

Block requests with malicious characters in path

This is a bonus feature which helps to defend against some attack vectors.

Block malicious characters in path

Limit usage of API Tokens

It is a security best practice to grant rights only to users who needs it and has proper training. There are incidents arising from users who entered their Jira passwords on 3rd party sites or executed a buggy script.

which users can create API tokens

Tip: We recommend to create a group “jira-api-users” to manage those service account users who can use API Tokens.

Set a validity of the API Token

If the token is for testing or for temporary usage, the Jira admin can just set a shorter validity that will expire automatically. Otherwise it relies on the Jira Admins to remember to revoke the access manually.

Service Accounts typically do not have a password validity. If the service account is from an Active Directory, there could be disruption if there is a 90 day reset password policy.

By using the Active Directory passwords, it is possible that account is locked out of all applications after multiple wrong password attempts.

Control over audit logging

It offers admins a fine level of control over the information to be logged.

What should be audit logged
Logging of failed attempts
audit logging of permission errors