mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 22:11:38 +00:00
Shankar
54a41603de
The pre-G-1 config validator accepted CERTCTL_AUTH_TYPE=jwt and the
startup log faithfully echoed 'authentication enabled type=jwt'.
Reasonable people read that and concluded JWT auth was on. It wasn't.
The auth-middleware wiring at cmd/server/main.go unconditionally routed
every request through the api-key bearer middleware regardless of
cfg.Auth.Type. So CERTCTL_AUTH_TYPE=jwt quietly compared the incoming
'Authorization: Bearer <token>' against whatever string the operator put
in CERTCTL_AUTH_SECRET — real JWT clients got 401, and operators who
treated CERTCTL_AUTH_SECRET as a *signing* secret (because they thought
they were configuring JWT) had effectively handed an attacker an api-key.
A security finding masquerading as a config option.
We chose the audit-recommended structural fix: remove the option, fail
fast at startup, and add the gateway-fronting pattern as the documented
forward path. Implementing JWT middleware would have meant jwks vs
static-secret rotation, claim mapping, expiry enforcement, audience and
issuer validation, key rollover semantics, and regression coverage at the
same depth as the existing api-key path — a feature, not a fix. Operators
who genuinely need JWT/OIDC front certctl with an authenticating gateway
(oauth2-proxy / Envoy ext_authz / Traefik ForwardAuth / Pomerium /
Authelia) and run the upstream certctl with CERTCTL_AUTH_TYPE=none. Same
shape works on docker-compose and Helm.
The change is comprehensive across 7 phases — every surface that
mentioned 'jwt' as a certctl-auth-type is updated, plus structural
backstops (typed enum, runtime guard, helm template validation, CI grep
guard) so the lie can't reappear.
Files changed:
Phase 1 — production code (typed enum + jwt removal):
- internal/config/config.go: AuthType typed alias + AuthTypeAPIKey /
AuthTypeNone constants + ValidAuthTypes() helper. Validate() routes
literal 'jwt' through a dedicated multi-line diagnostic naming the
authenticating-gateway pattern, then cross-checks against
ValidAuthTypes(). Secret-required branch simplified to api-key-only.
Field comment on AuthConfig.Type rewritten to drop jwt and point at
the gateway pattern.
- internal/api/middleware/middleware.go: AuthConfig.Type field comment
references the typed config.AuthType constants.
- internal/api/handler/health.go: same treatment for HealthHandler.AuthType.
- cmd/server/main.go: defense-in-depth runtime switch immediately after
config.Load() — exits 1 on any unsupported auth-type that bypassed the
validator. Auth-disabled startup log explicitly names the
authenticating-gateway pattern.
Phase 2 — tests (Red→Green, contract pinning):
- internal/config/config_test.go: TestValidate_JWTAuth_RejectedDedicated
(two table rows pinning the dedicated G-1 error fires regardless of
whether Secret is set), TestValidAuthTypesDoesNotContainJWT (property
guard against future re-introduction),
TestValidAuthTypesIsExactly_APIKey_None (allowed-set contract),
TestValidate_GenericInvalidAuthType (pins non-jwt invalid values still
hit the generic invalid-auth-type error). Removed the prior
TestValidate_JWTAuth_MissingSecret happy-path since its premise is
inverted post-G-1.
- internal/api/handler/health_test.go: removed
TestAuthInfo_ReturnsAuthType_JWT (which baked the silent-downgrade lie
into the regression suite). Pre-existing _APIKey test continues to
cover the api-key happy path.
Phase 3 — spec, docs, env templates:
- api/openapi.yaml: auth_type enum dropped to [api-key, none] with
inline comment naming the G-1 closure.
- .env.example (root): CERTCTL_AUTH_TYPE comment block rewritten to drop
jwt and point at the gateway pattern; secret-required conditional
simplified to api-key-only.
- docs/architecture.md: middleware-stack bullet rewritten to drop the
JWT mention; new H3 'Authenticating-gateway pattern (JWT, OIDC, mTLS)'
section explaining the design rationale and listing oauth2-proxy /
Envoy ext_authz / Traefik ForwardAuth / Pomerium / Authelia / Caddy
forward_auth / Apache mod_auth_openidc / nginx auth_request as the
standard fronting options.
- docs/upgrade-to-v2-jwt-removal.md (new ~125 lines): migration guide
with preconditions, what-changes, both recovery paths, complete
docker-compose oauth2-proxy walkthrough, Traefik ForwardAuth and Envoy
ext_authz patterns, rollback posture.
Phase 4 — Helm chart (template validation + docs):
- deploy/helm/certctl/templates/_helpers.tpl: new certctl.validateAuthType
helper mirroring the existing certctl.tls.required pattern. Fails
template render on any server.auth.type outside {api-key, none} with
a multi-line diagnostic.
- deploy/helm/certctl/templates/server-deployment.yaml,
server-configmap.yaml, server-secret.yaml: invoke the helper at the
top of each template that depends on .Values.server.auth.type.
- deploy/helm/certctl/values.yaml: auth: block comment expanded with the
G-1 rationale and gateway-pattern cross-reference.
- deploy/helm/CHART_SUMMARY.md: server.auth.type table row now surfaces
the allowed set and points at the upgrade doc.
- deploy/helm/certctl/README.md: new 'JWT / OIDC via authenticating
gateway' section with a Kubernetes-flavored oauth2-proxy + certctl
walkthrough.
Phase 5 — release surface:
- CHANGELOG.md: new [unreleased] top entry with Breaking / Removed /
Added / Changed sections; explicit pointer at
docs/upgrade-to-v2-jwt-removal.md from the Breaking subsection.
Phase 6 — CI guardrail:
- .github/workflows/ci.yml: new 'Forbidden auth-type literal regression
guard (G-1)' step. Scoped patterns catch the actual regression shapes
(map literal, slice literal, switch case, OpenAPI enum, env-file
default, AuthType('jwt') cast). Comments and the dedicated rejection
branch are intentionally exempt; connector-package JWT references
(Google OAuth2 / step-ca) are exempt as out-of-scope external
protocols. Verified locally: the guard passes on the actual tree and
fires on all 4 synthetic regression patterns.
Out of scope (explicitly untouched):
- internal/connector/discovery/gcpsm/gcpsm.go — Google OAuth2 service-
account JWT (external protocol).
- internal/connector/issuer/googlecas/googlecas.go — same.
- internal/connector/issuer/stepca/stepca.go — step-ca's provisioner
one-time-token JWT for /sign API.
- docs/test-env.md, docs/connectors.md, docs/features.md — describe
external CAs' use of JWT, not certctl's auth shape.
- Implementing actual JWT middleware. Feature, not a fix.
Verification (all gates pass):
- go build ./... — clean
- go vet ./... — clean
- go test -short ./... — every package green
- go test -short -race ./internal/config/... ./internal/api/... — clean
- govulncheck ./... — no vulnerabilities in our code
- helm lint deploy/helm/certctl/ — clean
- helm template with auth.type=api-key — renders OK
- helm template with auth.type=none — renders OK
- helm template with auth.type=jwt — fails with validateAuthType
diagnostic (exit 1)
- python3 yaml.safe_load on api/openapi.yaml — parses
- CI guardrail mirror — clean on real tree, fires on all 4 synthetic
regression patterns
- Smoke test: 'CERTCTL_AUTH_TYPE=jwt ./certctl-server' exits non-zero
with: 'Failed to load configuration: CERTCTL_AUTH_TYPE=jwt is no
longer accepted (G-1 silent auth downgrade): no JWT middleware ships
with certctl. To use JWT/OIDC, run an authenticating gateway
(oauth2-proxy / Envoy ext_authz / Traefik ForwardAuth / Pomerium) in
front of certctl and set CERTCTL_AUTH_TYPE=none on the upstream.
See docs/architecture.md "Authenticating-gateway pattern" and
docs/upgrade-to-v2-jwt-removal.md for the migration walkthrough'
config pkg coverage: ValidAuthTypes 100%, Validate 94.7%, total 75.5%.
Refs: coverage-gap-audit-2026-04-24-v5/unified-audit.md
§2 P1 cluster, cat-g-jwt_silent_auth_downgrade
Audit recommendation followed verbatim: 'Remove jwt from
validAuthTypes until middleware ships'.
64 lines
3.2 KiB
Bash
64 lines
3.2 KiB
Bash
# Certctl Configuration Example
|
|
# Copy this file to .env and configure for your environment
|
|
# DO NOT commit .env with real secrets to version control
|
|
|
|
# ==============================================================================
|
|
# PostgreSQL (used by Docker Compose for the postgres container)
|
|
# ==============================================================================
|
|
POSTGRES_DB=certctl
|
|
POSTGRES_USER=certctl
|
|
POSTGRES_PASSWORD=change-me-in-production
|
|
|
|
# ==============================================================================
|
|
# Certctl Server
|
|
# All server vars use the CERTCTL_ prefix (see internal/config/config.go)
|
|
# ==============================================================================
|
|
# IMPORTANT: keep the password segment of CERTCTL_DATABASE_URL in sync with
|
|
# POSTGRES_PASSWORD above. If you deploy via `deploy/docker-compose.yml`,
|
|
# this value is *overridden* by the compose file's
|
|
# `postgres://certctl:${POSTGRES_PASSWORD:-certctl}@postgres:5432/...`
|
|
# interpolation — but if you run the binary directly with this .env loaded
|
|
# (e.g. `set -a; source .env; ./certctl-server`), update *both* lines.
|
|
# Background: editing POSTGRES_PASSWORD after the postgres data directory
|
|
# has been initialized once does NOT rotate the password — initdb only
|
|
# seeds pg_authid on first boot of an empty volume. See docs/quickstart.md
|
|
# "Warning" callout and `internal/repository/postgres/db.go::wrapPingError`
|
|
# for the SQLSTATE 28P01 diagnostic that fires when the two drift.
|
|
CERTCTL_DATABASE_URL=postgres://certctl:change-me-in-production@postgres:5432/certctl?sslmode=disable
|
|
CERTCTL_SERVER_HOST=0.0.0.0
|
|
CERTCTL_SERVER_PORT=8443
|
|
CERTCTL_LOG_LEVEL=info
|
|
CERTCTL_LOG_FORMAT=json
|
|
|
|
# Auth type: "api-key" (production) or "none" (demo/development).
|
|
# For JWT/OIDC, run an authenticating gateway in front of certctl
|
|
# (oauth2-proxy / Envoy ext_authz / Traefik ForwardAuth / Pomerium) and
|
|
# set CERTCTL_AUTH_TYPE=none on the upstream — see
|
|
# docs/architecture.md "Authenticating-gateway pattern". G-1 removed
|
|
# the in-process "jwt" option (no JWT middleware shipped — silent auth
|
|
# downgrade); see docs/upgrade-to-v2-jwt-removal.md if you previously
|
|
# set CERTCTL_AUTH_TYPE=jwt.
|
|
CERTCTL_AUTH_TYPE=none
|
|
# Required when CERTCTL_AUTH_TYPE is "api-key".
|
|
# Generate with: openssl rand -base64 32
|
|
# CERTCTL_AUTH_SECRET=change-me-in-production
|
|
|
|
# ==============================================================================
|
|
# Certctl Agent
|
|
# ==============================================================================
|
|
# HTTPS-only as of v2.2 (TLS 1.3 pinned). Agents reject http:// URLs at
|
|
# startup. Use the docker-compose self-signed bootstrap CA bundle from
|
|
# `deploy/test/certs/ca.crt` or supply your own via CERTCTL_SERVER_CA_BUNDLE_PATH.
|
|
CERTCTL_SERVER_URL=https://localhost:8443
|
|
CERTCTL_API_KEY=change-me-in-production
|
|
CERTCTL_AGENT_NAME=local-agent
|
|
|
|
# ==============================================================================
|
|
# Optional: Scheduler Tuning (defaults are usually fine)
|
|
# ==============================================================================
|
|
# CERTCTL_SCHEDULER_RENEWAL_CHECK_INTERVAL=1h
|
|
# CERTCTL_SCHEDULER_JOB_PROCESSOR_INTERVAL=30s
|
|
# CERTCTL_SCHEDULER_AGENT_HEALTH_CHECK_INTERVAL=2m
|
|
# CERTCTL_SCHEDULER_NOTIFICATION_PROCESS_INTERVAL=1m
|
|
# CERTCTL_DATABASE_MAX_CONNS=25
|