docs(keycloak): document custom CA truststores and platform configuration #765

The Keycloak truststore section in content/en/docs/next/operations/oidc/self-signed-certificates.md currently says the Cozystack chart cannot mount additional CA files and instructs operators to add first-class chart support. This becomes stale when cozystack/cozystack#3823 is fixed by the truststores chart value.

Update the next guide when that support lands, and identify the first release that includes it (the feature is not available in existing stable releases). Keep released documentation unchanged unless the change is backported.

The chart accepts a list of references to existing objects in the Keycloak release namespace, selecting a single certificate key from each:

truststores:
  - configMapName: freeipa-ca
    key: ca.crt
  - secretName: partner-ca
    key: certificates.pem

Each entry must set exactly one of configMapName or secretName; key defaults to ca.crt. Keycloak loads the selected PEM bundle or unencrypted PKCS12 file from a read-only subdirectory of /opt/keycloak/conf/truststores on startup, preserving Java default roots and other certificates in the image. Supply public certificates only, with no private keys. Trust applies across all Keycloak realms, so restrict writes to the referenced objects accordingly.

Document rotation: updating the contents of an existing object does not roll the StatefulSet or reload the truststore; restart both Keycloak pods, or change the reference to a versioned object name to trigger a rollout. Keep strict hostname checks for LDAPS; importing a CA does not fix an LDAP server certificate that lacks the hostname used in the connection URL.

Platform Package configuration

cozystack/cozystack#5140 tracks exposing the same references through the administrator-owned platform Package as authentication.oidc.keycloakTruststores. When that platform forwarding lands, update this guide with the platform configuration path and also add the new key to the hand-written table in content/en/docs/next/operations/configuration/platform-package.md:

authentication:
  oidc:
    keycloakTruststores:
      - configMapName: organization-ca
        key: ca.crt
      - secretName: partner-ca
        key: certificates.pem

Document that platform values only forward references to existing Secrets and ConfigMaps in cozy-keycloak; they do not create CA objects. The chart's server-wide trust scope, public-certificate-only requirement, incoming-client-mTLS caveat, strict hostname verification, and restart-on-rotation behavior apply unchanged. When authentication.oidc.enabled is false, the value is ignored and no Keycloak Package is emitted; an existing Package and its rendered truststores remain on the cluster because it carries helm.sh/resource-policy: keep.

Update next documentation first. Released documentation should change only for an actual backport, and release-availability notes must distinguish the chart feature's first release from the later platform-forwarding release.