In this section is presented how to using eclipse to debug Keycloak SPI code. The example used is the eventListener described in a previous article.
- You need to have eclipse installed
- You need to have compiled the keycloak source distribution (cf before) containing the examples.
You first need to create a dummy empty eclipse projet in a nutshell.
To do this,
- Lauch eclipse
- select File Tab
- select switch
- select other
- specify a new workspace name (here keycloak-4.6.debug)
- click launch
You need to import in eclipse the keycloak example sources
- From the file tab, select import
- select existing maven projects, click next
- Enter the root directory of keycloak examples
- and click finish
On the screenshot below, we are using eclipse to browse SysoutEventListenerProvider.java
In order to bind eclipse debugger to keycloak, keycloak needs to be launched in debug mode.
Keycloak by itself is already geared to be launched in debug mode without any tweaking.
This can be done straightforward using the standalone.sh command with debug option
Usage: standalone.sh [args...] where args include: ………. --debug [<port>] Activate debug mode with an optional argument to specify the port. Only works if the launch script supports it.
On our example, keycloak server is launched with debug port 8100
sh standalone.sh --debug 8100 ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: /home/orivat/keycloak_latest/keycloak-4.6.0.Final JAVA: /home/orivat/dev/jdk1.8.0_101/bin/java 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=8100,server=y,suspend=n ========================================================================= Listening for transport dt_socket at address: 8100 18:11:34,454 INFO [org.jboss.modules] (main) JBoss Modules version 1.8.6.Final ……..
Interestingly enough, it is worth noticing keycloak trace displaying that has been launched in debug mode as remote server
-agentlib:jdwp=transport=dt_socket,address=8100,server=y,suspend=n Listening for transport dt_socket at address: 8100
The goal of this section is to showcase how it is possible to attach eclipse to keycloak server running in debug mode.
Under Eclipse, do the following
- Go to the run tab
- Select Debug Configurations
Filling Debug configuration information
On the panel left hand side:
- Select Remote Java application
(This allow to open the menu to connect to the remote machine which is the target to debug).
On the debug Remote – right hand side
Go to connection Properties (bottom right hand side)
- Connect Tab
- enter the remote port number (8100 here)
- enter FQDN of the host (localhost here)
- Source Tab
- Select the source path(It is the path of where the keycloak examples sources are located)
- Add a Name to the debug selection
- Click on the debug button
Your debugger is now connected to Keycloak example
Triggering breakpoint in EventListener SPI
Go to the realm demo
- Select the URL https://localhost:8080/auth/realms/demo/account in a new tab.(if the realm demo does not exist, you need to create it. Also populate with user and password- user1/password for example).
- Enter Credentials:
(You will need to enter credentials user1/password as specified in previous chapter)
- When you click, you will be redirected to the Eclipse browser debugging page within the SysoutEventListenerProvider page code.
You can now debug your SPI
You can now debug the SPI with eclipse, set breakpoints ….