Security for Connect apps

Atlassian Connect authenticates apps using JWT tokens. At installation time, the Connect app and the host product exchange a security context containing a shared secret used to create and validate JWT tokens for use in API calls.

The use of JWT tokens guarantees that:

• The Atlassian product 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).

Security basics

Here's how to use authentication and authorization in your app:

1. In the app descriptor, declare that the app uses JWT as the authentication mechanism.
2. Implement an installation callback endpoint and add a reference to it in the app descriptor.
3. In the app descriptor, declare any scopes needed by the endpoints your app will access.

When the installation callback is called at app install time, the host product passes in a security context that your app uses to validate incoming requests and sign outgoing requests. If you use the Atlassian frameworks, this is handled for you.

About the app descriptor

Authentication and authorization rely on elements in the app descriptor.

To enable your Atlassian Connect app to authenticate securely with the host Atlassian product, make sure the following elements are in the app descriptor:

• authentication:type: the authentication type (always jwt)
• lifecycle:installed: a callback endpoint to call at installation time

To request authorization to perform specific categories of actions in the host product, add the scopes element and the scopes you need. For a list of available scopes, see Scopes.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "baseUrl": "http://localhost:3000",
    "key": "atlassian-connect-app",
    "authentication": {
        "type": "jwt"
    },
    "lifecycle": {
        "installed": "/app-installed-callback"
    },
    "scopes": [
        "read", "write"
    ],
    "modules": {} // etc
}

Installation data

When the app is installed, the Atlassian product passes your callback a security context that contains important information that you will need to store in your app in order to sign and verify future requests.

For details on the contents of the payload, please see the lifecycle attribute documentation.

Upon successful registration, the installation callback must return either a 200 OK or 204 No Content response code. Otherwise, the operation will fail and the installation will be marked as incomplete.

Making API requests

When communicating server-to-server with the Atlassian host product your app uses a JWT token to access protected resources including most of the REST APIs. When you use the frameworks, this is handled for you.

If you are not using the frameworks, you can use JWT libraries to construct a token. See Creating a JWT token and the Atlassian-supported claims that you need to construct.

Validating incoming requests

Requests to your endpoints from the host product are signed with JWT tokens. If you use the frameworks, this is handled for you.

If you are not using the frameworks, you will have to decode and verify all incoming requests from an Atlassian product to your service. For more details, see Decoding and verifying a JWT and the Atlassian-supported claims that you need to validate.

Signed installation callback requests

When your app is first installed, the shared secret is exchanged for the first time. It is then available to sign callbacks on subsequent installations. The best way to see how JWT tokens work with your lifecycle events is to use the Connect inspector to create a temporary app, install it in your cloud development environment and watch the lifecycle events.