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

Glossary

The words these pages and the Bouncer apps use. The first part has the words you'll meet in the apps. The second part has the terms that matter mostly to the people who run the server or connect scripts to it. Each part is in alphabetical order.

Words in the app

Access duration

How long access lasts after a request is approved. The approver chooses it. It's separate from the time to answer. See Approvals and access duration.

Administrator

The person who runs your organisation's Bouncer server. They add people and requesters, decide which resources exist and who may approve them, make pairing codes, and revoke devices. They use the bouncer-admin tool on the server itself. This isn't the same as having administrator rights on a Windows PC.

APK and sideloading

An APK is an Android app file. Sideloading means installing an APK yourself, instead of from Google Play. Bouncer's Android app has no public Google Play listing, so you sideload it. See Install on Android.

Approval key

A key your device makes when you pair it, and keeps to itself. The app signs each approval and denial with it, so the server can check that the decision came from your paired device and matches the request you saw. How it's protected depends on the device:

  • Android: kept in the phone's Keystore (in its secure hardware), and usable only while the phone is unlocked. If you chose it when pairing, each use also needs your fingerprint.
  • iPhone: kept in the Secure Enclave, and each use needs Face ID or Touch ID.
  • Windows: a Windows Hello passkey, used after your PIN, face or fingerprint. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked (Device keys).

Approval log

Bouncer's own record of what happened: who asked for what, who approved, denied or revoked it, what was issued, and what changed in the config. It's kept in the server's database, never holds a secret value, and an administrator can export it with bouncer-admin log export. The apps show the part that concerns you, under Grants, then History.

Approver

A person allowed to approve or deny requests for a resource. The server's configuration says who the approvers are for each resource.

Device

A phone or PC paired with a Bouncer server. Each device has its own approval key and its own ID. An administrator can list and revoke devices; you can remove your own by signing out.

FCM

Firebase Cloud Messaging, Google's push service. Bouncer uses it to wake Android phones (and, through Apple's push service, iPhones) when a request arrives. Each push carries only a random ID; the app then fetches the details from your organisation's server.

Grant

The access that an approval gives: one requester, one resource, one action, until an end time. Grants are listed under Grants in the app, where you can revoke one early.

Human requester

The requester that belongs to a person. The server makes one for each person in its configuration. Requests you make in the app come from it, and so do requests from the command line once your administrator gives you its key. Scripts, agents and hosts have their own requesters.

Key attestation

Proof from a phone's own hardware about its approval key: where the key is kept, and what the phone needs before the key can be used. An Android phone can give this proof, signed by its hardware and traceable back to Google. When a phone sends it, Bouncer checks it when you pair (unless the administrator has turned the check off), so it doesn't just take the phone's word for it. A server can also be set to require it. Then it won't pair an Android phone that says its key is in hardware unless the proof checks out. iPhones have no server-verified key attestation. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked. Attestations signed with RS1 (RSA with SHA-1) are refused.

OpenBao

OpenBao is an open-source fork of HashiCorp Vault, managed by the Linux Foundation. Bouncer keeps secrets in OpenBao and asks it for short-lived tokens when a request is approved. Bouncer doesn't replace OpenBao, and it doesn't keep secret values in its own database. See openbao.org.

Pairing

Connecting an app to a Bouncer server. Your administrator makes a one-time pairing code; you scan it or paste it into the app. Pairing registers the device and its approval key with the server. See Pair the app with your server.

Pairing string

The pairing code and server address as one line of text, starting bouncer-pair:, for pasting into the app instead of scanning the QR code. Your administrator sees it under "Or copy this pairing string" when they run bouncer-admin device pair, and sends it to you privately.

Personal credential

A credential that a person creates in the app and owns, rather than one the administrator set up in the server's configuration. The owner chooses who it is shared with. Your server needs to be set up for these.

Requester

Whatever asks for access: a person, a script or host, or an AI agent. Each requester has its own requester key, issued by Bouncer. The app shows what kind of requester it is.

Requester key

The secret a requester uses to ask Bouncer for access and to use what's approved. Bouncer issues it; it starts with brk_. Keep it like a password. It lets the holder ask, but never approve.

Resource

Something people can ask for access to, set up by the administrator: a stored secret, a stored API key, or SSH access to a host. The app also calls these credentials.

Revoke

To end access before its end time. Revoking a grant stops Bouncer issuing tokens and revokes the ones already issued. A value that was already read can't be recalled.

