Security helps protect customer data from unauthorized access and from malicious or accidental changes. It also allows administrators to install apps with confidence, letting users enjoy the benefits of apps without worry.
Security has two key parts:
Authentication and authorization methods differ depending on whether you are building an Atlassian Connect app or another type of integration.
These methods are summarized below.
Atlassian Connect apps use JWT (JSON Web Tokens) for authentication. This technology is built into the supported Atlassian Connect libraries. If you use the client frameworks, most security operations are handled for you. Otherwise, you will need to construct and manage JWT tokens yourself. See Understanding JWT for Connect apps.
Atlassian Connect apps can use two types of authorization:
This method relies on two types of authorization:
You define scopes in the app descriptor to specify the maximum set of actions that an app may perform: read, write, etc. This security level is enforced by Atlassian Connect and cannot be bypassed by app implementations. To learn more, read our page on scopes.
The set of actions that an app is capable of performing is the intersection of the statically defined scopes and the permissions of the user assigned to the request. This means that requests can be rejected because the assigned user lacks the required permissions. Therefore, your app should always defensively detect HTTP 403 forbidden responses from the product.
Every app is assigned its own app user in a Cloud instance. In general, server-to-server
requests are made by the app user. Client-side requests are made as the current user in
the browser session, and are supported via the AP.request() method.
To learn more, read Security for Connect apps.
If the app needs to act on behalf of the user, you can make server-to-server requests using OAuth 2.0 user impersonation (see next section).
Connect apps cannot access private personal data by using OAuth 2.0 JWT or AP.request().
User impersonation allows your integration to access Atlassian APIs on a user's behalf. This is provided via the JWT Bearer token authorization grant type for OAuth 2.0, which is also known as two-legged OAuth with impersonation (2LOi). At a high level, this method works by the app exchanging a JWT for an OAuth 2.0 access token (provided by the application). The access token can be used to make server-to-server calls, on behalf of the user, to the application's API.
To learn more, read User impersonation for Connect apps.
Connect is not the only solution for integrating with Atlassian products. External applications or services, scripts, or even bots, can access Atlassian APIs directly. We recommend using OAuth 2.0 authorization code grants (3LO) for these types of integrations, although authentication with an API token is available for writing scripts or making REST API calls manually.
OAuth 2.0 authorization code grants, also known as three-legged OAuth, is a token-based method for authentication and authorization. This method allows your integration to access Atlassian APIs on a user's behalf. Unlike two-legged OAuth, three-legged OAuth involves the end user in the authorization process by asking them to consent to access to their data.
Authenticated access is provided by an access token that is used to make calls to the API. OAuth 2.0 authorization code grants require an app created in the developer console. This app provides the authentication credentials that are used to get an access token for the desired API.
Authorization for OAuth 2.0 authorization code grants is implemented via scopes. Scopes statically specify the maximum set of actions that an app may perform (see scopes). Note, OAuth 2.0 authorization code-only scopes are different to Connect scopes.
To learn more, read OAuth 2.0 (3LO) for apps.
Basic authentication uses an API token to authenticate the client. The token is generated from a user's Atlassian Account, encoded, then added to the header for requests to the API.
Authorization for basic authentication is based on the permissions of the user you used to generate
the API token. For example, if you are using basic authentication, your user must have the Admin
permission for a space in order to call PUT /wiki/rest/api/space/{spaceKey} (Update space).
We recommend that you don't use basic authentication. It may be easier to implement, but it is much less secure. Consider using OAuth 2.0 authorization code grants (3LO) instead.
To learn more, read Basic auth for REST APIs.
Rate this page: