Docs: Keycloak SSO Troubleshooting Updation (#22253)

Co-authored-by: “Rounak <“rounakpreet.d@deuexsolutions.com”>

openmetadata-docs/content/v1.7.x/deployment/security/keycloak/troubleshooting.md

@@ -0,0 +1,38 @@
+---
+title: Fix PKI Not Found When Using Keycloak with Custom PKI
+description: Learn how to resolve PKI not found errors in OpenMetadata when using Keycloak behind Nginx with custom PKI by importing CA certificates into the truststore.
+slug: /deployment/security/keycloak/troubleshooting
+collate: false
+---
+
+# FAQ: Security with Keycloak
+
+## How to resolve "PKI not found" error when connecting to Keycloak behind Nginx with a custom PKI?
+
+If you're using Keycloak behind an Nginx reverse proxy with a custom Public Key Infrastructure (PKI), OpenMetadata may fail to authenticate due to missing trusted certificates. This results in a **"PKI not found"** or TLS validation error.
+
+### Resolution
+
+To allow OpenMetadata to trust your custom CA:
+
+1. **Extend the OpenMetadata Docker image** and import your custom CA certificate into the Java truststore.
+2. Use the following command (replace paths accordingly):
+
+```bash
+   keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts \
+     -storepass changeit -noprompt -alias my-custom-ca \
+     -file /path/to/your/custom-ca.crt
+```
+
+3. Alternatively, if you're using Helm, you can update your deployment by modifying the container image or using an initContainer to patch the truststore and setting:
+
+```bash
+OPENMETADATA_OPTS="-Djavax.net.ssl.trustStore=/path/to/keystore.jks \
+-Djavax.net.ssl.trustStorePassword=changeit"
+```
+
+For guidance on extending the Docker image, refer to the official documentation:
+
+[Extending OpenMetadata Docker Image (GKE Example)](/deployment/kubernetes/gke#extending-openmetadata-server-docker-image)
+
+This enables OpenMetadata to establish a secure connection with Keycloak behind your Nginx reverse proxy using a custom certificate authority.

openmetadata-docs/content/v1.7.x/menu.md

@@ -144,6 +144,8 @@ site_menu:
     url: /deployment/security/keycloak/bare-metal
   - category: Deployment / Enable Security / Keycloak SSO / Kubernetes
     url: /deployment/security/keycloak/kubernetes
+  - category: Deployment / Enable Security / Keycloak SSO / Troubleshooting
+    url: /deployment/security/keycloak/troubleshooting
   - category: Deployment / Enable Security / Saml
     url: /deployment/security/saml
   - category: Deployment / Enable Security / Saml / AWS

openmetadata-docs/content/v1.8.x/deployment/security/keycloak/troubleshooting.md

@@ -0,0 +1,38 @@
+---
+title: Fix PKI Not Found When Using Keycloak with Custom PKI
+description: Learn how to resolve PKI not found errors in OpenMetadata when using Keycloak behind Nginx with custom PKI by importing CA certificates into the truststore.
+slug: /deployment/security/keycloak/troubleshooting
+collate: false
+---
+
+# FAQ: Security with Keycloak
+
+## How to resolve "PKI not found" error when connecting to Keycloak behind Nginx with a custom PKI?
+
+If you're using Keycloak behind an Nginx reverse proxy with a custom Public Key Infrastructure (PKI), OpenMetadata may fail to authenticate due to missing trusted certificates. This results in a **"PKI not found"** or TLS validation error.
+
+### Resolution
+
+To allow OpenMetadata to trust your custom CA:
+
+1. **Extend the OpenMetadata Docker image** and import your custom CA certificate into the Java truststore.
+2. Use the following command (replace paths accordingly):
+
+```bash
+   keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts \
+     -storepass changeit -noprompt -alias my-custom-ca \
+     -file /path/to/your/custom-ca.crt
+```
+
+3. Alternatively, if you're using Helm, you can update your deployment by modifying the container image or using an initContainer to patch the truststore and setting:
+
+```bash
+OPENMETADATA_OPTS="-Djavax.net.ssl.trustStore=/path/to/keystore.jks \
+-Djavax.net.ssl.trustStorePassword=changeit"
+```
+
+For guidance on extending the Docker image, refer to the official documentation:
+
+[Extending OpenMetadata Docker Image (GKE Example)](/deployment/kubernetes/gke#extending-openmetadata-server-docker-image)
+
+This enables OpenMetadata to establish a secure connection with Keycloak behind your Nginx reverse proxy using a custom certificate authority.

openmetadata-docs/content/v1.8.x/menu.md

@@ -150,6 +150,8 @@ site_menu:
     url: /deployment/security/keycloak/bare-metal
   - category: Deployment / Enable Security / Keycloak SSO / Kubernetes
     url: /deployment/security/keycloak/kubernetes
+  - category: Deployment / Enable Security / Keycloak SSO / Troubleshooting
+    url: /deployment/security/keycloak/troubleshooting
   - category: Deployment / Enable Security / Saml
     url: /deployment/security/saml
   - category: Deployment / Enable Security / Saml / AWS

openmetadata-docs/content/v1.9.x-SNAPSHOT/deployment/security/keycloak/troubleshooting.md

@@ -0,0 +1,38 @@
+---
+title: Fix PKI Not Found When Using Keycloak with Custom PKI
+description: Learn how to resolve PKI not found errors in OpenMetadata when using Keycloak behind Nginx with custom PKI by importing CA certificates into the truststore.
+slug: /deployment/security/keycloak/troubleshooting
+collate: false
+---
+
+# FAQ: Security with Keycloak
+
+## How to resolve "PKI not found" error when connecting to Keycloak behind Nginx with a custom PKI?
+
+If you're using Keycloak behind an Nginx reverse proxy with a custom Public Key Infrastructure (PKI), OpenMetadata may fail to authenticate due to missing trusted certificates. This results in a **"PKI not found"** or TLS validation error.
+
+### Resolution
+
+To allow OpenMetadata to trust your custom CA:
+
+1. **Extend the OpenMetadata Docker image** and import your custom CA certificate into the Java truststore.
+2. Use the following command (replace paths accordingly):
+
+```bash
+   keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts \
+     -storepass changeit -noprompt -alias my-custom-ca \
+     -file /path/to/your/custom-ca.crt
+```
+
+3. Alternatively, if you're using Helm, you can update your deployment by modifying the container image or using an initContainer to patch the truststore and setting:
+
+```bash
+OPENMETADATA_OPTS="-Djavax.net.ssl.trustStore=/path/to/keystore.jks \
+-Djavax.net.ssl.trustStorePassword=changeit"
+```
+
+For guidance on extending the Docker image, refer to the official documentation:
+
+[Extending OpenMetadata Docker Image (GKE Example)](/deployment/kubernetes/gke#extending-openmetadata-server-docker-image)
+
+This enables OpenMetadata to establish a secure connection with Keycloak behind your Nginx reverse proxy using a custom certificate authority.

openmetadata-docs/content/v1.9.x-SNAPSHOT/menu.md

@@ -150,6 +150,8 @@ site_menu:
     url: /deployment/security/keycloak/bare-metal
   - category: Deployment / Enable Security / Keycloak SSO / Kubernetes
     url: /deployment/security/keycloak/kubernetes
+  - category: Deployment / Enable Security / Keycloak SSO / Troubleshooting
+    url: /deployment/security/keycloak/troubleshooting
   - category: Deployment / Enable Security / Saml
     url: /deployment/security/saml
   - category: Deployment / Enable Security / Saml / AWS