Rotate

To change a secret where it's used (a new password, a new API key), so an old copy stops working. Bouncer can't do this for you.

Save request (store request)

A request to save new values into a secret, rather than read it. The app shows it as Save · N fields. Approving allows one save of the named fields. You never see the values.

Self-approval

Approving your own request, or a request from your own agent. Each resource's policy says whether it's allowed. Where it isn't, the app says "Another approver has to approve this", and you can only deny.

Standing access

Access with no end time, also called a standing grant. The app shows it as Always. Your server may offer it: it's in the default list unless your administrator turns it off. Always is experimental and may change or be removed, so choose a time limit instead. See Approvals and access duration.

Standing grant

A grant with no end time. See Standing access.

StrongBox and TEE

The two places an Android phone can keep a key away from the rest of the system. StrongBox is a separate security chip, on phones that have one. The TEE (trusted execution environment) is a protected part of the main processor. Bouncer's Android key uses StrongBox when the phone has it, and the TEE otherwise.

Tailscale

A VPN service. The deployment kit's examples use tailscale serve to put HTTPS in front of the server, but Bouncer doesn't need Tailscale or any other VPN: the apps need a network connection that reaches the server. If your organisation's server is on Tailscale, the Tailscale app has to be connected on your phone or PC first. Whether you need it is up to your organisation.

TestFlight

Apple's service for trying out iPhone apps before they're in the App Store. See iPhone and Mac.

Time to answer

How long a request waits for an approver before it expires. 15 minutes by default. The app shows it as "N left to answer".

Token

A short-lived pass that lets a requester read the one secret it was approved for, under one grant. Tokens are only for reading: a save request gets no token, because the server writes the values itself. OpenBao makes each token when Bouncer asks. Each token lasts a few minutes, and Bouncer hands out new ones until the grant ends. It isn't the same as a device token, which tells the server which of your devices is calling.

TPM

Trusted Platform Module, a security chip in most recent PCs. Windows Hello uses it to protect its keys. A TPM's presence alone is not proof of where a particular key lives. Existing Windows Hello keys remain unattested.

User verification

A check that the person, not just the device, is there for each use of a key: a fingerprint, a face, or a Windows Hello PIN. iPhone and Windows Hello keys need it every time you approve or deny. An Android key needs only an unlocked phone, unless you chose Confirm every signature with biometrics when you paired. See Setting up biometric approvals later.

Windows Hello and passkeys

Windows Hello is how Windows checks that it's you: a PIN, your face or your fingerprint. A passkey is a key that Windows keeps and uses only after a Windows Hello check. When you turn on approvals on a PC, Bouncer makes a passkey named "Bouncer on PC-NAME" and signs approvals with it. See Turn on approvals with Windows Hello.

Server and OpenBao terms

These are mostly for the people who run the Bouncer server or connect scripts and agents to it.

Accessor

A second ID for each OpenBao token. It can be used to look up or cancel the token, but not to read anything with it. Bouncer's records name tokens by their accessor, so its log can be compared with OpenBao's without anyone handling a real token.

AppRole

How a program, rather than a person, logs in to OpenBao. It works like a username and password for the program: the role_id names the program and isn't secret on its own, and the secret_id is the password. Bouncer logs in to OpenBao this way. The role kit sets it up.

Device token

A token the server gives a device when it pairs. The app sends it with each call, so the server knows which paired device is asking. It isn't the approval key: the token only identifies the device, and approvals still have to be signed with the key. Revoking the device makes its token stop working.

Downstream credential

A secret that really belongs to another system, such as a cloud provider's API key, which OpenBao only stores for Bouncer to hand out. Bouncer can stop handing it out, but it can't cancel the key at that other system. An administrator can mark a resource as downstream. Then, if the key was handed out under a grant that has since ended, Bouncer lists it as due to be changed at that other system.

Emergency stop

The role kit's emergency-stop.sh, run with an OpenBao admin token. It cuts Bouncer off from OpenBao without needing the Bouncer server at all: it removes Bouncer's logins, revokes the tokens Bouncer issued and empties the kit's policies. Compare the kill switch, which runs inside Bouncer.

Key labels

