Skip to main content
Version: 0.13.0

CAC Authentication and Testing Guide

Prerequisites​

  • Gateway/ingress supports mTLS and can forward client certificate details.
  • CAC root/intermediate CAs are trusted by the gateway and the identity provider (IdP) (e.g., Keycloak).
  • A valid CAC (or test client certificate) for validation.

Required Gateway/Auth Configuration​

Set the equivalent deployment values, ConfigMap entries, or environment variables required by your release workflow:

  • KAMIWAZA_USE_AUTH=true
  • AUTH_GATEWAY_CAC_ENABLED=true
  • AUTH_GATEWAY_MTLS_REQUIRED=true (required when CAC is enabled)
  • AUTH_GATEWAY_CAC_ALLOWED_ISSUERS="<issuer1>,<issuer2>" (DNs or SHA-256 hashes; required)
  • Optional subject parsing (e.g., EDIPI):
    • AUTH_GATEWAY_CAC_SUBJECT_REGEX='(?P<last>[^.]+)\.(?P<first>[^.]+)\.(?P<middle>[^.]+)\.(?P<edipi>\d+)'
  • AUTH_GATEWAY_CAC_CRL_URLS=<url1,url2,...>
  • AUTH_GATEWAY_CAC_CRL_CACHE_TTL_SECONDS=86400 (default)
  • Dev-only fail-open: AUTH_GATEWAY_CAC_FAIL_OPEN=true to allow logins if revocation data is missing (default false blocks in that case).

Edge Header Protection (optional)​

  • AUTH_GATEWAY_CAC_EDGE_HEADER=<header name>
  • AUTH_GATEWAY_EDGE_SHARED_SECRET=<16+ chars>

TLS Hardening​

  • Set AUTH_GATEWAY_TLS_INSECURE=false in production.

Ingress/Header Expectations​

The ingress (e.g., Traefik) must:

  • Request/require client certificates on auth routes.
  • Forward the sanitized client cert PEM in X-Forwarded-Tls-Client-Cert (required).
  • Forward a verification flag in X-Forwarded-Tls-Client-Cert-Verified (e.g., SUCCESS, recommended).
  • If forwarding subject/issuer/SAN separately, align with:
    • AUTH_GATEWAY_CAC_SUBJECT_HEADER, AUTH_GATEWAY_CAC_ISSUER_HEADER, AUTH_GATEWAY_CAC_SAN_HEADER.
  • If using an edge header, inject the edge header and shared secret.

IdP (Keycloak or equivalent) Setup​

  • Import CAC (or test CA) root/intermediates into the IdP truststore.
  • Enable X.509 auth and configure a principal mapper (Subject DN, email, SAN) to link the cert to a user (or auto-link).
  • Ensure realm/client configuration matches your deployment and whitelist redirect URIs.

Test Flow​

  1. Apply the configuration above through your normal deployment workflow.
  2. If no CRL/OCSP data in non-prod, either load a CRL cache or set AUTH_GATEWAY_CAC_FAIL_OPEN=true temporarily.
  3. From a client with a CAC (or test client cert), call:
    • POST https://<gateway>/api/auth/cac/login via the ingress (not localhost).
  4. Expected: 200 with JWT/session cookies. Failures return 4xx with reasons (issuer not allowed, revocation, missing/invalid headers).
  5. Validate token/cookies by calling a simple endpoint with the bearer token (e.g., /api/ping).

Troubleshooting​

  • 400/401: Missing/invalid client cert headers; issuer not in AUTH_GATEWAY_CAC_ALLOWED_ISSUERS; IdP client/realm mismatch; redirect URIs not whitelisted.
  • Revocation failures: Verify CRL URLs/TTL; in non-prod you can set AUTH_GATEWAY_CAC_FAIL_OPEN=true.
  • mTLS handshake issues: Gateway not trusting CAC root or client cert not presented; fix ingress TLS client auth.
  • User not found: Adjust X.509 mapper in the IdP (map Subject/SAN/EDIPI to username/email) or enable auto-link.
  • Check gateway/IdP logs for the specific rejection reason (issuer mismatch, revocation, header missing).

Minimal Non-Prod Setup​

  • Use a test CA and client cert; trust the test CA in gateway and IdP.
  • Set AUTH_GATEWAY_CAC_ALLOWED_ISSUERS to the test CA.
  • In strictly local/dev, you may temporarily set AUTH_GATEWAY_TLS_INSECURE=true and AUTH_GATEWAY_CAC_FAIL_OPEN=true; revert to secure settings for real testing.