AuthBox

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

Bring the organization you already have

In short

For an organization that already runs a directory, a PKI and a mail relay. AuthBox adopts the people and groups it reads and never owns them, trusts the certificates your own authority issues rather than issuing any, and stops counting a directory that goes quiet rather than going stale.

What it is for

An organization already has a directory, a public key infrastructure and a mail relay. AuthBox reads the directory — people and the groups they are in — and turns what it finds into attributes it adopts and never owns; every record keeps its origin, and if the directory goes quiet the copy stops counting rather than going stale. The organization's own authority issues the certificates; AuthBox issues none and only trusts.

Three sources on the left — a directory of people and groups, a PKI with its root and CRL, and a mail relay — send arrows into a central AuthBox marked adopts, never owns; from there, arrows carrying small envelope marks fan out to two edge proxies, each deciding locally, and one of the proxies stands in front of a service
Or keep your authority's signature

Or, if what you want is this enrollment ceremony and your own authority's signature, have both: AuthBox runs the invitation, the approval and the profile, forwards the approved request to your authority to sign, checks the certificate that comes back against the very key and subject it approved, refuses any difference, and records which authority signed it. The forwarding speaks EST, or ACME with external account binding, so your authority needs nothing new from you; what it never decides is who may ask, which stays this deployment's own ceremony.

Mail goes through the organization's relay. A fleet of proxies at the edges decides from the adopted data, so a person's standing in the directory opens a door at a service that knows nothing about the directory. Nothing is re-entered, nothing is migrated, and AuthBox writes only its own audit trail and receipts.

This is not a migration. The directory stays the directory; AuthBox holds a budgeted copy of what it says.

The topology

Three systems you already run feed one AuthBox that adopts and never owns; from there, signed material fans out to doors that decide locally.

   YOUR DIRECTORY  --+
   people, groups    |
                     |      +----------------+
   YOUR AUTHORITY  --+--->  |   AUTHBOX      |  --+--> DOOR --> a service
   root and its CRL  |      | adopts,        |    |            (knows nothing
                     |      | never owns     |    |             of the directory)
   YOUR MAIL RELAY --+      +----------------+    +--> DOOR

Each arrow leaving AuthBox carries signed material with the origin still on it. Each door decides where it stands.

Stand it up

$ docker run --rm authboxus/authbox-tools setup -example > answers.yaml
$ 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

This shape is your organization's, so no evaluation can stand it up for you: what you supply is a directory address and a service account, your authority's root and revocation list, and your relay. The first line prints an answers file whose integrations section takes each of them; the second is the first boot wizard, whose integrations step asks for them with an example in every field and a Test connection button, the only thing in the wizard that reaches the network. The evaluation of two organizations that trust each other (-scenario federation) shows the trust half with no outside service at all: a second organization's root appended to the pool and its people decided at the first (the evaluation runbook).

What the smoke proves

The directory proof runs against a third-party OpenLDAP holding the people and the groups, a fixture corporate authority that issues those people their certificates and issues AuthBox nothing at all, a writer with no authority section in its configuration, and a door whose one interesting route requires an attribute that exists only because of a group in somebody else's directory. Everything in the picture is issued by that corporate authority, and its issuing keystore is mounted into nothing.

The outside-authority proof makes an outside authority's root the only client trust anchor; a certificate that authority issued authenticates and resolves to the entity its subject names; and revocation propagates by re-importing the list out of band — a plain fetch, not a trust relationship maintained at runtime.

The worked federation's directory leg runs the connector against headquarters' directory on the composition's own network, binding with a keypair from a mount, and two consumers read what it adopted — and the same leg shows the lapse, where a quiet directory stops vouching.

Read on