Skip to main content

Agent Enrollment And mTLS Contracts

OneProtect agent enrollment is contract-designed and has a runtime-lite token exchange implementation.

The accepted contract lives in:

  • docs/adr/ADR-0009-agent-enrollment-mtls-identity.md
  • docs/architecture/agent-enrollment-mtls-contracts.md
  • specs/openapi.yaml
  • specs/asyncapi.yaml
  • specs/events/agent.*.v1.schema.json

Contract Summary​

Tenant admins create bounded enrollment tokens scoped to tenant, site, allowed agent class, expiration, and maximum use count. Agents use those bootstrap tokens over HTTPS with a CSR and nonce to receive per-device certificate identity. Future agent API calls use mTLS with that device certificate.

The enrollment token is not long-lived identity. It is returned once, stored hashed or redacted, and must never appear in logs, audit output, traces, UI, or support exports.

API Surface​

The OpenAPI contract marks these paths as implemented-runtime-lite:

  • GET /api/v1/agent-enrollment/tokens
  • POST /api/v1/agent-enrollment/tokens
  • POST /api/v1/agent-enrollment/tokens/{enrollment_token_id}/revoke
  • POST /api/v1/agent-enrollment/exchange
  • GET /api/v1/agents
  • GET /api/v1/agents/{agent_id}
  • POST /api/v1/agents/{agent_id}/telemetry/heartbeat

Future contract-only paths remain:

  • POST /api/v1/agents/{agent_id}/certificate/rotate
  • POST /api/v1/agents/{agent_id}/revoke

The runtime-lite exchange stores tenant-scoped agent identity and placeholder certificate metadata so downstream discovery, SSH, macOS, and command work can depend on identity records without pretending CA runtime is complete.

The identity-bound telemetry endpoint accepts heartbeats only from service-account callers whose actor or collector binding matches an enrolled or active agent identity in the authenticated tenant. Unknown identities fail with 401; revoked, stale, mismatched, or non-service-account callers fail with 403.

Events​

AsyncAPI and JSON Schema cover:

  • agent.enrollment_token.issued
  • agent.enrollment_token.revoked
  • agent.enrollment.failed
  • agent.enrolled
  • agent.certificate.rotated
  • agent.revoked

agent.enrolled remains additive and backward-compatible with the current asset heartbeat ingestion path.

Security Rules​

  • Token creation/revocation requires tenant_admin or system_admin.
  • Token exchange is bootstrap unauthenticated at bearer-token level, but token verifier, tenant/site scope, expiration, use count, CSR validity, nonce, and rate limits are mandatory authorization inputs.
  • Certificate rotation requires a valid current device certificate or approved tenant/system admin recovery.
  • Agent revocation is tenant-scoped and audited.
  • Source IP is never tenant identity.

Runtime Boundary​

The current runtime does not implement a CA, mTLS enforcement, collector runtime, active/passive discovery, command routing, or deployment change. Future runtime work must preserve these tenant, audit, telemetry authorization, and lifecycle semantics.