gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-09 17:08:53 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
aa6fafdee927691060aa7cfec6790d258c65ee2a
certctl/deploy/helm/certctl/templates/server-deployment.yaml
T
shankar0123 9c1d446e40 fix(security,config): remove unimplemented JWT auth-type, close silent downgrade (G-1) 
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'.
2026-04-25 00:22:23 +00:00

210 lines
7.9 KiB
YAML
Raw Blame History

{{- include "certctl.tls.required" . }}
{{- include "certctl.validateAuthType" . }}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "certctl.fullname" . }}-server
labels:
{{- include "certctl.labels" . | nindent 4 }}
app.kubernetes.io/component: server
spec:
{{- if gt (int .Values.server.replicas) 1 }}
replicas: {{ .Values.server.replicas }}
{{- end }}
selector:
matchLabels:
{{- include "certctl.serverSelectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "certctl.serverSelectorLabels" . | nindent 8 }}
annotations:
checksum/config: {{ include (print $.Template.BasePath "/server-configmap.yaml") . | sha256sum }}
checksum/secret: {{ include (print $.Template.BasePath "/server-secret.yaml") . | sha256sum }}
spec:
serviceAccountName: {{ include "certctl.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.server.securityContext | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: server
image: {{ include "certctl.serverImage" . }}
imagePullPolicy: {{ .Values.server.image.pullPolicy }}
ports:
- name: https
containerPort: {{ .Values.server.port }}
protocol: TCP
env:
- name: CERTCTL_SERVER_HOST
value: "0.0.0.0"
- name: CERTCTL_SERVER_PORT
value: "{{ .Values.server.port }}"
- name: CERTCTL_SERVER_TLS_CERT_PATH
value: "{{ .Values.server.tls.mountPath }}/tls.crt"
- name: CERTCTL_SERVER_TLS_KEY_PATH
value: "{{ .Values.server.tls.mountPath }}/tls.key"
- name: CERTCTL_DATABASE_URL
valueFrom:
secretKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: database-url
- name: POSTGRES_PASSWORD
valueFrom:
secretKeyRef:
name: {{ include "certctl.fullname" . }}-postgres
key: password
- name: CERTCTL_LOG_LEVEL
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: log-level
- name: CERTCTL_LOG_FORMAT
value: "json"
- name: CERTCTL_AUTH_TYPE
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: auth-type
{{- if eq .Values.server.auth.type "api-key" }}
- name: CERTCTL_AUTH_SECRET
valueFrom:
secretKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: api-key
{{- end }}
- name: CERTCTL_KEYGEN_MODE
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: keygen-mode
- name: CERTCTL_RATE_LIMIT_RPS
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: rate-limit-rps
- name: CERTCTL_RATE_LIMIT_BURST
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: rate-limit-burst
{{- if .Values.server.cors.origins }}
- name: CERTCTL_CORS_ORIGINS
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: cors-origins
{{- end }}
{{- if .Values.server.networkScan.enabled }}
- name: CERTCTL_NETWORK_SCAN_ENABLED
value: "true"
- name: CERTCTL_NETWORK_SCAN_INTERVAL
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: network-scan-interval
{{- end }}
{{- if .Values.server.est.enabled }}
- name: CERTCTL_EST_ENABLED
value: "true"
- name: CERTCTL_EST_ISSUER_ID
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: est-issuer-id
{{- if .Values.server.est.profileID }}
- name: CERTCTL_EST_PROFILE_ID
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: est-profile-id
{{- end }}
{{- end }}
{{- if .Values.server.smtp.enabled }}
- name: CERTCTL_SMTP_HOST
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: smtp-host
- name: CERTCTL_SMTP_PORT
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: smtp-port
- name: CERTCTL_SMTP_USERNAME
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: smtp-username
- name: CERTCTL_SMTP_PASSWORD
valueFrom:
secretKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: smtp-password
- name: CERTCTL_SMTP_FROM_ADDRESS
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: smtp-from-address
{{- end }}
{{- if .Values.server.issuer.acme.enabled }}
- name: CERTCTL_ACME_DIRECTORY_URL
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: acme-directory-url
- name: CERTCTL_ACME_EMAIL
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: acme-email
- name: CERTCTL_ACME_CHALLENGE_TYPE
valueFrom:
configMapKeyRef:
name: {{ include "certctl.fullname" . }}-server
key: acme-challenge-type
{{- end }}
{{- with .Values.server.env }}
{{- toYaml . | nindent 12 }}
{{- end }}
livenessProbe:
{{- toYaml .Values.server.livenessProbe | nindent 12 }}
readinessProbe:
{{- toYaml .Values.server.readinessProbe | nindent 12 }}
resources:
{{- toYaml .Values.server.resources | nindent 12 }}
volumeMounts:
- name: tmp
mountPath: /tmp
- name: tls
mountPath: {{ .Values.server.tls.mountPath }}
readOnly: true
{{- if .Values.server.volumeMounts }}
{{- toYaml .Values.server.volumeMounts | nindent 12 }}
{{- end }}
volumes:
- name: tmp
emptyDir: {}
- name: tls
secret:
secretName: {{ include "certctl.tls.secretName" . }}
defaultMode: 0400
{{- if .Values.server.volumes }}
{{- toYaml .Values.server.volumes | nindent 8 }}
{{- end }}
{{- if .Values.nodeAffinity }}
affinity:
nodeAffinity:
{{- toYaml .Values.nodeAffinity | nindent 10 }}
{{- else if .Values.podAntiAffinity }}
affinity:
podAntiAffinity:
{{- toYaml .Values.podAntiAffinity | nindent 10 }}
{{- else if .Values.podAffinity }}
affinity:
podAffinity:
{{- toYaml .Values.podAffinity | nindent 10 }}
{{- end }}
Reference in New Issue View Git Blame Copy Permalink