diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx index d0bc548..5d73a0e 100644 --- a/docs/v2/configuration/authentication.mdx +++ b/docs/v2/configuration/authentication.mdx @@ -338,6 +338,108 @@ authentication: If not specified, the default is `false`. +#### Self-Signed Certificates + +If your OIDC provider uses self-signed or internal CA certificates (common with self-hosted Keycloak, Dex, or corporate identity providers), Flipt will reject the TLS connection with an error like: + +```text +x509: certificate signed by unknown authority +``` + +The full error may also appear as `tls: failed to verify certificate: x509: certificate signed by unknown authority` depending on the log context. + +Flipt relies on the system trust store for TLS validation. To trust your internal CA, you need to add your CA certificate(s) to the container's trust store. + + + Unlike the [`kubernetes` auth + method](/v2/configuration/authentication#kubernetes), OIDC does not expose a + `ca_path` configuration option. You must add your CA certificate(s) to the + container's system trust store instead. + + +##### Dockerfile Example + +```dockerfile +FROM flipt/flipt:latest + +# Install CA certificates tooling +RUN apk add --no-cache ca-certificates + +# Copy your internal CA certificate(s) +COPY certs/Internal_Root_CA.crt /usr/local/share/ca-certificates/ +COPY certs/Internal_Intermediate_CA.crt /usr/local/share/ca-certificates/ + +# Update the system trust store +RUN update-ca-certificates +``` + +##### Kubernetes Example + +First, create a Secret containing your CA certificate: + +```bash +kubectl create secret generic internal-ca-certs \ + --from-file=ca.crt=/path/to/your/ca.crt +``` + +Then deploy Flipt with an init container that updates the trust store: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: flipt +spec: + replicas: 1 + selector: + matchLabels: + app: flipt + template: + metadata: + labels: + app: flipt + spec: + initContainers: + - name: update-ca-certs + image: alpine:latest + command: ["sh", "-c"] + args: + - | + apk add --no-cache ca-certificates && + cp /certs/*.crt /usr/local/share/ca-certificates/ && + update-ca-certificates && + cp -r /etc/ssl/certs/* /shared-certs/ + volumeMounts: + - name: ca-certs + mountPath: /certs + - name: shared-certs + mountPath: /shared-certs + containers: + - name: flipt + image: flipt/flipt:v2 + volumeMounts: + - name: shared-certs + mountPath: /etc/ssl/certs + readOnly: true + volumes: + - name: ca-certs + secret: + secretName: internal-ca-certs + - name: shared-certs + emptyDir: {} +``` + + +You can verify that the certificates are trusted by running: + +```bash +echo | openssl s_client -connect your-oidc-provider:443 2>&1 | grep "Verification" +``` + +You should see `Verification: OK` if the CA is properly trusted. + + + #### PKCE A good amount of OIDC providers support the PKCE (Proof Key for Code Exchange) flow and the implicit OAuth flow. Flipt allows for a configuration to enable PKCE for all the legs of the OIDC authentication flow.