Bitbucket Authentication Provider
The Backstage core-plugin-api
package comes with a Bitbucket authentication
provider that can authenticate users using Bitbucket Cloud. This does NOT
work with Bitbucket Server.
Create an OAuth Consumer in Bitbucket
To add Bitbucket Cloud authentication, you must create an OAuth Consumer.
Go to https://bitbucket.org/<your-project-name>/workspace/settings/api
.
Click Add Consumer.
Settings for local development:
- Application name: Backstage (or your custom app name)
- Callback URL:
http://localhost:7007/api/auth/bitbucket
- Other are optional
- (IMPORTANT) Permissions: Account - Read, Workspace membership - Read
Configuration
The provider configuration can then be added to your app-config.yaml
under the
root auth
configuration:
auth:
environment: development
providers:
bitbucket:
development:
clientId: ${AUTH_BITBUCKET_CLIENT_ID}
clientSecret: ${AUTH_BITBUCKET_CLIENT_SECRET}
signIn:
resolvers:
# See https://backstage.io/docs/auth/bitbucket/provider#resolvers for more resolvers
- resolver: userIdMatchingUserEntityAnnotation
The Bitbucket provider is a structure with two configuration keys:
clientId
: The Key that you generated in Bitbucket, e.g.b59241722e3c3b4816e2
clientSecret
: The Secret tied to the generated Key.
Resolvers
This provider includes several resolvers out of the box that you can use:
emailMatchingUserEntityProfileEmail
: Matches the email address from the auth provider with the User entity that has a matchingspec.profile.email
. If no match is found it will throw aNotFoundError
.emailLocalPartMatchingUserEntityName
: Matches the local part of the email address from the auth provider with the User entity that has a matchingname
. If no match is found it will throw aNotFoundError
.userIdMatchingUserEntityAnnotation
: Matches theuserId
from the auth provider with the User entity that has a matchingbitbucket.org/user-id
annotation. If no match is found it will throw aNotFoundError
.usernameMatchingUserEntityAnnotation
: Matches theusername
from the auth provider with the User entity that has a matchingbitbucket.org/username
annotation. If no match is found it will throw aNotFoundError
.
The resolvers will be tried in order, but will only be skipped if they throw a NotFoundError
.
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the Building Custom Resolvers section of the Sign-in Identities and Resolvers documentation.
Backend Installation
To add the provider to the backend we will first need to install the package by running this command:
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-bitbucket-provider
Then we will need to add this line:
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-bitbucket-provider'));
Adding the provider to the Backstage frontend
To add the provider to the frontend, add the bitbucketAuthApi
reference and
SignInPage
component as shown in
Adding the provider to the sign-in page.