How to secure Jira and Confluence REST API calls in Data Center
Out-of-the-box authentication methods
The REST API exposed by Jira and Confluence Server or Data Center is protected from unauthorized access. To access, a caller needs to demonstrate its identity, but also have the corresponding permission to take a particular action in Jira or Confluence. So both authentication and authorization are used to secure access to the REST API.
When integrating with Jira and Confluence, there are four different methods that can be used to authenticate the caller:
- OAuth (available in Jira)
- Basic authentication
- Cookie-based authentication (available in Jira)
- Personal access token (since Jira v8.14, JSM v4.15, Confluence v7.9)
In this article, we will detail each of the four methods and how they work.
OAuth JIRA ONLY
OAuth is an authorization mechanism that contains an authentication step. Jira Server/Data Center uses OAuth 1.0a, 3-legged OAuth (3LO). In this process, a user (called the resource owner) grants a third-party application (called the consumer/client) access to some information (called the resource). 3LO means that the resource owner is directly involved with authorizing access to the resource, as opposed to 2-legged OAuth, where the resource owner is not involved. See below to visualize how the process works:
Get more info about the authorization flow here: OAuth
The tokens that are used with this OAuth method have nothing to do with personal access tokens. For more information about them, see the "Personal access token" section below.
This method is the one of the most secure among the ones that are available out-of-the-box in Jira Server/Data Center. However, it’s the one that takes the most effort to implement, as it will require you to configure an application link (playing the role of consumer/client) and a library in order to make the calls.
See how to configure OAuth 1.0 to be used for the REST API calls: OAuth | Before you begin
Basic authentication
Basic authentication is the simplest way to authenticate a REST API call. In short, it sends a username and password in every request, contained in an
Authorization: Basic <credentials> header, where credentials are the username:password Base64 encoded.Security flaws
- Credentials are sent in a form that can be decoded easily (Base64). This could be solved by securing the connection using TLS/SSL.
- The password is sent repeatedly, for each request, which opens up a larger attack window.
- The password is cached by the browser, so it can be silently reused by any other request to the server.
- The password may be stored permanently in the browser, if the user requests. This creates a similar risk as the previous point, and also may allow it to be stolen by another user on a shared machine.
-
Get more info about basic authentication and Jira REST API: Basic authentication
-
Learn how this can affect the REST API calls: CAPTCHA
Disabling basic authentication in Jira
In Jira Server/Data Center v8.16, the basic authentication method can be disabled natively.
- Learn how: Disabling basic authentication
When basic authentication is disabled, you can still create an allowlist for specific users and URLs to use basic authentication in REST API calls.
Cookie-based authentication JIRA ONLY
Cookie-based authentication will create a session object when logging in that will be reused for the subsequent calls. Here's how it works:
- The client creates a new session for the user via the Jira REST API (calling the session resource
/auth/1/sessionwith a username and password). - Jira returns a session object that has information about the session, including the session cookie. The client stores this session object.
- The client can now set the cookie in the header for all subsequent requests to the Jira REST API (
Set-Cookie: JSESSIONID=6E3487971234567896704A9EB4AE501F; Path=/; HttpOnly).
-
Get more info about cookie-based Authentication and Jira REST API: Cookie-based authentication
-
Learn how this method is affected by cookie expiration, CAPTCHAs, and form token checking: Advanced topic
Personal access tokens
Personal access tokens (aka API tokens) were created to provide a more secure way to authenticate for third-party integrations. Already available in Bitbucket and Bamboo (for both Server and Data Center) and also in Cloud products, personal access tokens have been recently added to Jira (v8.14), JSM (v4.15) and Confluence (v7.9) Server/Data Center.
How personal access tokens work
- A user can create or revoke their own personal tokens via the User Profile screen.
- These tokens are to be used for REST API calls only, they cannot be used to log in to the product UI.
- The individual tokens will inherit the user’s existing product permissions.
- Tokens can be expiring (specified in days) or non-expiring. The ability to create non-expiring tokens can be switched-off with the
atlassian.pats.eternal.tokens.enabledsystem property (trueby default). - The user can create a maximum of 10 tokens — this can be adjusted with the
atlassian.pats.max.tokens.per.usersystem property. - To see other system properties that can be configured, see the "System properties" table below.
- Once generated, the token given to the user cannot be retrieved, it needs to be remembered.
- Tokens are immutable, i.e. they can’t be changed after they have been created.
- When a users successfully authenticates to the REST API using a created token, the “Last authenticated” timestamp is updated in the token list.
- Admins can administer user tokens, including viewing, searching, and deleting.
- To invoke a REST API call using the token, an HTTP Bearer authorization header has to be included:
1curl --header 'Authorization: Bearer NDcwNDQ0NTQ2MzE5Ol7lyYmNQ8WynnNMlhW2MpewDjGr' http://localhost:2990/jira/rest/api/2/project- A token itself can be created through the REST API:
1curl --request POST 'http://localhost:2990/jira/rest/pat/1.0/tokens' \2--header 'Authorization: Bearer NDcwNDQ0NTQ2MzE5Ol7lyYmNQ8WynnNMlhW2MpewDjGr'3--header 'Content-Type: application/json' \4--data-raw '{5 "name": "Yet Another Token!",6 "expirationDuration": "90"7}'How the token is built and managed internally
- The token is made up of two parts, the ID and the secret.
- The ID is a 12 digit number that represents the username.
- The secret is 20 bits of random data.
- The ID, a ":" character, and the secret are concatenated, then base64 encoded. This token is returned to the user.
- The secret is put through our default password encoder and is stored hashed and salted in the database along with the plain text ID number.
Therefore, we could say that in the database at rest, the token's secret is stored cryptographically salted and hashed, however, the raw token is returned to the end user and then sent to Jira during authentication.
In transit, this token would be subject to whatever protocol encryption is enforced between the client and Jira, for example, TLS.
System properties
Property | Default | Description |
|---|---|---|
atlassian.pats.enabled | true | Whether personal access tokens are globally enabled |
atlassian.pats.eternal.tokens.enabled | true | If users should be able to create tokens that do not expire |
atlassian.pats.mail.notifications.enabled | true | Whether mail notifications are globally enabled |
atlassian.pats.last.used.update.interval.mins | 1 | The interval at which the scheduler job is updating the 'last accessed at' property of each token, in minutes |
atlassian.pats.pruning.schedule.cron | 0 0 0 * * ? - 12 am local time, every day | The CRON expression for the expired token pruning scheduler job |
atlassian.pats.pruning.delay.days | 30 | The delay before expired tokens are removed from the database, in days |
atlassian.pats.max.tokens.expiry.days | 365 | Maximum number of days for a token to expire |
atlassian.pats.max.tokens.per.user | 10 | Maximum number of tokens allowed per user |
atlassian.pats.auth.cache.expiry.mins | 60 | The length of time, in minutes, an item can stay in the authentication cache before being removed |
atlassian.pats.auth.cache.max.items | 5000 | The maximum number of items allowed in the authentication cache |
atlassian.pats.expiry.check.schedule.cron | 0 0 * * * ? - every hour | The CRON expression for the scheduler job that sends notifications about expired tokens and tokens that will expire soon |
atlassian.pats.expiry.warning.days | 5 | How many days before sending an e-mail notification about tokens that will expire soon |
atlassian.pats.invalidate.session.enabled | true | If the session should be invalidated after succeeded authentication using personal access token |
atlassian.pats.token.name.length | 40 | The maximum number characters to be used for token name |
Note: You have to set these properties on every node of your Data Center instance.
How to add more security to the REST API calls
Besides the out-of-the-box authentication methods, we can provide more security to the Jira REST API by adopting additional measures.
Rate limiting
Rate limiting targets only REST API requests and can help you address the potential impact from spikes in requests from automated external requests and/or scripts. When users move around the Jira UI, viewing projects, transitioning issues, and completing other actions, they won’t be affected by rate limiting. This feature will enable admins to configure per-user limits for REST API calls. If users overdraw their limit, their requests will result in a 429 error code and the request will not be processed.
Anonymous traffic is represented by one user called “Anonymous”. This “user” aggregates all anonymous traffic into one bucket for all sources of anonymous requests.
There are different ways to set the limit: by node, user, time frame, and/or number of requests.
The UI allows system admins to:
- Set a default per-user limit
- Set per-user exemptions (limits different than the default, whether more restrictive or less restrictive)
- Set an exemption for the aggregated anonymous traffic
- See who is being limited across all nodes in the cluster
How rate limiting and personal access tokens work together
Rate limiting kicks in after authentication, so the per-user limits and exemptions also apply when using personal access tokens.
What rate limiting is based on
- A token is needed to make HTTP REST requests.
- Each request costs one token.
- Users get new tokens at a constant rate so they can keep making new requests. This represents the number of requests they are allowed, and can be, for example, ten every one minute.
- Tokens are added to a user’s personal bucket until it’s full. This is their max number of requests, and they can adjust the usage of tokens to their own frequency, for example twenty every two minutes instead of ten every one minute, as specified in their usual rate.
- If the bucket becomes empty, HTTP REST requests will not be processed and a 429 error code will be returned.
Getting started
Setting the right limit depends on a lot of factors, and there isn't a single rule that will work for all scenarios. To start finding the right limit, it's important to understand the size and traffic that instance receives and work from there.
To better understand the size of traffic, start by parsing the access log. Find the user that made the most REST requests over a day. Since UI traffic is not rate limited, this number will be higher than what you need as your rate limit.
Generally speaking, your goal in setting a limit should be to keep the instance safe from scripts going haywire, rather than stopping users from getting their work done.
- By default, all configurations are set to disabled.
- Admins have the choice of three options:
- Allow unlimited requests (can still block individual access through exemptions)
- Block all requests (can still allow individual access through exemptions)
- Limit requests (set a common limit for everybody, and use exemptions to assign individual limits)
- Exemptions allow you to customize rules for unique users.
- Exemptions can be created when rate limiting is disabled. The features will not work until rate limiting is enabled.
- It is possible to add multiple users to an exemption.
- Beyond this new rate-limiting algorithm and rule set, the API endpoints and the way you engage the API remains the same.
Turning rate limiting off
To turn it off, go to System → Rate Limiting, select Rate Limiting → Disable, press Save. Wait 60 seconds for the changes to be visible.
Note that by default, rate limiting is turned off. When turned on, it's set to “Allow unlimited requests” by default, which means it has no effect unless configured differently.
Impact to users that are rate limited
When users make authenticated requests, they will see rate limiting headers in the response. These headers are added to every response, not just when they’re rate limited:
Header | Description |
|---|---|
X-RateLimit-Limit | The bucket size (capacity) |
X-RateLimit-Remaining | The remaining number of tokens. This is what you have and can use right now. |
X-RateLimit-Interval-Seconds | The time interval in seconds. You get a batch of new tokens every such time interval. |
X-RateLimit-FillRate | How many tokens are added to the bucket on each refill. Sys admins configure this as Requests allowed. |
retry-after | How long you need to wait until you get new tokens. This value is 0 when the bucket is not empty. If the bucket is empty, this value is likely to not be zero. |
Benefits of "self-protection" capabilities
- Visibility: gives you the ability to see who is being rate limited, how many times requests are being limited, and when a user was last limited
- Security and control: admins are able to set custom configurations and add users to an allow-list, bypassing all restrictions
- Stability and performance: rate limiting helps to regulate CPU volume
Related info
API gateway/proxy
In some contexts, you may be interested in having more control over how the Atlassian product APIs are being used. In such contexts, you can introduce a new component to your API architecture: the API gateway. With this component (external to the Atlassian product architecture), you can usually expect the following aspects to improve:
- Tracking of API calls: who is invoking the APIs, when, how much, etc.
- Authentication/authorization: API gateways enable admins to add an additional security layer and provide support for methods that are not yet supported natively by the Atlassian Data Center products (e.g. OAuth 2.0)
- Filtering of API calls: API gateways can provide additional filtering capabilities to those provided out-of-the-box by the Atlassian Data Center products
- API management: API gateways can be part of the corporate API management
Sample architecture with an API gateway protecting a dedicated API node for Jira/Confluence
Marketplace apps
Using this app, you can authenticate Jira APIs using any third-party OAuth/OIDC provider or API tokens. The app supports Azure AD, Keycloak, Okta, AWS Cognito, Google, Github, Slack, Gitlab, Facebook, and any custom provider.
This app solves one of the biggest challenges in SSO-enabled applications: when users don't know their local account passwords.
Features provided:
- Allows you to disable Jira's basic authentication or OAuth 1.0 authentication
- Supports creating or revoking individual API tokens for users and universal API tokens for services
- One-click enable or disable REST API authentication using OAuth 2.0
This app allows you to authenticate Confluence APIs using third-party OAuth tokens or API tokens instead of your Confluence password. It supports 10+ OAuth providers like Azure AD, Keycloak, AWS Cognito, Google Apps and ADFS, with steps to setup in minutes.
Features provided:
- Allows you to create or revoke API tokens to better secure and manage your data using REST API calls
- Secures all the Confluence APIs
- Coming soon: IP restriction and cookie-based authentication
Was this content helpful?
Connect, share, or get additional help
Atlassian Community