AuthBox documentation — Scenarios

Documentation embedded in this build.

Bring the organisation you already have

What it is for

An organisation 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 organisation'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, if what you want is this enrolment 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 organisation'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

$ make scenario-corporate-directory   # a third-party directory, a corporate authority,
                                      # and a writer that issues nothing
$ make scenario-vault-external-ca     # an outside authority is the anchor, and its
                                      # revocation reaches the door
$ make all-in-one-federated           # the connector reading headquarters' directory

The two scenarios bring their own containers up, check them and take them down. The third leaves a stack running. What you supply in your own deployment is a directory address and a service account, your authority's root and revocation list, and your relay.

What the smoke proves

make scenario-corporate-directory runs the Go twin TestCorporateDirectory 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.

make scenario-vault-external-ca runs TestVaultExternalCA: an outside authority's root is 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.

make all-in-one-federated runs the directory leg of the composed smoke, whose twin is test/integration/federation/ldapsync_test.go: the connector dials the directory on the composition's own network, binds 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