This documentation describes AuthBox v0.3.0-133-g71cb5564.

1. Run it

AuthBox arrives as container images. The quickest look needs docker and nothing else — no checkout, no Go, no build.

One command: the evaluation

$ docker run -d --name writer -p 8443:8443 -p 8080:8080 -p 8081:8081 authboxus/authbox-eval -evaluate
$ docker logs writer

Open /dev/credentials/ on port 8080, import one, and open the console on port 8443 at /ui. -evaluate performs the first boot on answers built into the image: a certificate authority minted fresh into the container's own /data volume, the console on port 8443 at /ui, the public pages on port 8080 with the site at /site/, health on port 8081. The evaluation image also mints four people under that authority — an administrator, an operator, a reader and a service — and serves them as PKCS#12 files under one password the log prints once (docker logs writer 2>&1 | grep -A 2 'the evaluation persons' reads it back; a container recreated on the same volume prints nothing). There is nothing to prepare — no chown, no token, no wizard — and nothing is fetched from anywhere.

The released image, with an invitation to claim:

$ docker run -d --name writer -p 8443:8443 -p 8080:8080 -p 8081:8081 authboxus/authbox -evaluate

It prints a bootstrap administrator invitation once instead of any key. Claim it one of the two ways the log prints (the enrollment page's link, or three lines that run authboxclient from authboxus/authbox-tools) and the certificate you get opens the console.

Six scenarios to choose from

The image prints the rest: the whole recipe for a scenario — its network, its named volume and every container, with the teardown — as shell lines, or the same as a compose file. Every container but the writer runs its own image with -evaluate and waits for the file the writer writes for it — or, for a second organization, performs its own first boot beside it — so the lines work in any order. Six scenarios, each named once below as the word you type after -scenario:

One server, by itself. A console, a certificate authority, and four people to log in as, with the live publisher on so a front door can be added later. Type -scenario box.

A front door in front of it. Requests pass a door that decides and signs a receipt before anything is reached; the console answers through it on port 8444. Type -scenario door.

A second server that keeps answering. A read-only copy on port 8445 that decides from the first's signed bundle, even with the first stopped. Type -scenario fleet.

The server with its helpers. The door, a courier for enrollment, a key door for sealed data, a portal for requests, and an object store. Type -scenario companions.

Two organizations that trust each other. Each with its own certificate authority; one adopts the other's authority, so a person the second issued is decided at the first. Type -scenario federation.

A card from another authority. A stand-in smart card signs in from an authority this box never ran, and is recorded on the spot. Type -scenario card.

The card you already carry. Bring a real CAC or PIV card: the box trusts the DoD PKI's and the U.S. Treasury PKI's own certificates, fetches their revocation lists, and records you on the spot. Needs the network. Type -scenario cac.

Two ways to start one, here the front door: the recipe piped to a shell, or the same recipe as a compose file.

$ docker run --rm authboxus/authbox-eval -evaluate -scenario door -print docker | sh
$ docker run --rm authboxus/authbox-eval -evaluate -scenario door -print compose > docker-compose.yml
$ docker compose up -d

The evaluation runbook says what each one stands up, which ports it publishes, what to open and how it ends; every other page of this documentation names the scenario that shows what it describes and leaves the details there.

To read the site and this documentation with nothing else running — offline included — serve it from the same image: docker run --rm -p 8000:8000 authboxus/authbox -website, then open port 8000 of the machine docker runs on, over plain HTTP.

One image, no checkout: a deployment of your own

$ docker pull authboxus/authbox
$ mkdir -p data && sudo chown 65532:65532 data
$ docker run --rm -it -v "$PWD/data:/data" -p 127.0.0.1:8090:8090 \
      authboxus/authbox -setup -config /data/authbox.yaml \
      -setup-listen 0.0.0.0:8090 -setup-token generate

That is the first boot wizard, on http://127.0.0.1:8090 behind the one-time token it prints. If your browser is on another machine, publish the port to every interface instead — -p 8090:8090 in place of -p 127.0.0.1:8090:8090 — and open http://<that host>:8090. The token is what guards it, and it travels over plain HTTP, so on a network you do not own tunnel instead: ssh -L 8090:127.0.0.1:8090 <that host> and keep the loopback form. Its first page is a grid of switches: turn on what the deployment is for, and each later page asks only about those, with what each choice needs printed on its box. On the environment step, press In a container: /data, so the configuration and everything the box keeps land in the one directory you mounted. It then writes one configuration file into data/, prints a bootstrap administrator invitation once, and starts the box on the file. From then on the box runs as authboxus/authbox -config /data/authbox.yaml, with -v "$PWD/data:/data" and ports 8443, 8080 and 8081 published; claim the invitation for a certificate and the console is at https://<the host>:8443/ui. The last page in this series says where the answers it asks for are written down.

The command-line tools are published beside it as authboxus/authbox-tools, whose entry point is authboxctl.

What comes up

The rest of this series runs on the evaluation: the box from the first command above and, from step 3, the front door in front of it.

• The console, on port 8443 at /ui. It wants a certificate, and the four files under /dev/credentials/ are the fastest way to see it as somebody in particular.
• The public pages, on port 8080, which want none: the enrollment page a person with an invitation opens, the site at /site/ and this documentation.
• Health, on port 8081 at /livez and /readyz.
• Four people, each issued by this volume's own certificate authority and recorded in its issuance ledger: eval-admin holds every console desk, eval-operator the home, the directory and the status pages, eval-reader the home alone, and eval-service no desk at all, because it is a machine.

Every certificate in that list was minted a minute ago by an authority that exists only in the container's own volume.

Where to look

Two things are worth doing before you move on. Import eval-admin.p12, open the console and click through a person's record. Then import eval-reader.p12, ask for the directory, and, back as the administrator, find that refusal on the audit page. The reason a request was refused is in that record and never in the response — a refusal that explains itself is a way of asking questions about other people's standing.

When you are finished

$ docker rm -f -v writer

That removes the container and its volume, and the certificate authority with them, so a certificate you imported into a browser stops working the next time you run the first command. That is deliberate. A scenario started from its printed recipe ends with the teardown the recipe prints as its last lines.

Next: Enroll your first person