docs(authentication): add authentication layer enhancement

[chadcrum]

Summary

Enhancement proposal for DCM's authentication layer — FLPATH-4194.

Targets the control-plane monolith architecture: one binary (dcm-server), one database, in-process domain calls. All technical claims cross-checked against the control-plane codebase.

• Auth proxy via oauth2-proxy — standalone reverse proxy + JWT validator in front of dcm-server. No separate API gateway needed.
• Actor middleware — Chi router middleware resolves X-Forwarded-User → actor DB lookup → request context (ActorID, TenantID, ActorType) with LRU cache (60s TTL).
• Tenant isolation — TenantScope() GORM query middleware with merge-blocking CI lint rule from day one.
• Built-in local user store — username/password → DCM-issued ES256 JWT for bootstrap and testing. Default: disabled (DCM_BUILTIN_AUTH).
• Actor/tenant lifecycle — active, suspended, deactivated states with middleware enforcement.
• CLI authentication — dcm login via OIDC Device Authorization Grant + token file for CI/CD.
• Keycloak as V1 identity provider, with Kuadrant/Authorino documented as a deferred alternative.

Jira

FLPATH-4194 (epic: FLPATH-3254)

🤖 Generated with Claude Code

[chadcrum]

Ready for review

[gabriel-farache]

good overall but there are too many implementation details mixes with the global auth architecture.
We can have "implementation orientation" sections but it should not be mixed with the rest of the doc

[gabriel-farache]

the built-in local provider

is that defined anywhere? And is that something we want? IMO we should have keycloak as a pre-requisites

[chadcrum]

The built-in provider is defined in Section 1 under "V1 Implementations." It's there for bootstrap (first admin account before Keycloak is configured) and integration tests.

That said — if we make Keycloak a hard prerequisite, we could drop the built-in provider entirely and seed the initial admin via a DB migration instead. Deploy-time config provides the Keycloak admin's sub claim (e.g., DCM_ADMIN_SUBJECT), and the migration creates the default tenant + admin actor + identity binding. No custom token endpoint, no password hashing, no extra attack surface.

Trade-off is integration tests would need a Keycloak container in CI or a test-only signing key, but that's probably more realistic anyway.

What do you think — Keycloak as a prerequisite with seed migration, or keep the built-in provider for bootstrap/testing flexibility?

[gabriel-farache]

Trade-off is integration tests would need a Keycloak container in CI or a test-only signing key, but that's probably more realistic anyway.

My thoughts exactly

I would have Keycloak as a prerequisite, what @dcm-project/team-dcm thinks about it?

[jenniferubah]

Agree to have keycloak as prerequisite.

[chadcrum]

good overall but there are too many implementation details mixes with the global auth architecture.
We can have "implementation orientation" sections but it should not be mixed with the rest of the doc

Agreed — we've started trimming Go-specific implementation details in this review round (removed some code-level references, simplified several sections). I'll continue separating the architecture from implementation as the doc evolves. The data models, sequence diagrams, and API-level integration points stay; the Go function/package references get moved or removed.