Getting Started with OpenBao/Vault
In this tutorial, you'll learn how to get started with OpenBao and Vault.
You'll walk through how to:
- Initialize the service
- Unseal the service and log in
- Enable a basic key-value secrets engine
- Write and read secrets from the store
By the end, you'll have a working instance and a basic understanding of how to operate OpenBao/Vault.
💡 To dive deeper into the concepts covered in this tutorial, check out the References section.
Preparations
First, choose whether you want to use OpenBao or Vault. The included playground has both pre-installed.
Enter one of the following values:
openbaovault
Good to know
This tutorial uses an in-memory storage backend for simplicity.
The relevant configuration is located at:
/etc/openbao/config.d/storage.hcl
💡 Stick with the provided storage configuration for this tutorial. You can explore other available options in this playground.
Initializing the service
Initialization prepares the service's storage backend to receive data.
During this process, the service generates a root key (or master key) and an internal encryption key.
The encryption key is used to encrypt all data written to the storage backend. It's stored in the same backend, alongside the encrypted data.
Because the encryption key itself is persisted, it's encrypted with the root key before being written to storage.
The root key, on the other hand, is never stored. Since it protects the encryption key, keeping it secure is critical.
By default, the service uses Shamir's Secret Sharing to split the root key into multiple shards, called key shares or unseal keys. A configurable number of these shards (called threshold) must be provided to reconstruct the root key and gain access to the data.
To initialize the service, use the following command:
bao operator init -key-shares=1 -key-threshold=1
⚠️ In production, using -key-shares=1 -key-threshold=1 is not recommended, as it creates a single unseal key with no redundancy. This configuration is used here for simplicity.
Make sure to save both the unseal key and the root token.
Unsealing
When the service starts, it begins in a sealed state. At this point, it can access the physical storage but cannot decrypt any data.
In order to gain access to the data, the service needs to be unsealed.
Unsealing is the process of retrieving the root key, decrypting the encryption key, and loading it into memory to enable access to the data.
There are two types of unsealing mechanisms:
- automatic
- manual (default)
With automatic unsealing, the service relies on an external system (such as a KMS or HSM) to encrypt the root key during initialization and store it alongside the data. When the service starts, it contacts the external system to decrypt the root key and complete the unseal process automatically.
Automatic unsealing
With manual unsealing, the root key is never stored on disk. Instead, it is protected by unseal keys, which are distributed among multiple trusted individuals or systems. When enough unseal keys are provided, the root can be reconstructed and the service can be unsealed.
Manual unsealing
Until the service is unsealed, most operations (like authentication, reading secrets, or writing policies) are unavailable. Only basic actions (like checking the seal status or performing unseal operations) are allowed.
Once unsealed, the encryption key is kept in memory and used to access the data. The service remains unsealed until it's sealed manually or restarted.
💡 Sealing the service manually can also act as a protective measure (for example, during a security incident or operational emergency) to instantly revoke access to secrets without shutting down the system.
To proceed, unseal the service using an unseal key received during initialization:
bao operator unseal
Logging in
The login command authenticates a user or machine to the service using the provided credentials.
On success, the command returns a token, similar to a session token on a website.
By default, this token is cached locally for future requests in ~/.vault-token .
💡 OpenBao also supports reading tokens from ~/.bao-token.
You can log in to the service using the root token received during initialization:
bao login
🎉 Congratulations!
You've successfully set up OpenBao/Vault.
Now let's see what you can do with it. Start by checking its status:
bao status
The output should look something like this:
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 2.2.1
Build Date 2025-04-22T20:36:25Z
Storage Type inmem
Cluster Name vault-cluster-3405cc1a
Cluster ID 593a2d0f-5c16-8ba2-e721-17748ae523a0
HA Enabled false
Breakdown of the most important details
| Key | Expected value | Explanation |
|---|---|---|
Initialized | true | The service was initialized earlier. |
Sealed | false | The service was unsealed earlier. |
Storage Type | inmem | Data is stored in-memory. |
Seal Type | shamir | Shamir's Secret Sharing is used to split the root key into multiple shards. |
Total Shares | 1 | Amount of unseal keys the root key is split into. |
Threshold | 1 | Amount of unseal keys required to recover the root key. |
Enable the KV secrets engine:
bao secrets enable -version=2 -path=secret kv
Write a secret to the store:
bao kv put -mount=secret my-secret foo=bar
Summary
🎉 Congratulations!
You've learned the core concepts needed to run OpenBao/Vault and should now be able to spin up new instances on your own.
💡 Other tutorials based on this playground often include a /opt/playground/setup.sh script to help you reach this stage more quickly.
What's next?
There's still plenty more to explore:
- See the References section below to dive deeper into the topics covered
- Check out additional tutorials and challenges to expand your knowledge
If you want to test your knowledge or experiment further, check out these playgrounds:
References
💡 To dive deeper into the concepts covered in this tutorial, check out the resources below.
Level up your Server Side game — Join 10,500 engineers who receive insightful learning materials straight to their inbox