Rate this page:
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:
Here's how to use authentication and authorization in your app:
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.
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 timeTo 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
}
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.
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.
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.
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.
Use case | Shared secret used to sign |
---|---|
First install | None; no JWT token. Because there was no previous shared secret the recipient cannot validate
a JWT token. This means that you should anticipate that there will be no Authorization header present. |
Second and subsequent installs | The shared secret sent in the preceding installed callback. |
Uninstall, enable & disable | The shared secret sent in the preceding installed callback. |
First install after being uninstalled | The shared secret sent in the preceding installed callback. This allows apps to allow the new installation to access previous tenant data (if any exists).A valid signature demonstrates that the sender is in possession of the shared secret from when the old tenant data was accessed. |
Rate this page: