Apparently there is a Vault Management API that supports retrieving and editing vault items, but the only way to use it is to run the CLI command bw serve.
Although this mechanism works, and has the additional benefit of supporting multiple configurations, it has a really big glaring problem: it’s insecure by default, and it’s difficult to secure. It puts the onus of securing the vault management api endpoints on the customer instead of on Bitwarden.
Bitwarden should:
Create a properly configured, hardened docker image.
Provide much more guidance on the docs on what needs to be done to properly secure any machine running bw serve.
Provide the functionality and docs needed to properly encrypt and decrypt secrets using the public api, without having to go through the server.
More details in this post down below:
The Original Post
I saw a number of posts from the past few years asking for api support for creating, retrieving, and managing items. The most relevant reply was that Bitwarden has to guarantee that the data is encrypted in flight and at rest, which would somehow conflict with adding crud support for items to the api.
The concern is obviously legitimate but is clearly solvable, and not adding native api support has a number of far more serious ramifications.
By not adding such support, you are encouraging businesses to go elsewhere and to use password and secret managers that do provide such support, such as 1Password, Okta, probably all the cloud providers, HashiCorp Vault, and likely countless others.
Another consequence is that programmers have either tried to wrangle with the code in your repositories or reverse engineer some of your clients, with mixed success. Even when programmers succeed, it’s extremely likely that whatever solutions they come up with will be suboptimal from a security perspective and have vulnerabilities that will never be addressed.
On the api documentation site, you write: “For management of Vault items, use the CLI. Access to Vault items relies on Vault decryption, which must be done with a Master Password.” Note that it’s not at all clear from that message that it’s possible to use the cli to log in with an api key, which could lead to all kinds of mistakes like removing 2fa (if that’s even possible) or abandonment in order to support usage on a server.
Putting potential user error aside, that message is also very odd because vault decryption can obviously be done by the “client” using an api. Bitwarden itself does it in all of its clients. All you’d need to provide is solid documentation. And if decryption requires two steps, as it does with the cli, then mimic that behavior in the api. It’s no different than other multi-step api authentication mechanisms.
In summary, Bitwarden stands to lose customers and encourages poor security hygiene by neglecting to add support for managing vault items. I’d even go so far as to say that the api is nearly useless without item management support. It’s very difficult to understand the thinking behind its intentional absence.
By the way, you don’t have a tag here on the forum for “api”.
I just realized what you were likely asking - here is a more detailed answer.
When you execute the bw serve command in the CLI, it will bind to a hostname and port that you choose. The default is localhost on port 8087, and the api endpoints expose objects within whatever vault you have logged in to (could be hosted by Bitwarden.com or a self-hosted instance). So, in your terminal you might do something like this:
When you are finished your workflow, just type fg to bring the bw CLI back to the foreground in your terminal, and press Control-C to end the api session. Then you can logout of your vault with the CLI if you like. Hope that helps!
I appreciate the additional detail. It took some experimentation to figure all that out.
It turns out the problem I was having was that I was adding two slashes after the base url. For example, I was using http://localhost:8087//object/fingerprint/me instead of http://localhost:8087/object/fingerprint/me. That resulted in a Not Found response, which given the circumstances, was a bit confusing.
Following up on my original post, I have to say that although the vault management api is what I was looking for, going through the cli adds complexity that seems unwarranted.
It means having to spin up another machine or container in production (I don’t plan to run this only on my dev machine) and, more importantly, securing it. By going this route, another vector is exposed and there is little to no documentation on how to keep it safe.
I did see someone mention setting up firewall rules, an ip whitelist, and ssl, as well as the addition of the hostname argument, but that just demonstrates the lack of documentation and the level of potential vulnerability.
There are a number of solutions that I think Bitwarden should take to resolve this:
Create a properly configured, hardened docker image.
Provide much more guidance on the docs on what needs to be done to properly secure any machine running bw serve.
Provide the functionality and docs needed to properly encrypt and decrypt secrets using the public api, without having to go through the server.
If you think about it, by using the cli to serve the vault management api, Bitwarden is basically putting the onus of securing the endpoints on the customer. I’m basically going to spin up a server that’s almost guaranteed to be less secure than Bitwarden’s would be.
I got it to work locally and I think there are some serious caveats to this solution. I would say this only partially solves the issues I raised in the feature request.
Fair enough - would you mind editing your request above, then, to make it clear what you are asking for that is not met by the current solution? Thanks.
Just to follow-up, you should probably explain why you claim that the api is insecure by default. By default, it binds to your localhost address, which is only accessible from the same machine you are logged into. From that perspective, it is just as secure as any other Bitwarden client. If you have specific security concerns, you should explain them if you are making the suggestion that they need resolution. Thanks again.
When it runs locally on your own machine and bound to localhost, I’m guessing that it’s probably as secure or nearly as secure as the cli itself.
But in other environments, there are fewer guarantees.
If the machine running bw serve is deployed to a host with a public hostname, anybody accessing its endpoints can basically access everything that the cli has access to. With docker, the localhost binding is irrelevant because it’s proxied anyway.
This is insecure by default. All you have to do is deploy the machine, and run bw login followed by bw serve and your vault is exposed to the world.
To secure it, we have to set up a security envelope with firewall rules, ip whitelists, ssl certificates, and other secure mechanisms. And there are a lot of gotchas that most people aren’t aware of. For example, it’s not enough to have an ssl certificate; you have to actively prevent non-https traffic.
It’s possible that there already some accommodations for these issues, but I couldn’t find any info or documentation anywhere in the forums or in Bitwarden’s docs about them.
Is there any option to connect to self-hosted BW directly via its API without “bw serve”?
If not it’s a missing feature that limits ability to write integrations. Example: