AuthBox

Documentation embedded in this build.

Give a service a certificate

In short

Give a web server, a test site or an API its own certificate without a person claiming one for it. A project admin creates the identity from the workspace, and the key is born where it is used: on the server through ACME, at the door, or at the courier, which hands it over once and forgets it.

What it is for

Your project has something that is not a person and needs a certificate: a web server, a test site, the API behind one of your missions. Until now getting it one meant asking an operator for an invitation that a person then claimed, which left the key on somebody's laptop and the identity owned by nobody the certificate names.

A project admin creates a service identity from the workspace; AuthBox derives the name, bounds it to the hostnames the project published and mints one enrollment token, issuing no key of its own; the key is then born in one of three places — an ACME client on the server itself, the door that fronts the site, or the courier, which hands it over once and forgets it — and a download of a key AuthBox generated is not offered at all

A project admin creates the identity from the workspace instead. The name is derived from the project's own, so you choose one label; the hostnames it may carry are exactly the ones your project has published, refused by name if you ask for another project's; and it is granted unattended renewal at the moment it is created, so no person is ever in the renewal loop.

What is not offered is a download. A key is born where it is used and never travels: on the server through its own ACME or EST client, on the AuthBox door that fronts the site, or once through the vault's courier for a system that can run neither. There is no fourth way, and no response on this deployment has a field that could carry a key.

The topology

One project, one identity, and three places a key can be born — none of them AuthBox.

   THE PROJECT                     AUTHBOX                    WHERE THE KEY IS BORN
   admin at the workspace   ->   derives the DN        ->  ACME client on the server
   publishes its hostnames       bounds the SANs       ->  the door that fronts the site
   picks a delivery              mints one token       ->  the courier, once, then forgets

                                 issues no key, ever

The project's published hostnames are the ceiling in both directions: an invitation may not ask for a name outside them, and issuance refuses one that does, by name.

Stand it up

The server with its helpers: a front door, a courier for enrollment, a key door for sealed data, a portal for requests and an object store beside one box.DOORAUTHBOXcourierkey doorportalstore
$ docker run --rm authboxus/authbox-eval -evaluate -scenario companions -print docker | sh
$ docker logs writer

The server with its helpers runs the portal beside the box, and the services desk is on a project's page in the portal's workspace. A service identity is bounded by the hostnames its project has published, so the desk offers one once a project of yours has published a hostname; the door that fronts it with the managed credential is the evaluation's own front door. The evaluation runbook says which port each companion answers on.

What the smoke proves

The composition's service phase walks one identity's whole life against real containers: a project admin's audited write creates the service and its invitation, a second authboxproxy starts with the managed credential and that token and fronts the project's hostname, the credential renews, the certificate is revoked from the project's own desk, and the door then refuses. Beside it the same fixture enrolls a service through ACME with a project-minted external account binding, and claims one courier certificate for a service that can run neither.

The rules themselves are pinned in Go, off the compiled packages: a service identity is created only by an admin of its owning project, a SAN outside the project's claim is refused at both the authoring and the issuance moment, renewal re-issues what the presented certificate proves, a door refuses to start when a route names a hostname its credential does not carry, a courier claim for a person is refused, and no response schema in any shipped specification names key material but the courier's single-use claim.

Read on