Skip to content

OpenBao CLI Setup

This guide explains how to install the OpenBao CLI and authenticate to our secrets management system.

Prerequisites

  • Access to the Skatzi Keycloak realm
  • Member of an appropriate Keycloak group (e.g., mgmt-k8s-admins)

Install the CLI

macOS (Homebrew)

# Install OpenBao CLI
brew install openbao

# Or use the HashiCorp Vault CLI (compatible with OpenBao)
brew install vault

Linux

# Download the latest release
curl -fsSL https://github.com/openbao/openbao/releases/download/v2.1.0/bao_2.1.0_linux_amd64.tar.gz -o bao.tar.gz

# Extract
tar -xzf bao.tar.gz

# Move to PATH
sudo mv bao /usr/local/bin/

# Verify installation
bao version

Windows

Download the latest release from OpenBao Releases and add it to your PATH.

Configure Environment

Set the OpenBao server address:

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
export BAO_ADDR="https://openbao.prod.skatzi.com"

# Or if using the vault CLI
export VAULT_ADDR="https://openbao.prod.skatzi.com"

Reload your shell or source the profile:

source ~/.zshrc  # or ~/.bashrc

Authenticate with OIDC

Login using your Keycloak credentials:

# Login with OIDC (opens browser for Keycloak authentication)
bao login -method=oidc role=default

This will:

  1. Open your default browser
  2. Redirect you to Keycloak login
  3. After authentication, redirect back to the CLI
  4. Store the token locally for future commands

Available Roles

Role Description Access
default Basic user access Read-only to assigned paths
admin Full administrative access All paths and operations
mgmt-cluster-admin Management cluster admin Full access to clusters/hetzner-mgmt/*

Example Login

# Standard user login
bao login -method=oidc role=default

# Admin login (requires admin group membership)
bao login -method=oidc role=admin

Verify Authentication

After logging in, verify your access:

# Check token information
bao token lookup

# List available secrets engines
bao secrets list

Token Management

Check Token Status

bao token lookup

Renew Token

bao token renew

Revoke Token (Logout)

bao token revoke -self

Troubleshooting

"permission denied" Error

You may not have access to the requested path. Check:

  • Your Keycloak group membership
  • The role you logged in with
  • The policy attached to your role/group

"OIDC callback" Error

Ensure:

  • You're connected to the internet
  • Keycloak is accessible at https://keycloak.prod.skatzi.com
  • Your browser can open the callback URL

Token Expired

Simply re-authenticate:

bao login -method=oidc role=default

Next Steps