Skip to main content

OIDC/AuthContext + Keycloak Local Profile

Status​

Implemented as a production-shaped seam and local OIDC profile. Full enterprise IAM, SCIM, OPA/ABAC, and production IdP lifecycle remain planned.

  • SRS references: tenant-aware roles and auditor-safe access.
  • Client response references: SCIM 2.0 is Phase 1; agent/device certificate identity is separate Phase 1 work.
  • ADR references: Phase 1 platform stack ADR; production IdP ADR remains open.
  • Task board references: OP-D028, OP-D037, OP-029, OP-034.

Problem Statement​

The application must depend on a provider-agnostic auth/session abstraction, while supporting real OIDC verification for local and future hosted runtimes.

Architectural Intent​

FastAPI derives request context from verified authentication and maps it into AuthContext. Application handlers should consume AuthContext and centralized role checks rather than Keycloak internals.

What Was Implemented​

  • AuthContext and AuthProvider seam.
  • OIDC JWT verification for issuer, audience, expiration, and JWKS signature.
  • Configurable actor, tenant, and role claim mapping.
  • Local Keycloak Compose profile and realm import for dev/test.
  • Dev-token mode restricted to local/dev/test.
  • Raw header auth disabled by default.
  • /api/v1/session endpoint.

Components Involved​

  • poc/ingest_api/auth.py
  • poc/ingest_api/authorization.py
  • deploy/keycloak/realm-oneprotect-dev.json
  • docker-compose.yml
  • Frontend API client bearer-token support.

APIs / Events / Schemas​

  • GET /api/v1/session
  • Auth roles: system_admin, operator, tenant_admin, auditor
  • OIDC claims: tenant_id, role, configurable actor claim such as preferred_username

Deployment Notes​

Local OIDC can be run with the Compose auth profile. Production/staging should use a managed or separately operated OIDC provider; the app chart expects OIDC configuration and must not silently fall back to dev-token mode.

Security / Tenant Isolation​

  • Missing or invalid tokens fail closed.
  • OIDC mode does not fall back to dev-token.
  • Tenant context comes from verified token claims.
  • Auditor role is read-only through centralized role enforcement.
  • Keycloak local credentials are placeholders for local/dev/test only.

Validation Steps​

UI Validation​

  1. Start the app with local Keycloak enabled.
  2. Use a Keycloak token for tenant-admin@example.test, operator@example.test, or auditor@example.test.
  3. Open the console and confirm actor, role, and tenant context are displayed.
  4. Confirm auditor pages show read-only treatment.

API Validation​

curl -H "Authorization: Bearer <oidc-token>" \
  http://127.0.0.1:8000/api/v1/session

Smoke Validation​

docker compose --profile auth config
make smoke-keycloak
make test

Known Limitations​

  • Full login UI is not implemented.
  • SCIM runtime provisioning is implemented in OP-034R. Entra/Okta adapters and standards-shaped SCIM aliases remain future work.
  • Production/staging realm lifecycle is not implemented.
  • Service-account token lifecycle is minimal.
  • OPA/ABAC is future work.

Follow-Up Work​

  • Add Entra/Okta SCIM adapter compatibility after OP-034R.
  • Decide production IdP lifecycle.
  • Add agent enrollment/mTLS identity contracts.
  • Add OPA/ABAC boundary after role model stabilizes.

Acceptance Criteria Mapping​

Acceptance criterionEvidence
App uses auth seamAuthContext and AuthProvider implementation
OIDC tokens are verifiedOIDC auth tests and JWKS validation
Local Keycloak profile existsdeploy/keycloak/realm-oneprotect-dev.json
Dev-token remains local/test onlyAuth configuration tests