Getting Started

OpenBao is an open source secrets manager (a Linux Foundation project) with a Vault-compatible API. It stores and controls access to secrets such as API keys, passwords and certificates. Available as an open web service in Eyevinn Open Source Cloud, it runs as a single node with Raft integrated storage on a persistent volume, so no external database is needed. The instance initializes itself on first start, so there is no manual init step.

Prerequisites

  • If you have not already done so, sign up for an Eyevinn OSC account
  • openssl and curl on your machine
  • A password manager to store the unseal key and the admin password

Step 1: Generate an unseal key and choose an admin password

The instance auto-unseals with a static key. Generate 32 random bytes as 64 hex characters:

openssl rand -hex 32

Also pick a strong password for the initial admin user. Save both values in your password manager. Without this exact unseal key the stored data cannot be decrypted.

Step 2: Store the values as secrets

Navigate to the OpenBao service and go to the "Service Secrets" tab. Click "New Secret" and create:

  • baounseal: the unseal key from Step 1
  • baoadmin: the admin password

Step 3: Create the OpenBao instance

Create an instance of the OpenBao service and fill in:

Field Required Description
Name Yes Instance name, alphanumeric only
UnsealKey Yes {{secrets.baounseal}}
AdminPassword Yes {{secrets.baoadmin}}

Click on the instance card when the status is green and "running". A 5 GB persistent volume is mounted at /data. Wait a couple of minutes before using the API (see Limitations).

Step 4: What happens on first start

On the first start with empty storage OpenBao initializes itself and:

  • enables the userpass auth method
  • creates a superuser policy with full access, including sudo
  • creates the user admin with the password from AdminPassword
  • mounts KV v2 at secret/

No root token and no recovery keys are produced or shown anywhere.

Step 5: Sign in to the UI

  1. Open the instance URL and sign in to OSC (the UI is behind the OSC sign-in).
  2. On the OpenBao sign-in page, change Method to Username.
  3. Enter user admin and your admin password. Copy the whole password, a common mistake is pasting only part of it.

Step 6: Create a backup admin

After your first sign-in, create a second user with the superuser policy (or configure another auth method) and store its credentials separately. If the admin password is lost and there is no second admin, the data cannot be recovered.

Changing the AdminPassword option later does not change the password. Change it inside OpenBao as admin.

Usage Example

Check health (returns 200 when OpenBao is initialized and unsealed):

curl -s -o /dev/null -w "%{http_code}\n" https://<your-instance-url>/v1/sys/health

Log in as admin and get a client token (auth.client_token in the response):

curl -s -X POST https://<your-instance-url>/v1/auth/userpass/login/admin \
  -d '{"password":"<admin-password>"}'

Write and read a secret:

curl -s -X POST https://<your-instance-url>/v1/secret/data/hello \
  -H "X-Vault-Token: <client-token>" \
  -d '{"data":{"hello":"osc"}}'

curl -s https://<your-instance-url>/v1/secret/data/hello \
  -H "X-Vault-Token: <client-token>"

Configuration

Setting Required Description
UnsealKey Yes (sensitive) 32 bytes as 64 hex characters. Generate with openssl rand -hex 32.
AdminPassword Yes (sensitive) Password of the initial admin user. Read only during the one-time self-initialization; changing it later or restarting with a different value keeps the original password.

The listener is plain HTTP on $PORT (default 8080) with TLS terminated by OSC. Storage is Raft on the volume at /data (5 GB). The UI is enabled.

Limitations

  • Save the unseal key and the admin password. Losing the unseal key, the volume, or all admin credentials means losing access to the data. Starting with a wrong key on existing data leaves the server sealed with "message authentication failed". There is no root token or recovery key; if the admin password is lost and there is no second admin, the only remedy is deleting the instance.
  • Only some paths are public. Reachable from the internet and protected by OpenBao's own auth: /v1/sys/health, the KV API under /v1/secret/, and the login and token API under /v1/auth/. The UI at /ui, the rest of sys/, other mounts such as /v1/transit/ or /v1/pki/, and namespaces stay behind the OSC sign-in. An application outside OSC therefore cannot reach other secrets engines or sys/ endpoints. Token self-renewal under auth/token/ works.
  • Wait a couple of minutes after creation. For the first minute or two, requests under /v1/ may be answered by the OSC gate (401, 302 or a failed connection). This fails closed; nothing is exposed.
  • Single node only, no high availability. No backup is configured; upstream has Raft snapshots, but they are not set up.
  • Anyone with the unseal key and the volume can read the data. Upstream warns that static-key unseal is weaker than a KMS. Use the admin user for administration and create policies and scoped tokens for applications.
  • Rotating the unseal key needs upstream's seal-migration procedure (not tested).
  • Not tested: OIDC or other auth methods, PKI or dynamic secrets, namespaces, upgrades, backups and Raft snapshots, key rotation, high availability, the bao CLI against the instance, a second admin user, large datasets.

Resources