If you're here, chances are you're already added into the administration group for Bitwarden users. If not, please reach out to an existing administrator first to be added before continuing.

Before continuing, it is strongly advised that you have Nix and Direnv installed. This will allow you to store your Bitwarden secrets much easier.

First, set the BITWARDENCLI_APPDATA_DIR environment variable to prevent the CLI from using or overriding your personal Bitwarden configuration. It is strongly recommended to set this in .envrc so you don't forget:

$ cat .envrc
export BITWARDENCLI_APPDATA_DIR="$HOME/.config/bitwarden-dma-space"
...

Then, you'll need to obtain your Bitwarden API key. For this, follow the Bitwarden official documentation. You may choose to add these as environment variables as well:

$ cat .envrc
export BW_CLIENTID="your-client-id"
export BW_CLIENTSECRET="your-client-secret"

Now, proceed to run bw login --apikey to login using the exported environment variables, then bw unlock to unlock the actual vault. This will prompt you for your master password, so enter that.

Afterwards, you should see an output similar to this:

$ bw unlock
? Master password: [hidden]
Your vault is now unlocked!

To unlock your vault, set your session key to the `BW_SESSION` environment variable. ex:
$ export BW_SESSION="<REDACTED>"
> $env:BW_SESSION="<REDACTED>"

You can also pass the session key to any command with the `--session` option. ex:
$ bw list items --session <REDACTED>

Simply copy-paste the export BW_SESSION=... line into the terminal and run that. You should now be able to run bw sync, bw list, etc.

Head to the Bitwarden web app or extension, then navigate to the Server Credentials/NixOS Machines collection. Here, you will find 1 secret item per machine.

To add a secret to a machine, open the corresponding item, then add a new hidden field with the name being the SOPS path you want to store the secret at relative to /run/secrets.

For example, do add a secret at /run/secrets/authentik/secret_key, you would add a new hidden field with the name authentik/secret_key and the value being the value of the secret.

This step only needs to be done once per machine. To validate that a machine is ready for SOPS, ensure it has the sops.* options in its configuration.nix.

If not, start by referring to sops-nix's step 3 of Usage Examples. Essentially, you need to do the following steps:

1. Grab the machine's age key from its host SSH key using ssh-to-age.
2. Add it to vars.nix under <machine>.sops.hostPubKey.
3. Find the Bitwarden secret ID. There are 2 ways to do this:
   • Using just get-bitwarden-secret-id <machine>, which will match a secret with the exact name given, but this is not guaranteed to be in the correct collection.
   • Using the &itemId=<UUID> value when you click on the secret item in the Bitwarden web app.
4. Add it to vars.nix under <machine>.sops.bitwardenSecretID.

Then, add the boilerplate snippet to the machine's configuration.nix:

{
  sops = {
    defaultSopsFile = ./secrets.bitwarden.yaml;
    age.sshKeyPaths = [ "/etc/ssh/ssh_host_ed25519_key" ];
  };
}

First, make sure that the local Bitwarden vault is up to date by running bw sync.

Then, run just sync-bitwarden-secrets <machine> to synchronize the secrets from Bitwarden to the ./machines/<machine>/secrets.bitwarden.yaml file. The SOPS file will automatically be generated with the host SSH key being the only decrypting recipient.

Having more than just the host's recipient key is not recommended. Instead, prefer regenerating the secret file from source Bitwarden if needed. This way, the secrets are always up to date with Bitwarden.

You may use the secrets in your machine like any other sops-nix secrets. For example:

sops.secrets."authentik/secret_key" = {
  owner = "authentik";
};

This will place the secret at /run/secrets/authentik/secret_key with the owner being the authentik user.

Deploy the machine using just deploy <machine> to push the updated secrets to the machine.