Bitwarden plugin

This DMNO plugin allows you to securely access your secrets stored in Bitwarden Secrets Manager. Please note that this plugin is not compatible with Bitwarden’s Password Manager product. Authentication with Bitwarden uses Machine Account Access Tokens.

Installation & setup

Install the package in the service(s) that will use secrets from Bitwarden.

npm

npm add @dmno/bitwarden-plugin

pnpm

pnpm add @dmno/bitwarden-plugin

Yarn

yarn add @dmno/bitwarden-plugin

Bun

bun add @dmno/bitwarden-plugin

---

After installation, you’ll need to initialize the plugin in your config.mts and add a config item to hold your machine account access token. You can explicitly wire the plugin up to the service account token if using multiple tokens at once, or it will be injected by default based on the BitwardenSecretsManagerTypes.machineAccountAccessToken type. It’s ok if you have not created the machine account or access token - we’ll do that in the next section.

.dmno/config.mts

import { BitwardenSecretsManagerDmnoPlugin, BitwardenSecretsManagerTypes } from '@dmno/bitwarden-plugin';

// by default, access token will be injected using types
const bitwardenPlugin = new BitwardenSecretsManagerDmnoPlugin('bitwarden');

// or you can explicitly wire it up by path
const bitwardenPlugin2 = new BitwardenSecretsManagerDmnoPlugin('bitwarden', {
  accessToken: configPath('..', 'BWS_TOKEN')
});

export default defineDmnoService({
  schema: {
    BWS_TOKEN: {
      extends: BitwardenSecretsManagerTypes.machineAccountAccessToken,
      // NOTE - the type itself is already marked as sensitive 🔐
    },
  },
});

Plugin instance IDs

You must give each plugin instance a unique id so we can refer to it in other services and the dmno CLI.

In this case we used bitwarden, but you can imagine splitting vaults and access, and having multiple plugin instances - for example bitwarden/prod for highly sensitive production secrets and bitwarden/dev for everything else.

Injecting the plugin in monorepo services

In a monorepo, you are likely managing secrets for multiple services. If you will be using the same service account(s) to access those secrets, you can initialize a plugin instance once in your root service as seen above, and then inject it in child services. Note we must use that same id we set during initialization.

apps/some-service/.dmno/config.mts

import { BitwardenSecretsManagerDmnoPlugin } from '@dmno/bitwarden-plugin';

// 💉 inject the already initialized plugin instead of re-initializing it
const bitwardenPlugin = BitwardenSecretsManagerDmnoPlugin.injectInstance('bitwarden');

---

Setup Project & Secrets

If you are already using Bitwarden Secrets Manager, you likely already have existing projects that contain secrets. If so, now would be a good time to review how they are all organized. If not, you should create at least one project, as each secret can have a parent project it belongs to, and access can be granted to projects rather than managing each secret individually.

Use projects to segment access

You should use multiple projects to segment your secrets following the Principle of Least Privilege. This means at minimum, you should have one project for ultra-sensitive production secrets, and another for everything else. How much more you want to break things up is up to you and will depend on your security requirements.

It is technically possible to create secrets without using projects and/or to assign permissions at the individual secret level, but we do not recommend it.

Setup Machine Account & Access Tokens

Machine accounts can be granted access to projects, and each machine account can have multiple access tokens with optional expiration. How you want to manage this is up to you, but a sensible approach could be:

• Production machine account has access to all projects
  • single access token is used at a time
• Staging/CI machine account has access to all projects except ultra-sensitive prod secrets
  • each environment/CI/external tool could have a unique access token
• Dev machine account has access to secrets needed for local dev
  • each developer could have a unique access token

Expiring tokens are more secure, but require the overhead of rolling those tokens, which must be done manually. Not wanting to cause an outage, you may want to roll them manually without the pressure of a potentially forgotten expiry date. To roll without downtime, create a new token, redeploy, and then decommission the previous token.

Machine account access tokens now serve as your secret-zero - which grants access to the rest of your sensitive config stored in Bitwarden. It must be set locally and in deployed environments, but it is sensitive so we must pass in the value as an override rather than storing it within the config. Locally, this usually means storing it in your .env.local file and on a deployed environment you’ll usually set it within some kind of UI, wherever you would normally pass in environment variables.

.dmno/.env.local

BWS_TOKEN=0.abc123...

Note that the config path of BWS_TOKEN is arbitrary and you can see how it was wired up from your config schema to the plugin input in the example above.

---

Add items to your schema

With the plugin initialized and access wired up, now we must update our config schema to connect specific config values to data stored in Bitwarden secrets.

Items are wired up using the secret UUIDs found in the Bitwarden UI. For example:

export default defineDmnoService({
  schema: {
    ITEM_WITH_ID: {
      value: bitwardenPlugin.secretById('abc123-secretuuid-xyz789'),
    },
    // example showing a switchBy and multiple plugin instances
    SWITCHED_ITEM: {
      value: switchBy('MY_ENV_FLAG', {
        _default: 'not-sensitive',
        staging: bitwardenDevSecrets.secretById('0123...'),
        production: bitwardenProdSecrets.secretById('789...'),
      }),
    },
  },
});

Caching

In order to avoid rate limits and keep dev server restarts extremely fast, we heavily cache data fetched from external sources. After updating secrets in Bitwarden, if the item has been cached, you’ll need to clear the cache to see it take effect.

• Use the dmno clear-cache command to clear the cache once
• The dmno resolve and dmno run commands have cache related flags:
  • --skip-cache - skips caching logic altogether
  • --clear-cache - clears the cache once before continuing as normal

Active config iteration

While you are actively working on the config itself, dmno resolve -w --skip-cache will combine watch mode with skipping cache logic.

Once you are satisfied, clear the cache once more and you are good to go.

Self-hosted

In case you are self-hosting Bitwarden Secrets Manager, the BitwardenSecretsManagerDmnoPlugin also takes additional inputs for apiServerUrl and identityServerUrl. The values for this can be found in the Bitwarden UI under Machine Accounts > Config. See the Bitwarden docs for more details.

const bitwardenPlugin = new BitwardenSecretsManagerDmnoPlugin('bitwarden', {
  apiServerUrl: 'https://vault.bitwarden.com/api', // default value
  identityServerUrl: 'https://vault.bitwarden.com/identity', // default value
});