Bitbucket Authorization Provider

Bitbucket OAuth Consumers

Register a Workspace

The first step is create or have a Bitbucket Workspace, go to Bitbucket Home to create a Workspace. A workspace is a centralized area where your team or personal account manages repositories and settings.

Create an OAuth Consumer

Once a workspace is created, register an OAuth 2.0 consumer at OAuth Consumers Settings https://bitbucket.org/{workspace-name}/workspace/settings/api to grant access to Bitbucket resources like Account (User by Aura Auth), Projects, Repositories, Workspaces, etc. For more detailed information read Bitbucket Cloud REST APIs Intro and Get current user.

To generate an OAuth consumer the workspaces settings includes:

• Name: The application name shown when the user tries to grant access to the app.
• Description: An optional description of what the consumer does
• Callback URL: The URL to which Bitbucket OAuth will redirect, it should end in /auth/callback/bitbucket for local and production environments.
  • Local environment: http://localhost:3000/auth/callback/bitbucket.
  • Production environment: Set the URL of your production application.
• URL: Optional URL where users can learn more about your application.
• Permissions: Select scopes based on your application's needs. Aura Auth typically uses:
  • account
  • email

Full scopes reference Bitbucket OAuth 2.0 Scopes and for more information about how to create an OAuth 2.0 Consumer on Bitbucket read Use OAuth on Bitbucket Cloud and Guides OAuth 2.0.

Bitbucket Aura Auth

Installation

Install the package using a package manager like npm, pnpm or yarn.

npm install @aura-stack/auth

Environment setup

Now, it's time to create and consume the Bitbucket credentials required and used by Aura Auth, which include the client Id and client Secret and write them into a .env file.

Additionally set the secret used by Aura Auth to sign and encrypt the user's session.

# Bitbucket Credentials
AURA_AUTH_BITBUCKET_CLIENT_ID="bitbucket_client_id"
AURA_AUTH_BITBUCKET_CLIENT_SECRET="bitbucket_client_secret"

# Aura Secret
AURA_AUTH_SECRET="32-bytes-secret"

Configure the provider

Set the oauth option of the createAuth instance and writing "bitbucket" name.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: ["bitbucket"],
})

export const { handlers } = auth

Get HTTP Handlers

Use the HTTP handlers to consume the authentication logic and flow the Aura Auth library to be integrated into routers and frameworks.

import { handlers } from "@/auth"

export const { GET, POST } = handlers