Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.

On this page

Resources and policy

A resource is one thing Bouncer guards: usually a secret in OpenBao, sometimes SSH access to one host. Each resource in the config file says what it is, who may ask for it, who approves, and for how long access can last. This page explains those settings in Bouncer 0.5.7.

The basic resource

resources:
  - id: prod-db-password
    name: Production database password
    kind: stored_secret
    description: The billing service's PostgreSQL password.
    folder: Databases/Production
    kv:
      - mount: kv
        path: apps/billing/db-password
    fields: [password]
    approvers: [alice]
    requesters: [alice, build-agent]
SettingMeaning
idThe resource's ID: lower-case letters, digits and single hyphens, up to 40 characters. Requesters use it (bouncer exec prod-db-password). It must match the role kit's resources file. IDs starting with pc- are reserved
name, descriptionWhat people see in the apps and in bouncer resources
folderWhere the apps' library files it, as folder names joined by /. Leave it out for "Unfiled". Changing it doesn't affect any grant
kindstored_secret, stored_api_key or ssh_host. The first two behave the same way; the kind is a label for people. ssh_host is different (see SSH hosts)
credential_typeOptional. What the value is (api_key, password, access_token, certificate, certificate_with_private_key, ssh_private_key, secret_key, key_pair, recovery_codes, otp_seed or other), so the apps can show a matching icon. It's a label only, not policy
kvThe OpenBao KV version 2 secrets behind it: one or more mount and path pairs
fieldsOptional. The field names in the secret, shown to requesters so they know what to ask for. Names only, never values
approversThe people (by their id in people) who may approve requests for it
requestersWho may ask for it: a list of requester names, or ["*"] for any active requester. Leaving it out also means any active requester

A requester that isn't allowed to ask for a resource doesn't see it in its list, and a request for it is refused as if the resource didn't exist.

How long access lasts

Each resource takes the defaults and can override any of them:

  - id: prod-db-password
    # ...
    request_wait: 10m          # how long a request waits for a decision: 1m to 24h
    credential_ttl: 2m         # how long each OpenBao token lasts: 30s to 1h
    durations:
      presets: [15m, 1h]       # the quick choices on the approval screen
      min: 5m                  # the allowed range for a custom duration
      max: 4h
      always: false            # whether a standing grant may be approved

Two different times matter here, and it helps to keep them apart:

  • The grant's duration is how long the approval lasts. The requester asks for one, and the approver can approve it, shorten it, or (after a confirmation) lengthen it within the range above.
  • The token lifetime (credential_ttl) is how long each OpenBao token lasts. A requester fetches a fresh token each time it uses the grant. A token never outlives its grant.

The approver's choices are checked by the server. A duration outside the range, or a preset you disabled, is refused, never quietly shortened. Presets above max are shown disabled, with the reason.

The limit lives only in this file. The apps show it ("Up to 15 minutes for this credential. Your Bouncer administrator sets this in the server's settings."), but no app screen can change it. The CLI asks for the first enabled preset when no --for is given, so keep a short one first.

To change one resource's limit, follow docs/operations/approval-durations.md in the repository. It covers editing only that resource's lines, committing and reloading, the policy_loosened entry, why requests that were waiting must be asked again, checking the result with bouncer resources --json, and rolling back.

If the role kit's resources file gives a resource a shorter max-ttl-seconds, keep credential_ttl within it. OpenBao enforces the kit's cap.

Add a resource

On 0.5.6 and earlier, add the resource to the role kit's resources file and run ./setup.sh, add it to the config file, then restart the server (Keeping the two lists in step).

From 0.5.7, add a stored secret or API key resource in this order:

  1. Add its line to the role kit's resources file, then run the kit upgrade and permission checks.
  2. Make a copy of the config file with the new resource in it, and run the new server's configuration check on that copy. Once the kit is upgraded, it must exit 0.
  3. Install the checked config. The resource takes its durations from defaults unless you set its own; you don't need a shorter maximum because it's new.
  4. Restart the server. The server learns a new token role's name only when it starts, so a reload isn't enough. Then try a request with fake data, and use the result, before you rely on the resource.

If a resource's OpenBao token role or policy is missing or wrong, the server refuses only that resource, with HTTP 503 resource_not_provisioned and Retry-After: 5. Other resources keep working. Fix the kit entry, then apply and verify the kit; the server checks again by itself. A sealed or unreachable OpenBao, or one that refuses the server's login, is still an outage of the whole server, not a problem with one resource.

This check covers requesters' requests, issuing their tokens, and saves requesters make under those grants. Saves, views and replacements made from the apps use the server's own OpenBao policy and have their own checks. SSH hosts and personal credentials keep their existing checks. This was checked against the source for 0.5.7; the whole sequence hasn't been run end to end.

