Using Eclipse to debug Keycloak SPIs

par | Nov 21, 2018 | SSO

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.

Requirements
  • You need to have eclipse installed
  • You need to have compiled the keycloak source distribution (cf before) containing the examples.
Creating a new eclipse debugging workspace

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

Using Eclipse to debug Keycloak SPIs
Now your keycloak-4.6.debug workspace is created.

Importing keycloak examples maven project

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

Debug Keycloak SPIs-2
At the end, you can now browser keycloak examples sources within eclipse

On the screenshot below, we are using eclipse to browse SysoutEventListenerProvider.java

Debug Keycloak SPIs-3

Launching keycloak server in debug mode

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.

 

Example:

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

 

 

Attaching Eclipse Debugger to Keycloak

The goal of this section is to showcase how it is possible to attach eclipse to keycloak server running in debug mode.

Setting the Eclipse Debug configuration

Under Eclipse, do the following

  • Go to the run tab
  • Select Debug Configurations

Debug Keycloak SPIs-4

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)

Debug Keycloak SPIs-5

  • Source Tab
    • Select the source path(It is the path of where the keycloak examples sources are located)

Debug Keycloak SPIs-6

Debug Connexion
  • Add a Name to the debug selection
    (debug_latest here)
  • Click on the debug button

Debug Keycloak SPIs-7

Your debugger is now connected to Keycloak example

Debugging example
Set a breakpoint

In the following the breakpoint is set on the method onEvent of the SysoutEventListenerProvider

Debug Keycloak SPIs-8

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:

Debug Keycloak SPIs-9

(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

Debug Keycloak SPIs-10

You can now debug the SPI with eclipse, set breakpoints ….

janua
Les derniers articles par janua (tout voir)