Skip to main content

Bitbucket Server Authentication Provider

info

This documentation is written for the old backend which has been replaced by the new backend system, being the default since Backstage version 1.24. If have migrated to the new backend system, you may want to read its own article instead. Otherwise, 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.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.

Adding the provider to the Backstage frontend​

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

Using Bitbucket Server for sign-in​

In order to use the Bitbucket Server provider for sign-in, you must configure it with a signIn.resolver. See the Sign-In Resolver documentation for more details on how this is done. Note that for the Bitbucket Server provider, you'll want to use bitbucketServer as the provider ID, and providers.bitbucketServer.create for the provider factory.

The @backstage/plugin-auth-backend plugin also comes with a built-in resolver that can be used if desired. The emailMatchingUserEntityProfileEmail identifies users by matching their Bitbucket Server email address to the email address of User entities in the catalog. Note that you must populate your catalog with matching entities or users will not be able to sign in with this resolver.