dma.space wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# Setting up Bitwarden and SOPS for a NixOS Machine

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][nix] and [Direnv][direnv] installed**. This will allow you to store your Bitwarden secrets much easier.

#### Preparing the Bitwarden CLI

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:

```sh
$ 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](https://bitwarden.com/help/cli/#using-an-api-key). You may choose to add these as environment variables as well:

```sh
$ 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.

#### Adding a Secret

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.

#### Onboard the Machine to SOPS

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](https://github.com/Mic92/sops-nix?tab=readme-ov-file#usage-example). 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`:

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

#### Synchronizing Secrets

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.

#### Using the Secrets

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

```nix
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.

[nix]: https://nixos.org/download.html
[direnv]: https://direnv.net/
[sops-nix]: https://github.com/Mic92/sops-nix