Security for Connect apps

Atlassian Connect is an app framework used to build Atlassian apps. The methods for implementing security (that is, authentication and authorization) are different, depending on whether you are building an Atlassian Connect app or another type of integration. For more information, see Security overview.

Security for a Connect app has two key parts:

• Authentication tells the host product the identity of your app
• Authorization determines what actions it can take within the host product

Connect apps use JWT for authentication and either scopes or user impersonation for authorization.

Authentication

Atlassian Connect apps use JWT (JSON Web Tokens) for authentication. This is already built into the supported Atlassian Connect libraries.

When an app is installed, a security context is exchanged with the application. The security context contains, among other things, a key identifying the app and a shared secret used to create and validate JWT tokens. Your app uses the security context to validate incoming requests and to sign outgoing requests. The use of JWT tokens guarantees that:

• Confluence Cloud can verify it is talking to the app, and vice versa (authenticity)
• None of the query parameters of the HTTP request, nor the path (excluding the context path), nor the HTTP method, were altered in transit (integrity)

To learn more, read Authentication for Connect apps.

Authorization

Atlassian Connect apps can use two types of authorization: 

• Authorization via scopes and app users: This is the default authorization method. You should use this for most cases.
• Authorization with user impersonation: You should only use this method when your app needs to make server-to-server requests on behalf of a user.

Authorization via scopes and app users

This method has two levels of authorization:

• Static authorization via scopes
• Run-time authorization via app users

Scopes are defined in the app descriptor and statically 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.

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, or the app needs to make a server-to-server request using OAuth 2.0 user impersonation (see next section).

Authorization with user impersonation

User impersonation allows your integration to access Confluence 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 our page on User impersonation for Connect apps.