Authentication

Requests to ctrl authenticate with an Operator identity over mTLS, and requests to the node data plane carry a short-lived session credential. This page shows how a program obtains an Operator identity, how to configure TLS for both endpoints, and how to keep the identity renewed.

OverviewCopy Anchor Link

An enrolled Operator has cluster administration permissions and can call the Workspace API and the Operator API. Trusting the server certificate alone grants no permissions.

An identity is a client certificate that ctrl issues, valid for 30 days. A program obtains one in one of two ways:

Requests to the node data plane authenticate with a session credential instead, which the program requests from ctrl. See Data plane.

Obtaining an Operator identityCopy Anchor Link

Reading a kibo context directoryCopy Anchor Link

The simplest way is to enroll a dedicated directory for the program with kibo context enroll:

1. Issue an enrollment key for the program with kibo enrollment create --operator.
2. Set KIBO_CONTEXT_DIR to the directory the program will read, and run the enrollment.
3. Delete the key file after enrollment succeeds.

The following commands issue a key for an Operator named build-bot, enroll it into its own directory, and delete the key:

kibo enrollment create --operator build-bot --output build-bot.key
KIBO_CONTEXT_DIR="$HOME/.config/build-bot/kibo-context" kibo context enroll --endpoint https://ctrl.example.com:18092 --key-file build-bot.key
rm build-bot.key

For the other ways to provide the key and to set a proxy, see Identity and enrollment.

The directory defaults to $XDG_CONFIG_HOME/kibo/context, or ~/.config/kibo/context when that variable is unset. The environment variable KIBO_CONTEXT_DIR can point to another location.

The directory contains these files:

Go programs can open this directory with the Go SDK, which also renews the identity.

Enrolling on your ownCopy Anchor Link

A program can also use an enrollment key directly. The key that an Operator generates with kibo enrollment create --operator <id> is a three-part string:

kek1.<bootstrap certificate DER>.<bootstrap private key PKCS#8 DER>.<server CA DER>

All three parts are base64url-encoded. Use the bootstrap certificate and private key for mTLS, trust the server CA in the third part, and call kibotos.enrollment.v1.EnrollmentService/Enroll:

• The request has a single field, certificate_request: a DER-encoded PKCS#10 CSR of at most 8 KiB, without extensions or names. The subject in the CSR is ignored by ctrl; the identity is determined entirely by the grant behind the key.
• The response is an IssuedIdentity: identity_uri (of the form spiffe://<trust-domain>/operator/<id>), certificate (DER certificate), ca_certificate (the client CA in DER), serial, not_before, and not_after. The private key always stays on the client.
• A bootstrap identity can call only Enroll. A full identity can call only Renew and can no longer call Enroll. This restriction applies before the server reads the request body.
• Using the same key a second time returns already_exists.

Before saving the identity, verify it the way kibo does:

• The CA belongs to the expected trust domain.
• The certificate chain is valid.
• The public key in the certificate matches your private key.
• The URI has the correct type and subject.
• The key usage extensions and validity period are reasonable.

For the request and response messages, see EnrollmentService.

TLS settingsCopy Anchor Link

ctrl and the node data plane verify the server differently. Configure the client for each endpoint as follows:

For ctrl, also require TLS 1.3 or later and advertise h2 in ALPN.

The data-plane trust lets the deployer put the node behind a public TLS reverse proxy. For how the certificates are issued and which host names a node's data-plane certificate covers, see Server and data-plane certificates.

RenewalCopy Anchor Link

An identity is valid for 30 days. Renew it when fewer than 10 days remain.

To renew, call kibotos.enrollment.v1.EnrollmentService/Renew with the current identity. The request body is a CSR for a new private key. This is what kibo context renew does.

Moving requests to the new certificateCopy Anchor Link

A TLS connection keeps presenting the certificate from its handshake, and a connection that always has requests never closes as idle.

For the lifetime of every certificate, revocation, and recovery, see Renewal, revocation, and recovery.

Next stepsCopy Anchor Link

• Write operations and errors: capabilities, command IDs, expected revisions, and the error format.
• Data plane: requesting a session credential and calling the node.
• Identity, configuration, and connections: certificates, the context directory, and proxies.