Using BITBUCKET_STEP_OIDC_TOKEN for Bitbucket API Authentication

[Sjoerd de Vries]

Hello Bitbucket Community,

I'm currently automating some of our workflows using Bitbucket Pipelines and faced an issue when trying to authenticate API requests to Bitbucket's REST API. I attempted to use `BITBUCKET_STEP_OIDC_TOKEN` for this purpose, specifically to post comments on pull requests. Here's the curl command I used:

```sh
curl --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/${BITBUCKET_WORKSPACE}/${BITBUCKET_REPO_SLUG}/pullrequests/${BITBUCKET_PR_ID}/comments' \
--header 'Authorization: Bearer ${BITBUCKET_STEP_OIDC_TOKEN}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{ "content": { "raw": "what" } }'
```

However, this approach doesn't seem to work, and I suspect the `BITBUCKET_STEP_OIDC_TOKEN` might not be valid for this type of API request. I would appreciate any guidance on the following:

1. Is `BITBUCKET_STEP_OIDC_TOKEN` intended for use with Bitbucket's own API?
2. What is the recommended method for posting PR comments from a pipeline?

Any advice or examples would be greatly appreciated.

Thank you in advance for your help!

[Theodora Boudale · Accepted solution]

Hi Sjoerd,

OIDC is used if you want to connect to external resource servers, such as AWS, GCP, or Vault. In these cases, if you set up OIDC, the $BITBUCKET_STEP_OIDC_TOKEN will allow you to access these resource servers. It cannot be used for authentication with Bitbucket Cloud API calls.

You can see the available ways of authenticating with API calls here:

• https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication

You could create for example a Repository Access token with Pull requests permissions. You can store it in a secured variable (from Repository settings > PIPELINES Repository variables) and then use it in the API call.

You can find more info on Repository Access tokens here:

• https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/

Please feel free to reach out if you have any questions!

Kind regards,
Theodora

[reuben.j]

The documentation linked doesn't really answer the question. If you create access tokens in Bitbucket, how do you then use these in a pipeline? 

For example, if I create a Workspace token and set that as a secured Workspace variable, do I have to do something in the pipeline config to refer to these, are they just inherited in the runners environment, or something else? 

Thanks in advance

[Theodora Boudale]

Hi @reuben.j,

You will need to reference the workspace variable (that holds the value of the workspace access token) in the command you use with our API.

For example, if you use a curl command with our API in your bitbucket-pipelines.yml file, and you have created a workspace variable with the name Workspace_Access_Token (where you stored the value of the access token), the curl command will look like this:

curl --request GET --url 'https://api.bitbucket.org/2.0/repositories/some-workspace/some-repo' --header "Authorization:Bearer $Workspace_Access_Token" --header 'Accept:application/json'

Kind regards,
Theodora

[reuben.j]

Hi Theodora, 

I shouldn't really have added to this question as my clarification question was specifically about usage within a bitbucket pipeline, so the answer lacked the clarification within the context of a yaml bitbucket pipeline definition. 

Which is more generally a question of string parsing in yaml: 
Ie. is it $WORKSPACE_TOKEN, or ${WORKSPACE_TOKEN}, or `WORKSPACE_TOKEN`, or \$WORKSPACE_TOKEN 

I was specifically up against an error where the token DID work in a direct API request but the same token DID NOT work in a pipeline. I have since figured out the right string escaping to make it work through trial & error. 

It would good to have more examples of using variables within bitbucket pipeline yaml and what needs escaping and what doesn't when it comes to yaml strings/multi-line strings etc. 

Many thanks!

[Theodora Boudale]

Hi @reuben.j,

Thank you for the feedback and it's good to hear that you figured it out!

Variables can be referenced as $WORKSPACE_TOKEN in Pipelines, except when using self-hosted Windows Runners; then they need to be referenced as $env:WORKSPACE_TOKEN.

I am not sure what escaping you needed to do; if you can share the call you are using (sanitizing any private/sensitive info first), I will share the feedback with our documentation team.

Kind regards,
Theodora