Skip to main content

Bitbucket Server Authentication Provider

info

This documentation is written for the new backend system which is the default since Backstage version 1.24. If you are still on the old backend system, you may want to read its own article instead, and consider migrating!

The Backstage core-plugin-api package comes with a Bitbucket Server authentication provider that can authenticate users using Bitbucket Server. This does NOT work with Bitbucket Cloud.

To add Bitbucket Server authentication, you must create an incoming application link. Follow the steps described in the Bitbucket Server documentation to create one.

Configuration​

The provider configuration can then be added to your app-config.yaml under the root auth configuration:

auth:
  environment: development
  providers:
    bitbucketServer:
      development:
        host: bitbucket.example.org
        clientId: ${AUTH_BITBUCKET_SERVER_CLIENT_ID}
        clientSecret: ${AUTH_BITBUCKET_SERVER_CLIENT_SECRET}

The Bitbucket Server provider is a structure with two configuration keys:

  • clientId: The client ID that was generated by Bitbucket, e.g. b0f868455c15dcdff5c5fb5d173ae684.
  • clientSecret: The client secret tied to the generated client ID.

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 matching spec.profile.email. If no match is found it will throw a NotFoundError.
  • emailLocalPartMatchingUserEntityName: Matches the local part of the email address from the auth provider with the User entity that has a matching name. If no match is found it will throw a NotFoundError.
Note

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:

from your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-bitbucket-server-provider

Then we will need to add this line:

packages/backend/src/index.ts
//...
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(
  import('@backstage/plugin-auth-backend-module-bitbucket-server-provider'),
);
//...

Frontend Configuration​

Sign-in​

To add the provider to the frontend, add the bitbucketServerAuthApiRef reference and SignInPage component as shown in Adding the provider to the sign-in page.

ScmAuth​

For backstage to be able to use the oauth token of the logged in user to access the Bitbucket Server API, you need to add it to list of ScmAuth providers as shown in Custom ScmAuthApi Implementation using the ScmAuth.forBitbucketServer method.