···
# spindle secrets with openbao
This document covers setting up Spindle to use OpenBao for secrets
4
-
management instead of the default SQLite backend.
4
+
management via OpenBao Proxy instead of the default SQLite backend.
8
+
Spindle now uses OpenBao Proxy for secrets management. The proxy handles
9
+
authentication automatically using AppRole credentials, while Spindle
10
+
connects to the local proxy instead of directly to the OpenBao server.
12
+
This approach provides better security, automatic token renewal, and
13
+
simplified application code.
Install OpenBao from nixpkgs:
11
-
nix-env -iA nixpkgs.openbao
20
+
nix shell nixpkgs#openbao # for a local server
14
-
## local development setup
25
+
The setup process can is documented for both local development and production.
27
+
### local development
Start OpenBao in dev mode:
32
+
bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201
22
-
This starts OpenBao on `http://localhost:8200` with a root token. Save
23
-
the root token from the output -- you'll need it.
35
+
This starts OpenBao on `http://localhost:8201` with a root token.
Set up environment for bao CLI:
export BAO_ADDR=http://localhost:8200
29
-
export BAO_TOKEN=hvs.your-root-token-here
41
+
export BAO_TOKEN=root
46
+
You would typically use a systemd service with a configuration file. Refer to
47
+
[@tangled.sh/infra](https://tangled.sh/@tangled.sh/infra) for how this can be
50
+
Then, initialize the bao server:
52
+
bao operator init -key-shares=1 -key-threshold=1
55
+
This will print out an unseal key and a root key. Save them somewhere (like a password manager). Then unseal the vault to begin setting it up:
57
+
bao operator unseal <unseal_key>
60
+
All steps below remain the same across both dev and production setups.
62
+
### configure openbao server
Create the spindle KV mount:
bao secrets enable -path=spindle -version=2 kv
38
-
Set up AppRole authentication:
70
+
Set up AppRole authentication and policy:
Create a policy file `spindle-policy.hcl`:
75
+
# Full access to spindle KV v2 data
44
-
capabilities = ["create", "read", "update", "delete", "list"]
77
+
capabilities = ["create", "read", "update", "delete"]
80
+
# Access to metadata for listing and management
path "spindle/metadata/*" {
48
-
capabilities = ["list", "read", "delete"]
82
+
capabilities = ["list", "read", "delete", "update"]
85
+
# Allow listing at root level
90
+
# Required for connection testing and health checks
91
+
path "auth/token/lookup-self" {
92
+
capabilities = ["read"]
Apply the policy and create an AppRole:
···
bao write auth/approle/role/spindle \
token_policies="spindle-policy" \
105
+
bind_secret_id=true \
107
+
secret_id_num_uses=0
70
-
bao read auth/approle/role/spindle/role-id
71
-
bao write -f auth/approle/role/spindle/secret-id
113
+
# Get role ID (static)
114
+
ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id)
116
+
# Generate secret ID
117
+
SECRET_ID=$(bao write -field=secret_id auth/approle/role/spindle/secret-id)
119
+
echo "Role ID: $ROLE_ID"
120
+
echo "Secret ID: $SECRET_ID"
123
+
### create proxy configuration
125
+
Create the credential files:
128
+
# Create directory for OpenBao files
129
+
mkdir -p /tmp/openbao
132
+
echo "$ROLE_ID" > /tmp/openbao/role-id
133
+
echo "$SECRET_ID" > /tmp/openbao/secret-id
134
+
chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id
137
+
Create a proxy configuration file `/tmp/openbao/proxy.hcl`:
140
+
# OpenBao server connection
142
+
address = "http://localhost:8200"
145
+
# Auto-Auth using AppRole
148
+
mount_path = "auth/approle"
150
+
role_id_file_path = "/tmp/openbao/role-id"
151
+
secret_id_file_path = "/tmp/openbao/secret-id"
155
+
# Optional: write token to file for debugging
158
+
path = "/tmp/openbao/token"
164
+
# Proxy listener for Spindle
166
+
address = "127.0.0.1:8201"
170
+
# Enable API proxy with auto-auth token
172
+
use_auto_auth_token = true
175
+
# Enable response caching
177
+
use_auto_auth_token = true
184
+
### start the proxy
186
+
Start OpenBao Proxy:
189
+
bao proxy -config=/tmp/openbao/proxy.hcl
192
+
The proxy will authenticate with OpenBao and start listening on
195
+
### configure spindle
Set these environment variables for Spindle:
export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
80
-
export SPINDLE_SERVER_SECRETS_OPENBAO_ADDR=http://localhost:8200
81
-
export SPINDLE_SERVER_SECRETS_OPENBAO_ROLE_ID=your-role-id-from-above
82
-
export SPINDLE_SERVER_SECRETS_OPENBAO_SECRET_ID=your-secret-id-from-above
201
+
export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201
export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
88
-
Spindle will now use OpenBao for secrets storage with automatic token
207
+
Spindle will now connect to the local proxy, which handles all
208
+
authentication automatically.
210
+
## production setup for proxy
212
+
For production, you'll want to run the proxy as a service:
214
+
Place your production configuration in `/etc/openbao/proxy.hcl` with
215
+
proper TLS settings for the vault connection.
219
+
Test the proxy directly:
96
-
bao kv list spindle/
222
+
# Check proxy health
223
+
curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health
225
+
# Test token lookup through proxy
226
+
curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self
99
-
Add a test secret via Spindle API, then check it exists:
229
+
Test OpenBao operations through the server:
102
-
bao kv list spindle/repos/
233
+
bao kv list spindle/
105
-
Get a specific secret:
235
+
# Add a test secret via Spindle API, then check it exists
236
+
bao kv list spindle/repos/
238
+
# Get a specific secret
bao kv get spindle/repos/your_repo_path/SECRET_NAME
244
+
- Spindle connects to OpenBao Proxy on localhost (typically port 8200 or 8201)
245
+
- The proxy authenticates with OpenBao using AppRole credentials
246
+
- All Spindle requests go through the proxy, which injects authentication tokens
- Secrets are stored at `spindle/repos/{sanitized_repo_path}/{secret_key}`
114
-
- Each repository gets its own namespace
115
-
- Repository paths like `at://did:plc:alice/myrepo` become
116
-
`at_did_plc_alice_myrepo`
117
-
- The system automatically handles token renewal using AppRole
119
-
- On shutdown, Spindle cleanly stops the token renewal process
248
+
- Repository paths like `did:plc:alice/myrepo` become `did_plc_alice_myrepo`
249
+
- The proxy handles all token renewal automatically
250
+
- Spindle no longer manages tokens or authentication directly
123
-
**403 errors**: Check that your BAO_TOKEN is set and the spindle mount
254
+
**Connection refused**: Check that the OpenBao Proxy is running and
255
+
listening on the configured address.
257
+
**403 errors**: Verify the AppRole credentials are correct and the policy
258
+
has the necessary permissions.
**404 route errors**: The spindle KV mount probably doesn't exist - run
127
-
the mount creation step again
261
+
the mount creation step again.
263
+
**Proxy authentication failures**: Check the proxy logs and verify the
264
+
role-id and secret-id files are readable and contain valid credentials.
266
+
**Secret not found after writing**: This can indicate policy permission
267
+
issues. Verify the policy includes both `spindle/data/*` and
268
+
`spindle/metadata/*` paths with appropriate capabilities.
129
-
**Token expired**: The AppRole system should handle this automatically,
130
-
but you can check token status with `bao token lookup`
273
+
# If running as systemd service
274
+
journalctl -u openbao-proxy -f
276
+
# If running directly, check the console output
279
+
Test AppRole authentication manually:
282
+
bao write auth/approle/login \
283
+
role_id="$(cat /tmp/openbao/role-id)" \
284
+
secret_id="$(cat /tmp/openbao/secret-id)"
anirudh.fi