Authentication
How Koban agents enroll, authenticate, and sync with Fleet.
Koban uses different credentials for enrollment and steady-state sync. Enrollment proves that a Mac is allowed to join your fleet. After enrollment, production sensor traffic is authenticated with a device certificate.
Auth model
| Phase | Credential | Purpose |
|---|---|---|
| Enrollment | Short-lived enrollment token | Lets a new agent request a device identity. |
| Sync | Device client certificate | Authenticates the enrolled Mac for config, check-in, and upload requests. |
| Development fallback | Shared sensor token | Supports local or self-hosted deployments that have not enabled mTLS. |
Fleet does not use the enrollment token for ongoing sync. Treat enrollment tokens like bootstrap credentials: issue them narrowly, rotate them, and expire them quickly.
Enrollment flow
- An admin creates an enrollment token in Fleet.
- The agent is configured with the Fleet endpoint and enrollment token.
- The agent generates a device key locally.
- The agent sends the enrollment token and public key to Fleet.
- Fleet validates the token, creates the device record, and returns a client certificate.
- The agent stores enrollment state locally and stores certificate identity material in the macOS Keychain.
The enrollment endpoint is reachable before the Mac has a client certificate. That is deliberate: a new device cannot present a certificate it has not been issued yet.
Steady-state sync
After enrollment, the agent talks to Fleet over outbound HTTPS. In production, Fleet requires the device client certificate for:
- Fetching the canonical JSON configuration bundle
- Sending check-ins
- Uploading observations, inventory updates, and findings
Fleet verifies that the certificate maps to the enrolled device and tenant. A certificate for one device cannot sync as another device.
Sensor routes
The open sensor protocol is JSON-first. These are the v1 HTTP routes:
| Method | Path | Auth |
|---|---|---|
POST | /api/sensor/v1/enroll | Enrollment token in the request body |
POST | /api/sensor/v1/config | Device client certificate in production, sensor token only when mTLS is disabled |
POST | /api/sensor/v1/check-in | Device client certificate in production, sensor token only when mTLS is disabled |
POST | /api/sensor/v1/sync | Device client certificate in production, sensor token only when mTLS is disabled |
Enrollment is the only sensor route that does not require an existing device certificate. Config, check-in, and sync requests include tenant and device IDs in the body, and Fleet checks those IDs against the authenticated client identity.
mTLS and token fallback
Production Fleet uses mTLS for protected sensor routes. The server accepts unauthenticated TLS connections only where that is required for enrollment and product APIs.
The shared sensorToken exists for development and simple self-hosted deployments without mTLS. When Fleet is configured with an mTLS CA, protected sensor routes require a verified client certificate and token fallback is disabled.
Product API auth
Fleet operator APIs use admin tokens, not device certificates. Those APIs create enrollment tokens, publish config, list devices, and review findings. Mutating operator actions require an admin role.
Sensor credentials and operator credentials are separate on purpose: a Mac can upload its own observations, but it cannot publish policy or create enrollment tokens.
YAML for humans, JSON for systems
Humans can author Fleet configuration as YAML. Fleet validates that YAML against Koban's closed rule vocabulary, canonicalizes it to JSON, and serves the JSON bundle to enrolled agents.
Agents do not need to parse remote YAML. Local agent configuration remains YAML because it is edited by people on a Mac. Remote Fleet configuration is JSON because it is the wire protocol between systems.
What is not authenticated this way
Koban does not grant Fleet remote command execution on endpoints. Authenticated sensor routes are for configuration delivery, check-in, and upload. Rules still run locally on the agent, and findings are reports rather than enforcement actions.
Config signatures are reserved for a future offline-verification mode. In v1, transport security and device identity are the production auth boundary.