OIDC controller settings

auth.oidc.enabled enables generic OpenID Connect sign-in for the API. It requires the single-controller external sign-in profile and a recovery account. Use Enable OIDC sign-in for setup.

OCC_AUTH_OIDC_ENROLLMENT (Helm auth.oidc.enrollment) accepts the JSON OIDC enrollment policy. The installation profile uses controlPlane.oidc.enrollment. Absence requires explicit identity attachment and disables automatic account creation.

With auth.oidc.enabled, the chart adds the API-only egress policy openclaw-enterprise-api-oidc-login-egress on TCP 443. Empty auth.oidc.egressCidrs allows any address except link-local 169.254.0.0/16. The port is the destination Pod's port; an IdP inside the cluster on another target port needs its own egress policy. Rendering rejects invalid endpoint settings, a Secret shared with Google or another chart credential Secret, or an HTTP base URL. OIDC supports native Agent access.

auth.oidc.caSecretName and auth.oidc.caSecretKey optionally select a public PEM CA bundle from a Secret in the release namespace. Both default to empty; set both or neither, and only while OIDC is enabled. The CA Secret must not be a credential Secret the chart reads or database.caSecretName; it may share a public trust bundle Secret with gatewayRouting.caSecretName or repositoryCredentials.publicCaSecretName. Helm rejects invalid names, keys, shared credential Secrets and partial configuration. Required Secret projection and the assemble-api-ca init container gate API startup. Each input must contain only parseable PEM CA certificates, at most 1 MiB, without private keys or leaf certificates. This also applies to a selected Gateway CA bundle when OIDC CA trust is configured.

This opt-in also requires a separately selected database.caSecretName, distinct from the IdP CA Secret. The application URL must name the database by DNS hostname and use sslmode=verify-full and sslrootcert=<database.caMountPath>/<database.caKey>; mounting the Secret alone is insufficient. IP literal and Unix socket hosts are refused: the PostgreSQL client sends no TLS server name for an IP host, so Node would check the certificate against localhost instead of the address. Preserve the database's approved roots in that certificate-only PEM bundle (at most 1 MiB), including public roots if needed. Do not add IdP roots unless they were independently approved for the database.

Before loading the server, the API checks its actual OCC_DATABASE_URL with the installed PostgreSQL client parser and refuses absent, unreadable, empty or invalid CA material, ineffective TLS settings, IP or socket hosts (including a host parameter), duplicate URL parameters and nested connection strings. Errors omit the URL and credentials. Password and workload-identity pools retain this explicit CA; database TLS does not inherit the added IdP roots or Node's default roots. This checks local configuration at each API process start, not database reachability. Change database CA material only during stopped maintenance, then replace the Pod.

The init container combines the IdP bundle with the Gateway CA, when selected, in a memory volume with a 4 MiB size limit. The API reads it through NODE_EXTRA_CA_CERTS, extending Node's public roots process-wide for API clients using default trust, including token/JWKS requests. Clients with an explicit CA store keep that store. IdP roots are not added to workers, Jobs or Agents: the chart also sets OCC_GATEWAY_CA_PATH to the Gateway-only bundle (empty without one), and Harness node enrollment reads that instead of the combined bundle. An external Gateway issuer without a custom CA contributes no extra roots. With no OIDC CA values, existing chart trust wiring is unchanged. TLS verification and OIDC URL restrictions are unchanged.

Secret name/key changes replace the API Pod. Secret content changes require explicit API Pod replacement, including changes to a combined Gateway CA: assembly and Node trust loading happen at startup, without hot reload. Restarting only the API container keeps the init snapshot. The single API replica is interrupted during replacement. See private CA setup and rotation.