From 74327782e4815062a8e93f37733b27d2b4e630c1 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Mon, 23 Feb 2026 14:32:17 +0000
Subject: [PATCH 1/5] docs: add self-signed certificate guide for OIDC
 providers

Add documentation for trusting self-signed/internal CA certificates
when using OIDC with self-hosted identity providers (Keycloak, Dex, etc).

Includes:
- Dockerfile example with update-ca-certificates
- Kubernetes deployment example (init container + shared volume)
- Verification command

Closes flipt-io/flipt#5296
---
 docs/v2/configuration/authentication.mdx | 73 ++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx
index d0bc548..14ed8f0 100644
--- a/docs/v2/configuration/authentication.mdx
+++ b/docs/v2/configuration/authentication.mdx
@@ -338,6 +338,79 @@ 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:
+
+```
+tls: failed to verify certificate: x509: certificate signed by unknown authority
+```
+
+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.
+
+**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 (mount CA cert as a Secret):**
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: flipt
+spec:
+  template:
+    spec:
+      initContainers:
+        - name: update-ca-certs
+          image: flipt/flipt:latest
+          command: ["sh", "-c"]
+          args:
+            - |
+              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:latest
+          volumeMounts:
+            - name: shared-certs
+              mountPath: /etc/ssl/certs
+              readOnly: true
+      volumes:
+        - name: ca-certs
+          secret:
+            secretName: internal-ca-certs
+        - name: shared-certs
+          emptyDir: {}
+```
+
+<Tip>
+  You can verify that the certificates are trusted by running:
+  ```bash
+  echo | openssl s_client -brief -connect your-oidc-provider:443 -verify_hostname your-oidc-provider 2>&1 | grep Verification
+  ```
+  You should see `Verification: OK` if the CA is properly trusted.
+</Tip>
+
 #### 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.

From 67c34ee2bccd1723202cf10bb4baaecdcbfd0e65 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Mon, 23 Feb 2026 15:04:44 +0000
Subject: [PATCH 2/5] style: run prettier formatter

---
 docs/v2/configuration/authentication.mdx | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx
index 14ed8f0..3adaa74 100644
--- a/docs/v2/configuration/authentication.mdx
+++ b/docs/v2/configuration/authentication.mdx
@@ -404,11 +404,10 @@ spec:
 ```
 
 <Tip>
-  You can verify that the certificates are trusted by running:
-  ```bash
-  echo | openssl s_client -brief -connect your-oidc-provider:443 -verify_hostname your-oidc-provider 2>&1 | grep Verification
-  ```
-  You should see `Verification: OK` if the CA is properly trusted.
+  You can verify that the certificates are trusted by running: ```bash echo |
+  openssl s_client -brief -connect your-oidc-provider:443 -verify_hostname
+  your-oidc-provider 2>&1 | grep Verification ``` You should see `Verification:
+  OK` if the CA is properly trusted.
 </Tip>
 
 #### PKCE

From 7afebb46dd3685b4ca9a2cf0e36a6ee7e1040e09 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Fri, 27 Feb 2026 09:38:54 -0500
Subject: [PATCH 3/5] docs: address PR review feedback for OIDC self-signed
 certs guide

- Add language tag to error code block
- Use alpine image for init container (has apk available)
- Add apk install step in init container
- Add required K8s Deployment fields (replicas, selector, labels)
- Use proper subheadings instead of bold text
- Note both error message variants for searchability
- Fix malformed code block inside Tip component
- Remove -brief flag from openssl command for portability
- Add kubectl create secret snippet
- Add Note about OIDC lacking ca_path (cross-ref to K8s auth)

Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
---
 docs/v2/configuration/authentication.mdx | 44 +++++++++++++++++++-----
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx
index 3adaa74..519bea6 100644
--- a/docs/v2/configuration/authentication.mdx
+++ b/docs/v2/configuration/authentication.mdx
@@ -342,13 +342,19 @@ If not specified, the default is `false`.
 
 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
 ```
-tls: failed to verify certificate: 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.
 
-**Dockerfile example:**
+<Note>
+  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.
+</Note>
+
+##### Dockerfile Example
 
 ```dockerfile
 FROM flipt/flipt:latest
@@ -364,7 +370,16 @@ COPY certs/Internal_Intermediate_CA.crt /usr/local/share/ca-certificates/
 RUN update-ca-certificates
 ```
 
-**Kubernetes example (mount CA cert as a Secret):**
+##### 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
@@ -372,14 +387,22 @@ kind: Deployment
 metadata:
   name: flipt
 spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: flipt
   template:
+    metadata:
+      labels:
+        app: flipt
     spec:
       initContainers:
         - name: update-ca-certs
-          image: flipt/flipt:latest
+          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/
@@ -404,10 +427,13 @@ spec:
 ```
 
 <Tip>
-  You can verify that the certificates are trusted by running: ```bash echo |
-  openssl s_client -brief -connect your-oidc-provider:443 -verify_hostname
-  your-oidc-provider 2>&1 | grep Verification ``` You should see `Verification:
-  OK` if the CA is properly trusted.
+  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.
 </Tip>
 
 #### PKCE

From e77cf97b25621bc95225279b266fbd35c51ea3c6 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Fri, 27 Feb 2026 09:42:40 -0500
Subject: [PATCH 4/5] docs: fix prettier formatting issues

Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
---
 docs/v2/configuration/authentication.mdx | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx
index 519bea6..e086561 100644
--- a/docs/v2/configuration/authentication.mdx
+++ b/docs/v2/configuration/authentication.mdx
@@ -351,7 +351,10 @@ The full error may also appear as `tls: failed to verify certificate: x509: cert
 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.
 
 <Note>
-  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.
+  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.
 </Note>
 
 ##### Dockerfile Example
@@ -427,13 +430,14 @@ spec:
 ```
 
 <Tip>
-  You can verify that the certificates are trusted by running:
+You can verify that the certificates are trusted by running:
 
-  ```bash
-  echo | openssl s_client -connect your-oidc-provider:443 2>&1 | grep "Verification"
-  ```
+```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.
 
-  You should see `Verification: OK` if the CA is properly trusted.
 </Tip>
 
 #### PKCE

From eaae1956597324d569f7f19c1493eaf43438fd41 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Sat, 28 Feb 2026 08:42:26 -0500
Subject: [PATCH 5/5] chore: fix flipt image tag

Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
---
 docs/v2/configuration/authentication.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/v2/configuration/authentication.mdx b/docs/v2/configuration/authentication.mdx
index e086561..5d73a0e 100644
--- a/docs/v2/configuration/authentication.mdx
+++ b/docs/v2/configuration/authentication.mdx
@@ -416,7 +416,7 @@ spec:
               mountPath: /shared-certs
       containers:
         - name: flipt
-          image: flipt/flipt:latest
+          image: flipt/flipt:v2
           volumeMounts:
             - name: shared-certs
               mountPath: /etc/ssl/certs