Skip to main content

Agent Enrollment And mTLS Identity Contracts

Status​

Contract Designed

  • Client response references: Phase 1 tenant-scoped enrollment token, token-for-certificate exchange, per-device certificate identity, and future mTLS authentication.
  • ADR references: docs/adr/ADR-0009-agent-enrollment-mtls-identity.md.
  • Task board references: OP-032.

Problem Statement​

Collector runtime and richer RMM features need trustworthy tenant-scoped device identity before they expand. Enrollment cannot rely on source IP, shared secrets, or implicit network location.

Architectural Intent​

OneProtect uses tenant admin-created enrollment tokens only as bootstrap secrets. A newly installed agent exchanges a token and CSR over HTTPS for a per-device certificate identity. Future agent API calls authenticate with mTLS.

What Was Implemented​

  • ADR-0009 accepted the enrollment and mTLS identity model.
  • Architecture documentation now defines token issuance, token exchange, certificate lifecycle, revocation, audit, authorization, and tenant boundaries.
  • OpenAPI defines contract-only enrollment, rotation, and revocation endpoints.
  • AsyncAPI and JSON Schema define enrollment lifecycle events.
  • Contract validation covers the new event payloads.

Components Involved​

  • OpenAPI: specs/openapi.yaml
  • AsyncAPI: specs/asyncapi.yaml
  • Event schemas: specs/events/agent.*.v1.schema.json
  • Architecture docs: docs/architecture/agent-enrollment-mtls-contracts.md
  • ADRs: docs/adr/ADR-0009-agent-enrollment-mtls-identity.md

APIs / Events / Schemas​

  • API: POST /api/v1/agent-enrollment/tokens
  • API: POST /api/v1/agent-enrollment/exchange
  • API: POST /api/v1/agents/{agent_id}/certificate/rotate
  • API: POST /api/v1/agents/{agent_id}/revoke
  • Event: agent.enrollment_token.issued
  • Event: agent.enrollment_token.revoked
  • Event: agent.enrollment.failed
  • Event: agent.enrolled
  • Event: agent.certificate.rotated
  • Event: agent.revoked

Deployment Notes​

No deployment change. Runtime CA selection and mTLS enforcement are future implementation work.

Security / Tenant Isolation​

All token, agent, certificate, revocation, event, and audit records are tenant-scoped. Token secrets are returned once and must be redacted everywhere else. Source IP is never tenant identity. Revocation must stop future API/worker acceptance after propagation.

Validation Steps​

UI Validation​

No UI validation is applicable; this is a contract/design branch.

API Validation​

make validate-contracts

Smoke Validation​

make validate-contracts

Known Limitations​

  • CA runtime is not implemented.
  • mTLS enforcement is not implemented.
  • Collector runtime, active/passive discovery runtime, command routing, and macOS/Intune runtime work remain future branches. Discovery authorization is contract-designed in ADR-0012, and macOS/Intune scope is contract-designed in ADR-0017.

Follow-Up Work​

  • Implement enrollment service storage and RLS.
  • Select or implement the Phase 1 certificate issuing path.
  • Build collector runtime against this identity contract.
  • Use ADR-0012 discovery authorization before scanner or passive observation runtime.

Acceptance Criteria Mapping​

Acceptance criterionEvidence
Tenant admin enrollment token contract is acceptedspecs/openapi.yaml, ADR-0009
Token-for-certificate exchange is contract-defineddocs/architecture/agent-enrollment-mtls-contracts.md
Device certificate lifecycle is contract-definedspecs/events/agent.certificate.rotated.v1.schema.json, specs/events/agent.revoked.v1.schema.json
Revocation and audit events are contract-definedspecs/asyncapi.yaml, scripts/validate_contracts.py