Who may approve

    self_approval: true            # may people approve their own requests?
    notification_approval: true    # may they approve from the notification?
    require_hardware_uv: false     # must approvals come from a hardware biometric key?
    require_hardware_key: false    # must they come from a hardware key checked each time? (from 0.5.7+34)
  • self_approval (default true). When it's true, a person may approve requests from their own human requester and from agents or hosts they own. The apps label these "Self-approval" and "Your own agent". When it's false, those requests need another approver. Denying is always allowed. See Separation of duties.
  • notification_approval (default true). Allows approving straight from a notification, without opening the app. Each device must also opt in, and only the requested duration can be approved that way. Only the Android app offers it.
  • require_hardware_uv (default false). When true, only a phone key that asks for a biometric check on every signature (platform-hw-uv) can approve this resource. Windows Hello keys and older phone keys can still deny. See Device keys and user verification.
  • require_hardware_key (default false). Introduced in 0.5.7; earlier servers refuse a config that sets it. In the current source (not yet released), it accepts verified Android-key evidence plus biometric verification, or verified TPM evidence plus a WebAuthn UV assertion. An unverified platform-hw-uv claim and a hardware-unlocked key both fail. The server's evidence must belong to this key and epoch. No real PC has yet passed the TPM verifier; physical acceptance remains separate.
    • require_hardware_uv keeps its existing enrolled-label and biometric-statement rule. It still accepts declared claims until an operator opts in to verified evidence. Setting both flags requires both; a TPM key verified with a PIN cannot meet the biometric flag.
    • Denying is independent of these resource flags. The explicit server-wide pairing.require_verified_approval_keys opt-in also applies whenever a key signs. Device keys describes recovery and the default, which activates no policy.
    • Turning either requirement off is logged as a loosening, including dropping verified evidence while UV remains. Replacing the biometric requirement with hardware-key policy also removes the biometric requirement and is reported.

Saving new values: allow_write

    allow_write: true

Off by default. With it, a requester can ask to save new values into the secret (for example after rotating an API key) with bouncer put or the MCP request_store tool. The request names the fields, never the values; the values are sent only after approval, once. A resource with allow_write must list exactly one kv entry, and the role kit's resources line for that secret needs the word write.

With allow_write and self_approval both on, an approver can also save values from their own paired app.

Viewing the value in the app: view

    view: grant_holder     # off (the default), grant_holder or approver
  • off: nobody sees the value in the apps.
  • grant_holder: a person whose own human requester holds an active read grant for the resource can view it on a paired device. An agent's grant never counts.
  • approver: the resource's approvers can view it, grant or not.

Every view is signed by the device's approval key and logged as secret_viewed. It accepts a hardware-backed phone key or a Windows Hello key, including an Android key that needs only the phone unlocked. A view uses the check the key was set up with, so an unlocked-phone key asks for nothing more. If every view must check the person, also set require_hardware_uv: true on the resource. Turning it on counts as a loosening and is announced. It needs exactly one kv entry, and the word view on that line of the role kit's resources file.

Credentials from other systems: downstream

    downstream:
      system: Example cloud API
      kind: static_token
      expires_at: "2027-06-30T00:00:00Z"

Use this when the secret is a token issued by another system (a cloud API key, a Proxmox API token). Bouncer can revoke its own OpenBao tokens but not the copied value at that system. With this block, Bouncer tracks when the value has been released and the grant has ended, and bouncer-admin downstream list shows ROTATE yes. You rotate it at the system, update the secret in OpenBao, then record it:

docker compose exec bouncer bouncer-admin downstream rotated example-api-key

Bouncer trusts your word here: it doesn't contact the other system. See Copied secrets and revocation limits.

SSH hosts

  - id: web1-deploy
    name: Web server 1
    kind: ssh_host
    description: "SSH to web1.example.com"
    ssh:
      principal: deploy           # the one account on the host; never root
    approvers: [alice]
    requesters: [build-agent]
    credential_ttl: 5m

An ssh_host resource has no kv entry. Instead of a stored key, each use gets a fresh OpenSSH certificate for one account, signed by OpenBao, lasting at most credential_ttl. It needs the SSH signer's own login in openbao.ssh and the SSH role kit (deploy/openbao-role-kit/ssh/), and each host must fetch Bouncer's revocation list (deploy/ssh-krl/). Requesters connect with bouncer ssh (Use the CLI).

This page's SSH example was not run. A separate fake-data test exercised SSH issuance, host trust, KRL delivery and retirement in a disposable systemd container (SSH revocation). It establishes no real-host or production acceptance.

Personal credentials

personal_credentials lets people create their own credentials from the apps, in a storage area you define (a KV mount and a path prefix), and share them with other people or groups. Each area has ceilings for the token lifetime and durations. It's off unless you add the section. The full set of options is in the config file reference.

Keeping the two lists in step

Every resource with kv entries must also be in the role kit's resources file, with the same ID and paths. On 0.5.6 and earlier, a wrong role ID can stop start-up. From 0.5.7, a missing or wrong role or policy refuses only that resource with 503 resource_not_provisioned. If only the KV paths differ, issuing a token can succeed but OpenBao refuses its secret read with "permission denied". Change both files together, run ./setup.sh for the kit, then restart Bouncer for a new resource.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).