AuthBox documentation — Scenarios

Documentation embedded in this build.

Give a service a certificate

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 enrolment 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

$ make all-in-one    # the reference stack, with the demo project's service fixture

The stack brings up the authority, the portal workspace and the doors. The worked organisation it seeds carries a project that has published a hostname of its own, and the services desk is on that project's page in the workspace.

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 enrols 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