verdaccio-bitbucket-auth

Verdaccio authentication plugin for Bitbucket Cloud users.

It validates npm login --auth-type=legacy credentials against Bitbucket Cloud by using the developer email or username plus a Bitbucket API token. It is intended for self-hosted Verdaccio registries that want Bitbucket Cloud workspace membership as the login source.

What it does

• Authenticates Verdaccio users against Bitbucket Cloud REST API.
• Checks membership in one or more configured Bitbucket workspaces.
• Adds Verdaccio groups from Bitbucket workspace membership.
• Supports local-part login normalization with configured email domains.
• Keeps package publish denied by default unless publishWorkspaces is configured.

What it does not do

• It does not implement an OAuth2 browser authorization-code flow.
• It does not support Bitbucket Data Center or Bitbucket Server in v1.
• It does not create or store local Verdaccio users.
• It does not store Bitbucket API tokens in clear text.

Requirements

• Verdaccio with classic auth plugin support. See Verdaccio authentication plugin docs
• Node.js 18 or newer.
• Bitbucket Cloud API tokens for developers. See Bitbucket API token permissions

Each developer token needs at least:

• user data read permission
• workspace read permission

Install

Install the plugin in the same Node.js environment where Verdaccio runs:

npm install -g verdaccio-bitbucket-auth

If testing from a checkout:

npm pack
npm install -g ./verdaccio-bitbucket-auth-0.1.0.tgz

Configure Verdaccio

Configure the plugin in Verdaccio's config.yaml, under the top-level auth section.

Minimal configuration:

auth:
  bitbucket-auth:
    workspaces:
      - my-workspace
    emailDomains:
      - my-company.com

Complete plugin configuration with all optional settings shown:

auth:
  bitbucket-auth:
    workspaces:
      - my-workspace
      - platform-team
    publishWorkspaces:
      - platform-team
    emailDomains:
      - my-company.com
    requestTimeoutMs: 10000
    cacheTtlMs: 300000
    maxCacheEntries: 1000
    maxUsernameLength: 320
    maxTokenLength: 8192
    maxResponseBytes: 1048576
    logUsernames: false

Then use the generated workspace groups in Verdaccio packages rules:

packages:
  '@my-company/*':
    access: workspace:my-workspace workspace:platform-team
    publish: workspace:platform-team
    proxy: npmjs

Alternatively, if every authenticated Bitbucket workspace user may access and publish packages, use Verdaccio's built-in $authenticated group:

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

With $authenticated, Verdaccio only checks that this plugin authenticated the user successfully. With workspace:<workspace-slug> groups, Verdaccio also checks the specific Bitbucket workspace group returned by the plugin. Bitbucket workspace permission values are also exposed as workspace:<workspace-slug>:<permission>, for example workspace:platform-team:owner, when Bitbucket returns them.

Full config.yaml fragment:

auth:
  bitbucket-auth:
    workspaces:
      - my-workspace
      - platform-team
    publishWorkspaces:
      - platform-team
    emailDomains:
      - my-company.com

packages:
  '@my-company/*':
    access: workspace:my-workspace workspace:platform-team
    publish: workspace:platform-team
    proxy: npmjs

workspaces is required. A user must belong to at least one configured workspace.

publishWorkspaces is optional. If omitted, allow_publish returns false. This keeps publish locked down unless explicitly enabled. It is a plugin-level gate; keep Verdaccio packages rules narrow as well.

emailDomains is optional. If configured, a login username without @ is expanded to each configured domain in order. Example: jane becomes jane@my-company.com. Supports multiple company domains.

All numeric options are optional. If omitted, the plugin uses the safe defaults shown in the configuration reference.

Login

Developers log in with legacy npm auth:

npm login --auth-type=legacy --registry https://registry.example.internal/

Prompt values:

• username: Atlassian account email, or local part if emailDomains is configured.
• password: Bitbucket Cloud API token.
• email: ignored by the plugin; use the Atlassian account email if npm asks.

Then verify:

npm whoami --registry https://registry.example.internal/

Why --auth-type=legacy

This plugin implements Verdaccio's classic username/password authentication hook. Modern npm clients may default to a browser-based web login flow, but this plugin expects the CLI to send the username and password fields to Verdaccio. --auth-type=legacy forces that prompt-based flow.

Generated groups

On successful authentication the plugin returns these Verdaccio groups:

• bitbucket
• workspace:<workspace-slug>
• workspace:<workspace-slug>:<permission>
• bitbucket-account:<account-id> when Bitbucket returns it
• bitbucket-user:<nickname> when Bitbucket returns it

Use workspace groups in Verdaccio packages rules.

Configuration

Option	Required	Default	Description
workspaces	yes	none	Bitbucket Cloud workspace slugs allowed to authenticate.
publishWorkspaces	no	none	Workspace slugs allowed by allow_publish. Empty means publish denied.
emailDomains	no	none	Domains used to expand usernames without @.
apiBaseUrl	no	https://api.bitbucket.org	Bitbucket Cloud API base URL. Must use HTTPS.
requestTimeoutMs	no	10000	Bitbucket API request timeout.
cacheTtlMs	no	300000	In-memory successful-auth cache TTL.
maxCacheEntries	no	1000	Maximum successful-auth cache entries kept in memory.
maxUsernameLength	no	320	Maximum accepted npm login username length.
maxTokenLength	no	8192	Maximum accepted Bitbucket API token length.
maxResponseBytes	no	1048576	Maximum Bitbucket response size parsed as JSON.
logUsernames	no	false	Log full usernames. By default usernames are masked in plugin logs.

Security notes

• apiBaseUrl must use HTTPS.
• Password/API token values are never logged.
• Usernames are masked in logs by default. Set logUsernames: true only if your log policy allows full usernames or emails.
• Auth cache keys are SHA-256 hashes of username and token.
• Username and token lengths are bounded before outbound requests are built.
• Auth cache size is bounded.
• Bitbucket API response bodies are size-limited before JSON parsing.
• Bitbucket response bodies are not attached to logged errors.
• Publish is denied unless publishWorkspaces is configured.
• Do not commit .npmrc files or npm tokens.

Troubleshooting

npm login opens a browser or fails before asking username/password:

Use legacy auth:

npm login --auth-type=legacy --registry https://registry.example.internal/

Login fails with valid Bitbucket token:

• Confirm the token has user data read and workspace read permissions.
• Confirm the workspace slug matches Bitbucket Cloud exactly.
• If emailDomains is configured, confirm the user email domain is allowed.
• Confirm Verdaccio can reach https://api.bitbucket.org.

Publish fails after login:

• Add the user's workspace slug to publishWorkspaces.
• Confirm the Verdaccio packages rule allows the generated workspace group.

Development

npm test
npm run pack:check

Before publishing:

npm view verdaccio-bitbucket-auth
npm publish

References

• Verdaccio plugins
• Verdaccio authentication plugin API
• Bitbucket Cloud REST API users
• Bitbucket Cloud workspace permissions