Supported OAuth 2.0 flows

We support the following OAuth 2.0 flows:

• Authorization code with Proof Key for Code Exchange (PKCE)

• Authorization code

We don’t support Implicit Grant and Resource Owner Password Credentials flows, as they will be deprecated in the next version of the OAuth specification.

For more information on how these flows work, see OAuth RFC. This should help you understand the flows and choose the right one for you.

Security recommendations

Here are some recommendations on how to improve security:

Preventing CSRF attacks

To protect redirect-based flows, the OAuth specification recommends the use of “One-time use CSRF tokens carried in the state parameter, which are securely bound to the user agent” using the state query parameter, with each request to the /rest/oauth2/latest/authorize endpoint. This can prevent CSRF attacks.

Using HTTPS in production

For production environments, use HTTPS for the redirect_uri parameter. This is important as OAuth 2.0 bases its security on the transport layer. For more info, see the OAuth 2.0 RFC and the OAuth 2.0 Threat Model RFC.

For the same reason, we also enforce HTTPS for the base URL of production environments. You can use insecure URIs and base URLs for staging or development environments by enabling the relevant system properties.

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. The following steps and parameters describe our implementation of this flow.

Parameters

Here are parameters you’ll use in this flow:

Before you begin

• Register your application in Bamboo by creating an incoming. During registration, you can enable proper scopes to limit the range of resources that the application can access. After creating the link, you should receive the OAuth Client ID and Client secret — make sure to keep these secure. For more info, see Configuring an incoming link.

• Before starting the flow, generate state (optional), code_verifier, code_challenge, and code_challenge_method.

Steps

1. Request authorization code by redirecting the user to the /rest/oauth2/latest/authorize page with the following query parameters:

   curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

   This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope. The user is then redirected to the URL specified in redirect_uri. The redirect includes the authorization code. For example:

   https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE

   

2. With the authorization code returned from the previous request, you can request an access_token, with any HTTP client. The following example uses curl:
   

   curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER

   Example response:

   {
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
    "created_at": 1607635748
   }

3. To retrieve a new access_token, use the refresh_token parameter.
   

   Refresh tokens may be used even after the access_token itself expires.

   curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI

   This request:

   • invalidates the existing access_token and refresh_token

   • sends new tokens in the response

   Example response:
   

   {
     "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
     "token_type": "bearer",
     "expires_in": 7200,
     "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
     "created_at": 1628711391
   }

   You can now make requests to the API with the returned access token. For more info, see Accessing the Bamboo API with the access token.

Authorization code

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

Parameters

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

Before you begin

• Register your application in Bamboo by creating an incoming. During registration, you can enable proper scopes to limit the range of resources that the application can access. After creating the link, you should receive the OAuth Client ID and Client secret — make sure to keep these secure. For more info, see Configuring an incoming link.

• If you want to use the optional state parameter, generate it before starting the flow.

Steps

1. Request the authorization code by redirecting the user to the /oauth/authorize page with the following query parameters:

   curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE

   This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope. The user is then redirected to the URL specified in redirect_uri. The redirect includes the authorization code, like in the following example:

   https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE

   

2. With the authorization code (response_type) returned from the previous request, you can request an access_token, with any HTTP client. The following example uses Ruby’s rest-client:

   curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI

   Example response:

   {
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
    "created_at": 1607635748
   }

3. To retrieve a new access_token, use the refresh_token parameter.

   Refresh tokens may be used even after the access_token itself expires.

   curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI

   This request:

   • Invalidates the existing access_token and refresh_token.

   • Sends new tokens in the response.

   Example response:
   

   {
     "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
     "token_type": "bearer",
     "expires_in": 7200,
     "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
     "created_at": 1628711391
   }

   You can now make requests to the API with the returned access token. For more info, see Accessing the Bamboo API with the access token.

Accessing the Bamboo API with the access token

To access the Bamboo API with the previously returned access token, put the token in the Authorization header. For example:

curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com:8085/bamboo/rest/api/latest/plan/{projectKey}-{buildKey}"

Scopes

The scope parameter is required in both flows. It allows you to specify the permission scopes your application can request from the authorizing user. Note that regardless of which scopes you choose, the actual permissions will always be capped at what the user can actually do.

Here you can find the scope keys you can use in your requests, as values of the scope parameter: