Skip to content

Commit 7215b02

Browse files
feat(keycloak): load additional CA files from Secret or ConfigMap keys (#5039)
## What this PR does Closes #3823. With the stock Cozystack chart, Keycloak cannot connect to an LDAPS server, external identity provider or SMTP server signed by a private CA because the chart cannot deliver a CA file to its truststore. Add `truststores`, a list of existing Secret/ConfigMap references in the release namespace, with one selected key per entry (`ca.crt` by default). ```yaml truststores: - configMapName: freeipa-ca key: ca.crt - secretName: partner-ca key: certificates.pem ``` Each key is mounted read-only in a separate `cozystack-<index>` subdirectory of `/opt/keycloak/conf/truststores`. Keycloak discovers it automatically; the chart adds no environment override, Kubernetes API permission or arbitrary volume path. Existing image certificates, Java default roots, themes and `extraEnv` keep their behavior. References are mandatory: a missing object or selected key prevents the pod from starting. Helm validates the reference shape and safe key paths, but cannot inspect external certificate contents. The trust decision belongs to platform administrators and applies to the entire Keycloak server, across all realms. Write access to a referenced object therefore permits changing that server's trust. If HTTPS client authentication is set to `request` or `required` without a separate `https-trust-store-file`, these CAs also verify incoming client certificates; configure that file explicitly when incoming mTLS requires a different trust boundary. Use public certificates only (PEM bundles or unencrypted PKCS12 without private keys). This does not disable TLS hostname verification. Updating an object's contents does not restart Keycloak or reload its truststore: restart both pods after rotation, or use a versioned object name to trigger a rollout. Validation: - All 113 Keycloak Helm tests pass, including 21 new cases for reference wiring, read-only mounts, selected-key isolation, themes, PKCS12 filenames, defaults and invalid input. - Boundary tests reject source names and keys of 254 characters and the single-dot key, and accept a source name and key of exactly 253 characters. Removing any of the three guards makes its regression test fail; changing either length comparison to reject 253 also fails the boundary test. - Empty-default render matches a clean upstream/main worktree after normalizing the existing randomly generated bootstrap password. Four mutations (wrong mount path, writable mount, wrong selected key and removed validation) each turn the new suite red. - Enabled and default manifests render successfully; enabled YAML parses with yq. `git diff --check` passes. - Runtime check with official Keycloak 26.6.3 in isolated Docker: synthetic LDAPS succeeds with a CA loaded automatically through an emulated Kubernetes AtomicWriter symlink layout (HTTP 204 from the LDAP connection-test Admin API); no custom CA fails with PKIX, and a trusted CA with a mismatched SAN fails hostname verification (both HTTP 400). KC_TRUSTSTORE_PATHS was unset. This checks TLS establishment, not a complete federation bind/failover or deployment to a Kubernetes cluster. - `make generate` has no target in this system chart; no generated schema/API files are involved. `make show` requires the unavailable cozyhr CLI and a live release, so rendering uses `helm template`. `helm lint` reports the same pre-existing undeclared cozy-lib dependency on both this branch and clean main. ### Screenshots Not applicable; no UI changes. ### Downstream repositories The website guide currently says CA mounts are unavailable, so its `next` documentation needs updating once this ships. Other downstream trigger-map entries do not apply: this only adds an opt-in value to the system Keycloak chart, with no app schema, platform configuration, CRD, tooling, naming or node-contract changes. - [ ] No downstream repository is affected by this change - [x] [cozystack/website](https://github.com/cozystack/website) - follow-up: cozystack/website#765 - [ ] [cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack) - follow-up: - [ ] [cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack) - follow-up: - [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up: - [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up: - [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) - follow-up: - [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) - follow-up: - [ ] [cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) - follow-up: - [ ] [cozystack/external-apps-example](https://github.com/cozystack/external-apps-example) - follow-up: - [ ] [cozystack/examples](https://github.com/cozystack/examples) - follow-up: - [ ] [cozystack/community](https://github.com/cozystack/community) - follow-up: ### Release note ```release-note feat(keycloak): load additional CA files from existing Secret or ConfigMap keys through the new truststores value, enabling TLS to private LDAPS, identity-provider and SMTP endpoints. ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## Summary by CodeRabbit - **New Features** - Added support for configuring Keycloak truststores from existing Secrets or ConfigMaps. - Supports PEM bundles and unencrypted PKCS12 certificates, with optional key selection and read-only mounts. - Truststore certificates apply server-wide, including incoming client-certificate validation when no separate HTTPS truststore is configured. - Invalid truststore configurations produce clear errors. Missing objects or keys prevent startup; certificate rotations require pod restarts unless the referenced object name changes. - **Tests** - Added coverage for default behavior, multiple truststore sources, theme mounts, explicit paths, and invalid configurations. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 749d401 + d607b68 commit 7215b02

4 files changed

Lines changed: 358 additions & 2 deletions

File tree

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{{- define "keycloak.truststores.validate" -}}
2+
{{- if not (kindIs "slice" .Values.truststores) -}}
3+
{{- fail "truststores must be a list" -}}
4+
{{- end -}}
5+
{{- range $i, $store := .Values.truststores -}}
6+
{{- if not (kindIs "map" $store) -}}
7+
{{- fail (printf "truststores[%d] must be an object" $i) -}}
8+
{{- end -}}
9+
{{- range $field, $_ := $store -}}
10+
{{- if not (has $field (list "secretName" "configMapName" "key")) -}}
11+
{{- fail (printf "truststores[%d]: unknown field %s" $i $field) -}}
12+
{{- end -}}
13+
{{- end -}}
14+
{{- if eq (hasKey $store "secretName") (hasKey $store "configMapName") -}}
15+
{{- fail (printf "truststores[%d] must set exactly one of secretName or configMapName" $i) -}}
16+
{{- end -}}
17+
{{- $name := get $store "secretName" -}}
18+
{{- if hasKey $store "configMapName" -}}{{- $name = $store.configMapName -}}{{- end -}}
19+
{{- if not (kindIs "string" $name) -}}
20+
{{- fail (printf "truststores[%d]: source name must be a non-empty DNS subdomain" $i) -}}
21+
{{- end -}}
22+
{{- if or (gt (len $name) 253) (not (regexMatch "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$" $name)) -}}
23+
{{- fail (printf "truststores[%d]: source name must be a non-empty DNS subdomain" $i) -}}
24+
{{- end -}}
25+
{{- if hasKey $store "key" -}}
26+
{{- if not (kindIs "string" $store.key) -}}
27+
{{- fail (printf "truststores[%d]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'" $i) -}}
28+
{{- end -}}
29+
{{- if or (gt (len $store.key) 253) (not (regexMatch "^[A-Za-z0-9._-]+$" $store.key)) (eq $store.key ".") (hasPrefix ".." $store.key) -}}
30+
{{- fail (printf "truststores[%d]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'" $i) -}}
31+
{{- end -}}
32+
{{- end -}}
33+
{{- end -}}
34+
{{- end -}}

‎packages/system/keycloak/templates/sts.yaml‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
{{- regexReplaceAll "-+" (regexReplaceAll "[^a-z0-9-]" (. | lower) "-") "-" | trimPrefix "-" | trimSuffix "-" -}}
33
{{- end -}}
44

5+
{{- include "keycloak.truststores.validate" . -}}
6+
57
{{- $host := index .Values._cluster "root-host" }}
68
{{- $ingressHost := .Values.ingress.host | default (printf "keycloak.%s" $host) }}
79
{{- $clusterDomain := (index .Values._cluster "cluster-domain") | default "cozy.local" }}
@@ -213,10 +215,17 @@ spec:
213215
{{- with .Values.extraEnv }}
214216
{{- toYaml . | nindent 12 }}
215217
{{- end }}
216-
{{- if $themes }}
218+
{{- if or $themes .Values.truststores }}
217219
volumeMounts:
220+
{{- if $themes }}
218221
- name: themes
219222
mountPath: /opt/keycloak/themes
223+
{{- end }}
224+
{{- range $i, $_ := .Values.truststores }}
225+
- name: truststore-{{ $i }}
226+
mountPath: /opt/keycloak/conf/truststores/cozystack-{{ $i }}
227+
readOnly: true
228+
{{- end }}
220229
{{- end }}
221230
ports:
222231
- name: http
@@ -245,10 +254,25 @@ spec:
245254
periodSeconds: 10
246255
timeoutSeconds: 5
247256
failureThreshold: 3
248-
{{- if $themes }}
257+
{{- if or $themes .Values.truststores }}
249258
volumes:
259+
{{- if $themes }}
250260
- name: themes
251261
emptyDir:
252262
sizeLimit: 256Mi
263+
{{- end }}
264+
{{- range $i, $store := .Values.truststores }}
265+
- name: truststore-{{ $i }}
266+
{{- if hasKey $store "secretName" }}
267+
secret:
268+
secretName: {{ $store.secretName | quote }}
269+
{{- else }}
270+
configMap:
271+
name: {{ $store.configMapName | quote }}
272+
{{- end }}
273+
items:
274+
- key: {{ $store.key | default "ca.crt" | quote }}
275+
path: {{ $store.key | default "ca.crt" | quote }}
276+
{{- end }}
253277
{{- end }}
254278
terminationGracePeriodSeconds: 60
Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
suite: keycloak custom trust anchors
2+
release:
3+
name: keycloak
4+
namespace: cozy-keycloak
5+
templates:
6+
- templates/sts.yaml
7+
tests:
8+
- it: leaves the default pod without truststore volumes or mounts
9+
documentSelector:
10+
path: kind
11+
value: StatefulSet
12+
asserts:
13+
- notExists:
14+
path: spec.template.spec.volumes
15+
- notExists:
16+
path: spec.template.spec.containers[0].volumeMounts
17+
- notContains:
18+
path: spec.template.spec.containers[0].env
19+
content:
20+
name: KC_TRUSTSTORE_PATHS
21+
any: true
22+
23+
- it: mounts only the selected ConfigMap key read-only at a reserved subdirectory
24+
documentSelector:
25+
path: kind
26+
value: StatefulSet
27+
set:
28+
truststores:
29+
- configMapName: freeipa-ca
30+
asserts:
31+
- equal:
32+
path: spec.template.spec.volumes
33+
value:
34+
- name: truststore-0
35+
configMap:
36+
name: freeipa-ca
37+
items:
38+
- key: ca.crt
39+
path: ca.crt
40+
- equal:
41+
path: spec.template.spec.containers[0].volumeMounts
42+
value:
43+
- name: truststore-0
44+
mountPath: /opt/keycloak/conf/truststores/cozystack-0
45+
readOnly: true
46+
47+
- it: mounts a selected Secret key without changing its PKCS12 extension
48+
documentSelector:
49+
path: kind
50+
value: StatefulSet
51+
set:
52+
truststores:
53+
- secretName: partner-ca
54+
key: trust.p12
55+
asserts:
56+
- equal:
57+
path: spec.template.spec.volumes
58+
value:
59+
- name: truststore-0
60+
secret:
61+
secretName: partner-ca
62+
items:
63+
- key: trust.p12
64+
path: trust.p12
65+
- equal:
66+
path: spec.template.spec.containers[0].volumeMounts
67+
value:
68+
- name: truststore-0
69+
mountPath: /opt/keycloak/conf/truststores/cozystack-0
70+
readOnly: true
71+
72+
- it: keeps themes and multiple CA sources separate even with identical key names
73+
documentSelector:
74+
path: kind
75+
value: StatefulSet
76+
set:
77+
themes:
78+
- name: custom
79+
image: example.com/theme:1
80+
truststores:
81+
- configMapName: freeipa-ca
82+
- secretName: partner-ca
83+
asserts:
84+
- equal:
85+
path: spec.template.spec.volumes
86+
value:
87+
- name: themes
88+
emptyDir:
89+
sizeLimit: 256Mi
90+
- name: truststore-0
91+
configMap:
92+
name: freeipa-ca
93+
items:
94+
- key: ca.crt
95+
path: ca.crt
96+
- name: truststore-1
97+
secret:
98+
secretName: partner-ca
99+
items:
100+
- key: ca.crt
101+
path: ca.crt
102+
- equal:
103+
path: spec.template.spec.containers[0].volumeMounts
104+
value:
105+
- name: themes
106+
mountPath: /opt/keycloak/themes
107+
- name: truststore-0
108+
mountPath: /opt/keycloak/conf/truststores/cozystack-0
109+
readOnly: true
110+
- name: truststore-1
111+
mountPath: /opt/keycloak/conf/truststores/cozystack-1
112+
readOnly: true
113+
- equal:
114+
path: spec.template.spec.initContainers[0].volumeMounts
115+
value:
116+
- name: themes
117+
mountPath: /opt/keycloak/themes
118+
119+
- it: does not override explicitly configured truststore paths
120+
documentSelector:
121+
path: kind
122+
value: StatefulSet
123+
set:
124+
truststores:
125+
- configMapName: freeipa-ca
126+
extraEnv:
127+
- name: KC_TRUSTSTORE_PATHS
128+
value: /opt/additional-ca
129+
asserts:
130+
- contains:
131+
path: spec.template.spec.containers[0].env
132+
content:
133+
name: KC_TRUSTSTORE_PATHS
134+
value: /opt/additional-ca
135+
136+
- it: rejects a non-list truststores value
137+
set:
138+
truststores: invalid
139+
asserts:
140+
- failedTemplate:
141+
errorMessage: truststores must be a list
142+
143+
- it: rejects a non-object source
144+
set:
145+
truststores: [invalid]
146+
asserts:
147+
- failedTemplate:
148+
errorMessage: truststores[0] must be an object
149+
150+
- it: rejects an entry without a source
151+
set:
152+
truststores: [{}]
153+
asserts:
154+
- failedTemplate:
155+
errorMessage: truststores[0] must set exactly one of secretName or configMapName
156+
157+
- it: rejects ambiguous sources
158+
set:
159+
truststores:
160+
- configMapName: freeipa-ca
161+
secretName: partner-ca
162+
asserts:
163+
- failedTemplate:
164+
errorMessage: truststores[0] must set exactly one of secretName or configMapName
165+
166+
- it: rejects unknown fields instead of silently using the default key
167+
set:
168+
truststores:
169+
- configMapName: freeipa-ca
170+
keys: wrong
171+
asserts:
172+
- failedTemplate:
173+
errorMessage: 'truststores[0]: unknown field keys'
174+
175+
- it: rejects an empty source name
176+
set:
177+
truststores:
178+
- secretName: ""
179+
asserts:
180+
- failedTemplate:
181+
errorMessage: 'truststores[0]: source name must be a non-empty DNS subdomain'
182+
183+
- it: rejects a non-string source name
184+
set:
185+
truststores:
186+
- secretName: 123
187+
asserts:
188+
- failedTemplate:
189+
errorMessage: 'truststores[0]: source name must be a non-empty DNS subdomain'
190+
191+
- it: rejects an invalid source name
192+
set:
193+
truststores:
194+
- configMapName: Bad/Name
195+
asserts:
196+
- failedTemplate:
197+
errorMessage: 'truststores[0]: source name must be a non-empty DNS subdomain'
198+
199+
- it: rejects a non-string key
200+
set:
201+
truststores:
202+
- configMapName: freeipa-ca
203+
key: 123
204+
asserts:
205+
- failedTemplate:
206+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"
207+
208+
- it: rejects an empty key
209+
set:
210+
truststores:
211+
- configMapName: freeipa-ca
212+
key: ""
213+
asserts:
214+
- failedTemplate:
215+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"
216+
217+
- it: rejects path traversal
218+
set:
219+
truststores:
220+
- configMapName: freeipa-ca
221+
key: ../ca.crt
222+
asserts:
223+
- failedTemplate:
224+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"
225+
226+
- it: rejects AtomicWriter reserved names
227+
set:
228+
truststores:
229+
- configMapName: freeipa-ca
230+
key: ..data
231+
asserts:
232+
- failedTemplate:
233+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"
234+
235+
- it: accepts a source name and key of exactly 253 characters
236+
documentSelector:
237+
path: kind
238+
value: StatefulSet
239+
set:
240+
truststores:
241+
- configMapName: &maxSourceName aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
242+
key: &maxKey aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.crt
243+
asserts:
244+
- equal:
245+
path: spec.template.spec.volumes[0].configMap
246+
value:
247+
name: *maxSourceName
248+
items:
249+
- key: *maxKey
250+
path: *maxKey
251+
252+
- it: rejects a source name longer than 253 characters
253+
set:
254+
truststores:
255+
- secretName: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
256+
asserts:
257+
- failedTemplate:
258+
errorMessage: 'truststores[0]: source name must be a non-empty DNS subdomain'
259+
260+
- it: rejects a key longer than 253 characters
261+
set:
262+
truststores:
263+
- configMapName: freeipa-ca
264+
key: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.crt
265+
asserts:
266+
- failedTemplate:
267+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"
268+
269+
- it: rejects a single-dot key
270+
set:
271+
truststores:
272+
- configMapName: freeipa-ca
273+
key: "."
274+
asserts:
275+
- failedTemplate:
276+
errorMessage: "truststores[0]: key must contain 1-253 letters, digits, '.', '_' or '-' and cannot be '.' or start with '..'"

‎packages/system/keycloak/values.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,28 @@ extraEnv: []
102102
# name: my-secret
103103
# key: my-key
104104

105+
# Additional system trust anchors (LDAPS, external IdPs, SMTP).
106+
# Each entry selects one key from an existing Secret or ConfigMap in the
107+
# release namespace; key defaults to ca.crt. Supply only public certificates:
108+
# PEM bundles or unencrypted PKCS12 (.p12, .pfx, .pkcs12), without private keys.
109+
# Keycloak scans /opt/keycloak/conf/truststores recursively on startup;
110+
# its Java default roots and certificates baked into the image stay trusted.
111+
# The chart reserves the cozystack-* subdirectories there for these mounts.
112+
# These CAs apply to the whole Keycloak server, across all realms, so restrict
113+
# writes to the referenced objects to administrators who manage that trust.
114+
# They also verify incoming client certificates when https-client-auth is
115+
# request or required and no separate https-trust-store-file is configured.
116+
# Set that file explicitly if incoming mTLS needs a different trust boundary.
117+
# Changing an object's contents does not restart Keycloak: restart both pods
118+
# after rotation, or change the referenced object name to trigger a rollout.
119+
# Missing objects/keys prevent the pod from starting. Certificate
120+
# loading is handled by Keycloak, not Helm; no API read permissions are added.
121+
truststores: []
122+
# - configMapName: freeipa-ca
123+
# key: ca.crt
124+
# - secretName: partner-ca
125+
# key: certificates.pem
126+
105127
# Transparent column-level PII encryption for the Keycloak database.
106128
# When enabled, a keycloak-kms-proxy Deployment is placed on the wire
107129
# between Keycloak and its CloudNativePG database: Keycloak's DB endpoint

0 commit comments

Comments
 (0)