The label the server records for each device's approval key when it pairs. In the labels, hw means hardware, sw means software, and uv means user verification (a fingerprint, face or PIN check):

  • platform-hw-unlocked: kept in the phone's secure hardware, and usable while the phone is unlocked. This is a standard Android key.
  • platform-hw-uv: kept in secure hardware, with a fingerprint or face check on every use. This is an Android key paired with Confirm every signature with biometrics, or an iPhone key.
  • platform-sw-uv: a Windows Hello key, with a check on every use. A passing Windows Hello check doesn't prove the key is in hardware.
  • platform-sw-unlocked: a key kept in software. Servers refuse these unless their administrator allows them.

Unless key attestation proves it, a label is what the device said about itself.

Kill switch

bouncer-admin revoke --all, run on the server by an administrator. It ends active grants, cancels pending requests and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm. It does not suspend personal credentials' Always approved mode; use bouncer-admin personal suspend for each namespace as well (Recovery). Compare the emergency stop, which works without Bouncer.

KV version 2

The part of OpenBao that stores plain secrets. Each secret sits at a path and has named fields, for example a password field at apps/billing/db-password. It keeps earlier versions of each secret. Bouncer reads stored secrets from it.

MCP

The Model Context Protocol, which AI agents and their client apps use to call tools. bouncer-mcp lets an agent ask for access through Bouncer.

Migration

A numbered change to the Bouncer server's database that comes with a new version. The server runs any new migrations itself when it starts. If one fails, the server stops instead of starting with the wrong database layout.

Personal-credential namespace

A storage area in OpenBao that an administrator sets aside for personal credentials: a place to keep them, and limits on how long their tokens and access may last. The apps call it a Storage area.

Policy loosening

A change to the server's settings that makes access or pairing easier. When an administrator reloads the config (bouncer-admin config reload), Bouncer looks for these changes: for a resource, longer durations or token lifetimes, new requesters, approvers or secrets, allowing self-approval, approving from a notification or viewing values, and no longer requiring a hardware key; for pairing, allowing software keys or user-verified keys, a weaker Android attestation setting, or a changed Android app identity. For each one it finds, the approval log records exactly what was loosened, and the approvers' devices are told. Anything else isn't announced. For example, turning on Windows Hello keys isn't one of the changes it looks for. A change made while the server was stopped isn't announced: the log only records that the config was loaded. Changes that only make things stricter aren't announced either.

Raft snapshot

A backup of OpenBao's own storage (Raft is the name of that storage). What's in it stays encrypted, so restoring it also needs OpenBao's unseal key, in its Shamir shares, unless the server uses a static seal, in which case it needs that seal's key (see Sealed and unsealed). Keep the shares or the seal key safe, and separate from the snapshots.

Role kit

The scripts in deploy/openbao-role-kit that set up Bouncer's narrow role on an OpenBao: its AppRole login, its policies, and a token role for each resource. An administrator runs it once with an OpenBao admin token, and again when resources change.

Root token

The token with every permission, which OpenBao prints once, when it's first set up. Bouncer never uses it. The kit's instructions encrypt it as soon as it's printed. If it's lost, a new one can be made with the unseal shares.

Sealed and unsealed

OpenBao encrypts everything it stores. When it starts, it's sealed: it can't read its own data until it's given its key, which is called unsealing. While OpenBao is sealed, Bouncer can't issue any tokens, so nobody can read a secret through it.

Shamir shares

Pieces of OpenBao's unseal key. When OpenBao is first set up, the key is split into several shares, and a minimum number of them, the threshold, is needed to unseal it. Bouncer's server kit uses three shares with a threshold of two, so no single person holds the whole key. If OpenBao is moved to a static seal, the shares become recovery keys: they can no longer unseal it, and are only used for a few recovery tasks.

SSH revocation list

For SSH access, Bouncer hands out short-lived certificates, and these can't be revoked from OpenBao. Each configured host's timer attempts to fetch a list every 15 seconds. Its SSH server refuses listed certificates only after a successful installation and when sshd uses the list through RevokedKeys. OpenSSH calls this a KRL (key revocation list). Bouncer can't confirm delivery: a revoke reports unknown with pending: krl_delivery. Existing SSH sessions stay open.

Static seal

An OpenBao option where OpenBao unseals itself after a restart, instead of someone typing in shares. Bouncer's repository has an optional setup that keeps the seal key so that only the machine's TPM can decrypt it at boot. That protects against someone copying the disk, but not against someone with full control of the running machine or its host.

Threshold

How many Shamir shares are needed to unseal OpenBao.

Token role

A rule in OpenBao that says what kind of token may be made for a resource: which policy it gets and how long it may last. The role kit makes one for each resource, and Bouncer can only issue tokens through them.

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