How to remote debug attach Keycloak in versions > 8

Question

I recently upgraded Keycloak to version 9, and when running in Docker, I'm having trouble attaching a remote debugger. I suspect this has to do with Keycloak's underlying upgrade to Java 9+.

The error I get is:

handshake failed - connection prematurally closed

I have my ports mapped correctly within Docker (I can run Keycloak version 7 and it attaches just fine).

Answer 1

The approach depends on whether you're using standalone.sh (or .bat presumably) or a docker image.

If you're using standalone.sh, you can use the --debug option, documented in standalone.sh -h:

standalone.sh --debug '*:8000'

(the * is to allow access from any host. Plain --debug 8000 will allow access only from localhost)

For docker images, this will be the documented approach from version 12 on, and it works at least from Keycloak 11.0.2:

$ git diff
diff --git a/docker-compose/keycloak-standalone/docker-compose.yml b/docker-compose/keycloak-standalone/docker-compose.yml
index fcf3a52..93b7209 100644
--- a/docker-compose/keycloak-standalone/docker-compose.yml
+++ b/docker-compose/keycloak-standalone/docker-compose.yml
@@ -11,11 +11,14 @@ services:
       environment:
         KEYCLOAK_USER: admin
         KEYCLOAK_PASSWORD: admin
+        DEBUG: "true"
+        DEBUG_PORT: "*:8000"
       ports:
         - 8080:8080
+        - 8000:8000
       volumes:
         - data:/opt/jboss/keycloak/standalone/data

(Again, the * is to allow access from any host.)

Answer 2

As it turns out, Java 9 introduced a security enhancement with respect to debugging. Information here: https://stackoverflow.com/a/60090750/2117355

In my Keycloak docker-compose service definition, I was able to add under environment:

DEBUG_PORT: "*:8787"

And that fixed the problem. I'm now able to debug.

Answer 3

For Keycloak version 7

I'm using this command to run the docker container to enable debugging at port 1234

docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin 
-e JAVA_OPTS="-server -Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m 
   -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman 
   -Djava.awt.headless=true 
   -agentlib:jdwp=transport=dt_socket,address=1234,server=y,suspend=n" 
-p 8080:8080 -p 1234:1234 jboss/keycloak:7.0.0 

Connecting it to the IntelliJ using Remote Configuration

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1234

*Note: The default value of the JAVA_OPTS is below so I prepended it with the above configuration

-server -Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m 
-Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman 
-Djava.awt.headless=true 

Answer 4

You can replace debug params by creating your own image, using Dockerfile

Dockerfile:

FROM jboss/keycloak:latest
ENV DEBUG true
ENV DEBUG_PORT *:8787
EXPOSE 8080 8443 9990 8787
ENTRYPOINT ${JBOSS_HOME}/../tools/docker-entrypoint.sh

console:

docker build -t local/debug-keycloack ..
docker run -p 8080:8080 -p 8443:8443 -p 9990:9990 -p 8787:8787 --name debug-keycloack local/debug-keycloack

Answer 5

This answer is not related to docker, just trying to help anyone who needs this

For keycloak 22.0.1, I use intellij to debug my custom SPI (which I put in /provider as a jar file), then start keycloak locally, and do remote debug.

1. Run kc.bat start-dev --http-relative-path=/auth --debuginsideC:\YourPath\keycloak-22.0.1\bin>, it will then show something like Listening for transport dt_socket at address: 63506
2. Open intellij, Ctrl+Alt+F5 to open attach to process (Or Run | Attach to Process), choose the address, for example 63506
3. Then you can do your remote debugging! Start by setting some breakpoints and open localhost:8080 and do your stuff