Security for Connect apps

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

The use of JWT tokens guarantees that:

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

Authorization

Atlassian Connect apps can use two types of authorization when interacting with the Atlassian host product APIs:

• Authorization via scopes and app users: Scopes are permissions that are defined in the app descriptor. The app has its own app user with permissions controlled by the admin. The set of allowed actions is the intersection of the scopes and the permissions of the app user. This is the normal authorization method, which you should use unless you need to make server-to-server requests on behalf of a user.
• Authorization with user impersonation: User impersonation allows your integration to access Atlassian APIs on a user's behalf. You should only use this method when your app needs to make server-to-server requests on behalf of a user.

See the Connect app authorization guide for how your app should perform user authorization checks against the permission model defined in Atlassian products.

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 Atlassian host 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 Atlassian host product, add the scopes element and the scopes you need. For a list of available scopes, see Scopes.

For example:

1
2
{
    "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 host 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, 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 Atlassian host product are signed with JWT tokens. If you use the frameworks, verifying the JWT is handled for you.

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

Once a request has been authenticated, your app should perform additional authorization checks to determine if the user is permitted to perform the requested action. For more details, see the Connect app authorization guide.

Validating installation lifecycle requests

An installation secret will be exchanged every time your app is installed or updated. To secure this key exchange process, the install and uninstall lifecycle events include JWT tokens in the Authorization header. This JWT token will be signed with a private key using the RS256(RSA-SHA256) algorithm.

To retrieve the publicKey, make a request to the CDN with the kid parameter supplied in the JWT token header. For example, https://connect-install-keys.atlassian.com/kid

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.

About the installation secret

When storing the app installation secret, allow up to 400 bytes of storage space per secret. Because the secret is used for authentication between your app and Atlassian, it is required that you keep it secure and safe. Ensure the following:

• As few people as possible have access to the secret
• The secret is encrypted at rest
• Only send the secret over an encrypted connection (eg. HTTPS over TLS)

In case of the installation secret being out of sync

There are various of reasons that the installation secret can be desynchronized. In such a case, consider going with the following viable options upon your requirements: