docs: gateway & self-signed certs

ericpaulsen · ericpaulsen · commit e7e53d4ddf4d · 2023-05-31T19:58:17.000Z
diff --git a/docs/ides/gateway.md b/docs/ides/gateway.md
@@ -74,3 +74,44 @@ explaining this IDE specification.
    ![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png)
 
 > Note the JetBrains IDE is remotely installed into `~/.cache/JetBrains/RemoteDev/dist`
+
+## Configuring Gateway to use self-signed certificates
+
+When attempting to connect to a Coder deployment that uses self-signed certificates,
+you may receive the following error in Gateway:
+
+```console
+Failed to configure connection to https://coder.internal.enterprise/: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
+```
+
+To resolve this issue, you will need to add Coder's certificate to the Java trust store
+present on your local machine. Here is the default location of the trust store for
+each OS:
+
+```console
+# Linux
+$JAVA_HOME/lib/security/cacerts
+/etc/pki/java/cacerts
+/etc/ssl/certs/java/cacerts
+
+# macOS
+$(/usr/libexec/java_home)/lib/security/cacerts
+$(/usr/libexec/java_home)/jre/lib/security/cacerts
+
+# Windows
+C:\Program Files (x86)\Java\jre<version>\lib\security\cacerts
+```
+
+To add the certificate to the keystore, you can use the `keytool` utility that ships
+with Java:
+
+```console
+keytool -import -alias coder -file <certificate> -keystore /path/to/trust/store
+```
+
+On Windows, you can use `keytool` that ships with the JetBrains Gateway installation.
+For example:
+
+```powershell
+& 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jbr/bin/keytool.exe' 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jbr/lib/security/cacerts' -import -alias coder -file <cert>
+```
