Skip to main content

Bind AeroSim Keycloak configuration to project-scoped Bitwarden keys

Project task

Bind AeroSim Keycloak configuration to project-scoped Bitwarden keys

AeroSim deployment reads its Keycloak issuer, client identity, API audience, JWKS endpoint, and cache policy from project-scoped Bitwarden keys and uses an AeroSim system client identity rather than a Nebula technology name.

AEROSIM-TS-128Canonical ID TASK-0128
Verified flow state
Done
Owner
AeroSim Architecture and Delivery
Component
Web Application, API Service, and deployment identity configuration
Repository
corp-v1-aerosim/corp-v1-aerosim; corp-v1-aerosim/gondor-v1-tmpl-aerosim; corp-v1-aerosim/gondor-v1-aerosim

Delivery scope

Replace technology-named and framework-local deployment configuration with the HL_V1_AEROSIM_KEYCLOAK_* contract; use gondor-v1-aerosim as the browser OIDC client ID; map External Secrets into the web runtime and API configuration without exposing values in source; retain Authorization Code with PKCE and local/JWKS token validation boundaries.

Implementation contract

Implementation artifacts

  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/values.yaml
  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/values.schema.json
  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/templates/web-configmap.yaml
  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/templates/api-configmap.yaml
  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/templates/web-deployment.yaml
  • corp-v1-aerosim/corp-v1-aerosim:charts/aerosim/templates/api-deployment.yaml
  • corp-v1-aerosim/corp-v1-aerosim:tests/helm/keycloak-bitwarden-contract.test.mjs
  • corp-v1-aerosim/corp-v1-aerosim:applications/web/src/auth/oidc-config.ts
  • corp-v1-aerosim/corp-v1-aerosim:applications/api/src/auth/keycloak-config.ts
  • corp-v1-aerosim/gondor-v1-tmpl-aerosim:cluster/0500-resources/{{ '0600-aerosim' if aerosim.is_enabled }}/externalsecret-aerosim-keycloak.yml.jinja
  • corp-v1-aerosim/gondor-v1-tmpl-aerosim:cluster/0500-resources/{{ '0600-aerosim' if aerosim.is_enabled }}/aerosim.yml.jinja
  • corp-v1-aerosim/gondor-v1-tmpl-aerosim:tests/test_aerosim_keycloak_template.py
  • corp-v1-aerosim/gondor-v1-aerosim:cluster/0500-resources/0600-aerosim/externalsecret-aerosim-keycloak.yml
  • corp-v1-aerosim/gondor-v1-aerosim:cluster/0500-resources/0600-aerosim/aerosim.yml
  • corp-v1-aerosim/gondor-v1-aerosim:tests/test_aerosim_keycloak_manifest.py

Inputs

  • Bitwarden keys HL_V1_AEROSIM_KEYCLOAK_ISSUER, HL_V1_AEROSIM_KEYCLOAK_CLIENT_ID, HL_V1_AEROSIM_KEYCLOAK_AUDIENCE, HL_V1_AEROSIM_KEYCLOAK_JWKS_URI, and HL_V1_AEROSIM_KEYCLOAK_JWKS_CACHE_TTL_MS.
  • Keycloak root-realm public client gondor-v1-aerosim with Authorization Code flow and PKCE S256.

Outputs

  • One retained Kubernetes Secret rendered by External Secrets and consumed by both AeroSim workloads.
  • Web runtime configuration and API validation configuration sourced from the same project-scoped identity contract.
  • Fail-closed validation that rejects nebula-web and unscoped VITE_KEYCLOAK_*/KEYCLOAK_* deployment inputs.

Failure boundaries

  • Missing or empty Bitwarden-backed values prevent workload readiness rather than silently falling back to sample identity configuration.
  • A client ID using the Nebula technology name, a wrong issuer, wrong audience, malformed JWKS URI, or cache TTL below 1000 milliseconds fails validation.
  • Browser code never receives client secrets, database credentials, or administrative Keycloak credentials.

Excluded scope

  • Keycloak user lifecycle, local credentials, MFA policy, federation, and administrator credentials remain outside AeroSim.
  • This Task does not change Authorization Code with PKCE into a confidential browser flow and does not add a browser client secret.

Verification steps

  • Render the application Helm chart and verify system-owned browser/API identity configuration without fallback to nebula-web or sample identity values.
  • Render the governed GitOps template and prove the ExternalSecret uses the five exact HL_V1_AEROSIM_KEYCLOAK_* remote keys inside the existing conditional AeroSim resource directory.
  • Verify the rendered Gondor manifests map that retained Secret into the web runtime and API configuration with client ID gondor-v1-aerosim and audience gondor-v1-aerosim-api.
  • Run focused web/API configuration tests, Helm contract tests, template and rendered-manifest tests, complete repository validation, and production builds.

Traceability

Requirements

Dependencies

Acceptance evidence

Verified delivery: application PR #180 merged and exact integration/publication CI passed; open unmerged GitOps PRs #7 and #18 passed exact-head CI; the retained five-key Bitwarden contract, public PKCE client metadata, and browser/API fail-closed boundaries passed local and remote validation. Release completion verified on product 1.0.0.0 at GitOps revision 5d3712d89dfbf7dacd993348e55f497d126c7bf9 with Argo Synced/Healthy, exact image digests, authenticated API/database access, and three-world configured-flight acceptance.

Current evidence boundary

No current implementation, acceptance, release, or deployment evidence is claimed for this planned Task. Any prior implementation may be used only as prototype and discovery evidence.