Authentication Through Bitbucket Cloud

Overview

One of the login options for dex uses the Bitbucket OAuth2 flow to identify the end user through their Bitbucket account.

When a client redeems a refresh token through dex, dex will re-query Bitbucket to update user information in the ID Token. To do this, dex stores a readonly Bitbucket access token in its backing datastore. Users that reject dex’s access through Bitbucket will also revoke all dex clients which authenticated them through Bitbucket.

Configuration

Register a new OAuth consumer with Bitbucketensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

There are several permissions required for an OAuth consumer to use it with Dex:

  • Account: Read - required for extracting base information (email, username)
  • Workspace membership: Read - only necessary to get user’s teams

The following is an example of a configuration for examples/config-dev.yaml:

  1. connectors:
  2. - type: bitbucket-cloud
  3.   # Required field for connector id.
  4.   id: bitbucket-cloud
  5.   # Required field for connector name.
  6.   name: Bitbucket Cloud
  7.   config:
  8.     # Credentials can be string literals or pulled from the environment.
  9.     clientID: $BITBUCKET_CLIENT_ID
  10.     clientSecret: $BITBUCKET_CLIENT_SECRET
  11.     redirectURI: http://127.0.0.1:5556/dex/callback
  12.     # Optional teams whitelist, communicated through the "groups" scope.
  13.     # If `teams` is omitted, all of the user's Bitbucket teams are returned when the groups scope is present.
  14.     # If `teams` is provided, this acts as a whitelist - only the user's Bitbucket teams that are in the configured `teams` below will go into the groups claim.  Conversely, if the user is not in any of the configured `teams`, the user will not be authenticated.
  15.     teams:
  16.     - my-team
  17.     # Optional parameter to include team groups.
  18.     # If enabled, the groups claim of dex id_token will looks like this:
  19.     # ["my_team", "my_team/administrators", "my_team/members"]
  20.     includeTeamGroups: true