Documenting Secrets

Just writing secrets in plain text into my documentation is bad, especially since I intend to just publish it on the internet.

On the other hand, homelab documentation often benefits from being able to include secrets: Server addresses, passwords and access tokens are closely interlinked with workflows such as updating packages that this kind of documentation describes.

To solve this conflict, I’m not including secrets in my documentation directly. I save those in my Bitwarden password safe instead. Bitwarden supports direct links to items, so that’s already much better than simply referencing the item by name. However, these direct links only open the web interface, which I don’t typically use. This can be improved a bit more.

In Linux, it’s possible to register custom mime types via .desktop files. If this is paired with a command line client for Bitwarden, we can click on a link in the homelab documentation with a custom mime type, e.g. bw-item://, and have a script look up the referenced item in password safe using the command line client. Subsequently, the password is copied to clipboard. With a bit more boilerplate, the whole workflow means just clicking a link plus sometimes entering the master password and the secret is copied right to the clipboard. I’m happy with that!

I’m planning to implement this in my NixOS configuration, so it’s automatically available in all my Linux desktops.