Skip to main content

0023 - Identifying Integrated Clients

ID:ADR-0023
Status:ACCEPTED
Published:2024-10-22

Context and Problem Statement​

Traffic on the Bitwarden platform continues to grow. As that load increases on our systems it becomes imperative to understand how and when our various clients are connecting to our API and other server-side components. Not all traffic is currently well-formed and certain key pieces of information such as accurate device type signatures and user agents as well as client versions are missing or invalid. To best support client-server interactivity there is a desire to not only inform deprecated or obsolete integrations that there could be issues, but to protect those server-side components from integrations that could do outright harm to the platform or client data.

Beyond the immediate observability needs, there is a significant portion of the community that uses alternative (not developed by Bitwarden) clients to access vault data and perform operations. These integration methods are perfectly acceptable but are largely unknown, with many not necessarily being offered as independent applications but custom integrations for proprietary purposes. Bitwarden would like to register these integrations somehow to better understand platform usage and utilize common sense constraints to keep the overall platform more resilient and prepare for traffic shape changes. Furthermore, a number of Bitwarden-developed integrations are largely external such as our Splunk and Sentinel apps that should also be registered.

Considered Options​

  • Maintain current integration method - Make no changes to validation or registration of traffic and expect self-regulation of integrations.
  • Support only Bitwarden integrations - Utilize application signature checks and other security features to only allow Bitwarden-developed clients to connect to server-side components, therefore constraining traffic to known entities.
  • Validate baseline expectations - Inspect and eventually enforce several checks on traffic so that all integrations provide a minimum amount of information on their state so that the platform can be better monitored.
  • Register integrations along with validation - Develop a simple registration method for integrations so that they are enumerated and known to Bitwarden, whether internally or externally developed. Associate validation with registered integrations for enhanced developer feedback.

Decision Outcome​

Chosen option: Register integrations along with validation.

While this is more effort for Bitwarden to develop than just adding validation, combining efforts to expect more from integrations' request data with also providing a registration identifier is a simple addition.

Positive Consequences​

  • Integrations are registered and known to the platform for sensible traffic identification.
  • Bitwarden's operations group receives data to aid in maintainability of the platform, especially to keep things running well for users while keeping out bad actors.
  • Feedback to Bitwarden support teams on version usage is available.
  • Bitwarden's support policy of a certain number of major versions can be more actively enforced.

Negative Consequences​

  • Integrations will need to make the effort to register with Bitwarden and adjust their requests, potentially with brief disruptions for them.
  • Very small latency may be added for the additional validations.

Plan​

Documentation will be provided on the Help Center or this contributing docs site indicating the minimally-required request headers for all clients to provide when communicating to the Bitwarden platform. Release notes will include mention of this and the future enforcement after a set number of major releases. Documentation will also be expanded to offer guidance on how unofficial clients should form their provided client version to accurately represent supported "windows" of client-server interactivity (or a mapping to the latest Bitwarden server release they have certified or tested their integration against) as well as an appropriate device type.

Operations teams will perform the necessary development to validate that required headers are present and enable its enforcement after that time; requests will be rejected as a 400 Bad Request when required headers are missing and a 403 Forbidden when provided headers or their values are not supported.

A process will be established for integrations to submit support tickets requesting a client identifier. Customer Success will work with operations teams to register integrations and deliver the needed information. Existing Bitwarden integrations will be issued their own client identifiers, and this will also be used as an opportunity to establish contact and build a stronger relationship with external entities and the community. Client details will be provided in requests to the Bitwarden platform, with the goal being the identification of conformance per client to the technical needs of the Bitwarden server infrastructure; attestation and the guarantee that a client is who they say they are will be considered as a future effort. Subsequent enhancements may occur beyond the client identifier wherein API keys and authentication token scopes will further refine permissions of an integration.

Self-hosted instances will not perform any checks for client identifiers or required request data.