Summary

Confluence Data Center and Server provide APIs that allow external services to access resources on behalf of a user using the OAuth 2.0 protocol. OAuth 2.0 was introduced in Confluence version 7.17 and onwards.

Environment

7.17 onwards

Before you begin

To register your application in Confluence, create an incoming link in the application links section. During the registration process, you can enable proper scopes to limit the range of resources that the application can access. Once you've created the link, you'll receive the OAuth credentials: Client ID and Client Secret. Make sure to keep these credentials secure. For more information, please refer to the documentation., see Configure an incoming link

Create an incoming link using application links

To create an incoming link:

1. Go to  > General Configuration > Application links.

2. Select Create link.

3. Select External application, and then choose Incoming or Outgoing as the direction.

4. Fill in the details as described in the sections below.

Provide application details

In this type of link, you only need to provide the Redirect URL (also known as Callback URL) from your external application. After authorizing the application, the user will be redirected to this URL with the authorization code.

Note: Here https://oauth.pstmn.io/v1/callback is the Postman CallbackURL which is used for testing purposes only. 

Provide application permissions

Select permissions the application can have on your instance. You can choose the following permission scopes:

• Read

• Write

• Admin

• System admin

Note that even if you grant higher permissions, the application won’t be able to do more than the user authorizing it. For more info on what each of these scopes do, see OAuth 2.0 scopes for incoming links.

Copy OAuth credentials to the application

After providing the Redirect URL and selecting the scopes, Confluence will generate the OAuth credentials that include these details. You need to copy the credentials to your external application to complete the link.

At this point, the application link has already been created in Confluence. You can view its details in Application links, including the OAuth credentials in case you needed to access them later.

View OAuth credentials for an existing link

If you lose your OAuth credentials, you can access them any time in the details of the application link you created.

To view OAuth credentials:

1. Go to  > General Configuration > Application links.
2. Find the application link you’re interested in, and select More actions > View credentials.

Authorization code with Proof Key for Code Exchange (PKCE)

This flow lets you securely perform the OAuth exchange of client credentials for access tokens on public clients.

Here are the parameters you’ll use in this flow:

Steps

Method 1: Generating authorization and access token using Postman

1. 1. As per the initial steps, the incoming link with an external application is already created and already generates the Client ID & Client Secret.
   2. Copy both Client ID & Client Secret and save them somewhere as these 2 values will be used for generating the access token. 
   3. After that, Open a new request in Postman and open the Authorization tab.
   4. Here select the type as Oauth 2.0 and configure the new token.
   5. Here provide the following values:
      • Token Name -> Anything
      • Grant Type -> select "Authorization Code"
      • Callback URL -> Use the Callback URL whatever you have. For testing we used https://oauth.pstmn.io/v1/callback"
      • Authorize using browser: Uncheck this open
      • Auth URL -> https://<Base URL>/rest/oauth2/latest/authorize
      • Access Token URL -> https://<Base URL>/rest/oauth2/latest/token
      • Client ID -> Client ID generated during the Incoming app link Configuration
      • Client Secret -> Client Secret generated during the Incoming app link Configuration
      • Scope -> Whatever Scope you want to define
      • State -> Any unique Value
      • Client Authentication -> Select "Send Client credential in the body"
   6. Last click on the "Get New Access Token". This will open the application login page, where you need to provide the credential:
   7. After authenticating the user, the application will open the consent page, where you need to allow the request:
   8. After this Postman, will use the authorization code and generate the access token and you will get the following screen with detail:

                i. Using this access Token, Confluence REST API can be used on a user’s behalf with the OAuth 2.0 protocol.