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.
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

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 command with debug option



On our example, keycloak server is launched with debug port 8100


Interestingly enough, it is worth noticing keycloak trace displaying that has been launched in debug mode as remote server



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

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 ….

Olivier Rivat

Senior Software Engineer with over 25 years of experience doing Software Development, Support and Consulting in Identity and Access Management Solutions.
Specialised in IAM (security, access control, identity management) and Open Source integration, settled in 2004 by IAM industry veteran, JANUA offers high value-added products and services to businesses and governements with a concern for Identity Management and Open Source components.
JANUA provides better security, build relationships, and enable new cloud, mobile, and IoT offerings from any device or connected thing.
Olivier Rivat

Les derniers articles par Olivier Rivat (tout voir)