1. Janua – SARL au capital de 30 000 € - 8 Chemin du bas Lauron – 06 650 Le Rouret
Tél. 0 950 260 370 – Fax. 0 955 260 370
Siret : 478 075 369 00015 - http://www.janua.fr
Page 4 / 159
Table of contents
1 Prerequisites.............................................................................................................................................9
1.1 Hardware requirements.......................................................................................................................9
1.2 Software requirements ........................................................................................................................9
1.3 Tools....................................................................................................................................................9
1.4 Keycloak documentation ...................................................................................................................10
1.5 Keycloak code sources .....................................................................................................................11
2 Using Keycloak SPI – add a custom Event Listener module .................................................................12
2.1 Presentation ......................................................................................................................................12
2.2 Prerequisites .....................................................................................................................................12
2.3 Deploy event listener module............................................................................................................12
2.4 Configure Event Listener in Keycloak ...............................................................................................13
2.5 Test....................................................................................................................................................14
2.6 Save events in DB.............................................................................................................................14
2.7 A look at the code..............................................................................................................................16
3 Use Eclipse/IntelliJ to debug Keycloak SPIs..........................................................................................18
3.1 Presentation ......................................................................................................................................18
3.2 Prerequisites .....................................................................................................................................18
3.3 Launch Keycloak server in debug mode...........................................................................................18
3.4 Debug with Eclipse............................................................................................................................18
3.4.1 Import keycloak-quickstarts project in Eclipse..........................................................................18
3.4.2 Attach Eclipse Debugger to Keycloak ......................................................................................20
3.4.3 Set a breakpoint........................................................................................................................21
3.4.4 Trigger breakpoint in EventListener SPI...................................................................................21
3.5 Debug with IntelliJ .............................................................................................................................22
3.5.1 Import keycloak-quickstarts project in IntelliJ ...........................................................................22
3.5.2 Attach IntelliJ Debugger to Keycloak........................................................................................23
3.5.3 Set a breakpoint........................................................................................................................24
3.5.4 Trigger breakpoint in EventListener SPI...................................................................................24
4 Keycloak logger......................................................................................................................................26
4.1 Presentation ......................................................................................................................................26
4.2 Adjust the log dynamically.................................................................................................................26
4.2.1 Read the current root-logger value...........................................................................................26
4.2.2 Update the root-logger value ....................................................................................................26
5 Keycloak Multifactor authentication (MFA) using OTP...........................................................................28
5.1 Presentation ......................................................................................................................................28
5.2 Prerequisites .....................................................................................................................................28
5.3 Create demo_otp realm.....................................................................................................................28
5.4 Modify demo_otp Authentication Workflow.......................................................................................28
5.5 Authentication of a user for the 1
st
time.............................................................................................29
5.6 Authentication of a user (after 1
st
time) .............................................................................................30
5.7 Keycloak OTP ...................................................................................................................................32
6 MFA with Keycloak.................................................................................................................................33
6.1 Presentation ......................................................................................................................................33
6.2 Keycloak OTP MFA versus SMS-OTP..............................................................................................33
6.3 LOA concepts and MFA usage .........................................................................................................33
6.4 Keycloak Authentication flow and MFA.............................................................................................33
6.4.1 Keycloak 3.4.3 ..........................................................................................................................33
6.4.2 Keycloak 4.6 .............................................................................................................................34

2. Janua – SARL au capital de 30 000 € - 8 Chemin du bas Lauron – 06 650 Le Rouret
Tél. 0 950 260 370 – Fax. 0 955 260 370
Siret : 478 075 369 00015 - http://www.janua.fr
Page 5 / 159
6.4.3 Upcoming releases – Jira tickets..............................................................................................34
6.5 Keycloak MFA synthesis ...................................................................................................................34
7 Multi tenancy with Keycloak ...................................................................................................................36
7.1 Keycloak quickstart multi tenancy example ......................................................................................36
7.1.1 Prerequisites.............................................................................................................................36
7.1.2 Create 2 realms on Keycloak....................................................................................................36
7.1.3 Deploy the multi-tenant app on WildFly....................................................................................37
7.1.4 Test...........................................................................................................................................38
8 Map LDAP Group to Keycloak Roles .....................................................................................................40
8.1 Presentation ......................................................................................................................................40
8.2 LDAP Group to Keycloak roles mapping workflow ...........................................................................40
8.3 Prerequisites .....................................................................................................................................40
8.4 Examine LDAP example using JXplorer ...........................................................................................40
8.5 Configure ldap user federation in Keycloak ......................................................................................42
8.5.1 Define LDAP synchronisation...................................................................................................42
8.6 Add group ldap mapper.....................................................................................................................43
8.6.1 Create ldap group mapping ......................................................................................................43
8.6.2 Synchronize ldap group mapping .............................................................................................44
8.7 Add SSO Role to Keycloak group .....................................................................................................45
8.8 Test....................................................................................................................................................45
8.8.1 Create a new ldap user.............................................................................................................45
8.8.2 Ldap-user part part of ldap-admin group ..................................................................................46
8.8.3 Keycloak ldap synchronization .................................................................................................46
8.8.4 New user with Keycloak role admin rights................................................................................47
8.9 Log to the admin console with a new admin user .............................................................................47
9 Use Client Scope in Keycloak ................................................................................................................49
9.1 Presentation ......................................................................................................................................49
9.2 Scope and claims Openid Core definition.........................................................................................49
9.3 Using Scope and Claims...................................................................................................................50
9.4 Prerequisites .....................................................................................................................................50
9.5 Accessing the access token using direct grant .................................................................................50
9.6 Get access token using ROPC workflow ..........................................................................................51
9.7 Add user federation mapper for mobile number ...............................................................................52
9.8 Create a new scope to expose mobileNumber claim........................................................................54
9.8.1 Create mobileNumber scope within ldap-demo realm..............................................................54
9.8.2 Create a mapper of mobileNumber scope................................................................................55
9.8.3 Add new scope mobileNumber to optional client scopes .........................................................58
9.9 Use the new scope mobileNumber ...................................................................................................58
9.10 Use Keycloak Generator to evaluate scope .................................................................................60
10 Understand client authenticator security ................................................................................................62
10.1 client_id/client_secret security issue ............................................................................................62
10.2 Using other Keycloak client authenticator ....................................................................................62
10.3 Using Signed JWT client authenticator.........................................................................................62
10.4 JWKS_URI....................................................................................................................................63
11 Understanding Token usage ..................................................................................................................64
11.1 Token Lifecycle.............................................................................................................................64
11.2 Understand Keycloak session ......................................................................................................65
11.2.1 Session creation ...................................................................................................................65
11.2.2 Session usage ......................................................................................................................65
11.2.3 Session termination ..............................................................................................................65
11.2.4 Importance of session control – Potential security vulnerability...........................................66

3. Janua – SARL au capital de 30 000 € - 8 Chemin du bas Lauron – 06 650 Le Rouret
Tél. 0 950 260 370 – Fax. 0 955 260 370
Siret : 478 075 369 00015 - http://www.janua.fr
Page 6 / 159
11.3 Keycloak Access Token................................................................................................................66
11.4 Offline session and offline token...................................................................................................67
11.4.1 Offline token introduction ......................................................................................................67
11.4.2 Offline session main features ...............................................................................................68
11.4.3 Offline token main features...................................................................................................68
11.4.4 Revoke refresh token flag.....................................................................................................69
11.4.5 Offline Session Max Limited .................................................................................................69
11.4.6 Revoke offline token .............................................................................................................69
12 Examples of Offline token usage............................................................................................................71
12.1 Prerequisites.................................................................................................................................71
12.2 Offline Token through direct access grant flow ............................................................................71
12.2.1 Add offline-access role to the user .......................................................................................71
12.2.2 Adjust token lifespan.............................................................................................................71
12.2.3 Set the maximum invokation of refresh token ......................................................................72
12.2.4 Get an offline token...............................................................................................................73
12.3 Revoke the offline token ...............................................................................................................74
12.3.1 Revoke the offline token through the admin UI ....................................................................75
12.3.2 Revoke the offline token through the user self service panel...............................................75
12.4 Impact of offline_access scope.....................................................................................................75
12.4.1 Request without offline_access scope .................................................................................75
12.4.2 Request with offline_access scope.......................................................................................76
12.5 Offline token through authorization code flow ..............................................................................77
12.5.1 Prerequisites.........................................................................................................................77
12.5.2 Build and deploy offline-access-app webapp .......................................................................77
12.6 Offline-access-portal application test............................................................................................79
12.6.1 Use Kcadm to monitor the offline sessions ..........................................................................87
12.7 Synthesis / Best practices with offline tokens...............................................................................88
13 Understanding Keycloak user Federation ..............................................................................................89
13.1 Overview.......................................................................................................................................89
13.2 User Federation storage Provider.................................................................................................89
13.3 Keycloak default local userstorage (SQL database) ....................................................................89
13.3.1 Synchronize LDAP users to keycloak...................................................................................89
13.3.2 Synchronize newly created Keycloak users to LDAP..........................................................90
13.3.3 Deal with Keycloak – LDAP synchronization parameter ......................................................90
13.4 Use Keycloak user Federation SPI...............................................................................................91
13.5 Using Keycloak Provider interfaces..............................................................................................91
13.6 User storage simple providers......................................................................................................91
13.6.1 Prerequisites.........................................................................................................................92
13.6.2 Deploy user-storage-sample providers.................................................................................92
13.6.3 Enable the “readonly-property-file” provider for the Master realm........................................93
13.6.4 Test the “readonly-property-file” provider .............................................................................93
13.6.5 Enable the “writeable-property-file” provider for the Master realm .......................................94
13.6.6 Test the “writeable-property-file” provider.............................................................................95
13.6.7 Display all the users..............................................................................................................95
13.7 User storage JPA provider............................................................................................................96
13.7.1 Presentation..........................................................................................................................96
13.7.2 Prerequisites.........................................................................................................................96
13.7.3 Deploy the datasource..........................................................................................................96
13.7.4 Check XA data source with Keycloak console management ...............................................98
13.7.5 Deploy user-storage-jpa provider .........................................................................................98
13.7.6 Using JPA .............................................................................................................................99

4. Janua – SARL au capital de 30 000 € - 8 Chemin du bas Lauron – 06 650 Le Rouret
Tél. 0 950 260 370 – Fax. 0 955 260 370
Siret : 478 075 369 00015 - http://www.janua.fr
Page 7 / 159
13.7.7 Enable the “user-storage-jpa” provider for the Master realm ...............................................99
13.7.8 Display all the users............................................................................................................100
13.7.9 Test the “user-storage-jpa” provider ...................................................................................100
14 Understanding Keycloak Authentication ..............................................................................................102
14.1 Presentation................................................................................................................................102
14.2 Authentication Flow ....................................................................................................................103
14.2.1 Built-in browser authentication flow ....................................................................................104
14.2.2 Direct Authentication Grant flow .........................................................................................106
14.2.3 Registration Flow ................................................................................................................106
14.2.4 Reset Credentials ...............................................................................................................106
14.2.5 First Broker Login Flow.......................................................................................................107
14.2.6 Client authentication flow....................................................................................................108
14.3 Required Actions ........................................................................................................................108
14.4 Customize authenticator flow......................................................................................................110
14.4.1 Prerequisites.......................................................................................................................110
14.4.2 Build and deploy the customized authenticator flow ..........................................................110
14.4.3 Configure the custom authentication flow in Keycloak .......................................................112
14.4.4 Test.....................................................................................................................................115
15 Using apache2 mod_auth_openidc module with Keycloak (OpenID Connect) ...................................117
15.1 Presentation................................................................................................................................117
15.2 openID protocol recap ................................................................................................................117
15.3 Putting mod_auth_openidc in place ...........................................................................................118
15.4 Enabling mod_auth_openidc module with apache2...................................................................118
15.4.1 Getting hold of the library....................................................................................................118
15.4.2 Configuring keycloak Server for mod_auth_openidc.........................................................119
15.5 Configuration of mod_auth_openidc module..............................................................................120
15.6 Example......................................................................................................................................121
15.7 Using the hook mod_auth_openidc ............................................................................................122
15.8 Keycloak and NGINX..................................................................................................................122
16 Using UMA and Keycloak..............................................................................................................123
16.1 Presentation – What is UMA ?.............................................................................................123
16.2 Pointers.......................................................................................................................................123
16.3 UMA Key stakeholders.........................................................................................................123
16.4 UMA workflow..........................................................................................................................123
16.5 UMA typical use case.........................................................................................................124
16.6 Illustration of a RPT token (Request Party Token)..........................................126
16.7 Illustration of a resource (Keycloak)....................................................................127
16.8 Using permission .................................................................................................................128
16.9 Request approval or revokation...................................................................................128
16.10 UMA with Keycloak – Improve application productivity...................................129
17 UMA photoz keycloak example...................................................................................................130
17.1 Presentation..........................................................................................................................130
17.2 Deploying uma photoz example .......................................................................................130
17.2.1 Starting keycloak .......................................................................................................130
17.2.2 Starting wildfly .........................................................................................................130
17.2.3 Deploy app-authz-uma-photoz example.......................................................................130
17.2.4 Uploading uma-photoz config file.......................................................................131
17.3 Presentation of uma_photoz application .................................................................131
17.3.1 Uma_photoz architecture ..........................................................................................131
17.3.2 Uma_photoz actions.....................................................................................................132

5. Janua – SARL au capital de 30 000 € - 8 Chemin du bas Lauron – 06 650 Le Rouret
Tél. 0 950 260 370 – Fax. 0 955 260 370
Siret : 478 075 369 00015 - http://www.janua.fr
Page 8 / 159
17.3.3 Uma_photoz policy .......................................................................................................132
17.4 Photoz-restful-api application...................................................................................132
17.4.1 Photoz-restful-api settings .................................................................................132
17.4.2 Photoz-restful-api Resources ...............................................................................133
17.4.3 Authorization scopes.................................................................................................135
17.4.4 Policies...........................................................................................................................136
17.4.5 Permission ......................................................................................................................138
Scope base permission ................................................................................................................138
17.5 UMA-Photoz Lifecycle.........................................................................................................139
17.5.1 after login ....................................................................................................................139
17.5.2 listing resource created........................................................................................139
17.5.3 Sharing Resource .........................................................................................................140
17.5.4 Listing Resources of Alice....................................................................................140
17.5.5 Logging as Jdoe ...........................................................................................................141
17.6 Request Approbation Lifecycle.....................................................................................142
17.6.1 Pending approval request........................................................................................142
17.6.2 Request revokation...................................................................................................142
18 Accessing UMA through REST API.............................................................................................143
18.1 Presentation..........................................................................................................................143
18.2 Scenarios.................................................................................................................................143
18.3 scripts used..........................................................................................................................144
18.3.1 access_token..................................................................................................................144
18.3.2 UMA ticket request.....................................................................................................144
18.3.3 RPT token request (no persistence permission) ..........................................144
18.3.4 RPT token request (persisting permission)...................................................144
18.3.5 UMA access using RPT.................................................................................................144
18.4 Scenario1.................................................................................................................................145
18.4.1 Reminder of (1) alice has created an album alice3 ...............................145
18.4.2 (6) Jdoe can access to the resourcethe scenario1....................................145
18.4.3 Step 1 – creation of Album alice1 ....................................................................145
18.4.4 Step2 creation of an RPT for Alice ..................................................................145
18.5 Scenario2.................................................................................................................................149
18.5.1 Reminder...........................................................................................................................149
18.5.2.................................................................................................................................................149
18.6 Listing all the resources..............................................................................................154
18.6.1 Resource_set endpoint ..............................................................................................154
18.6.2 PAT token (Protected access token) ..................................................................154
18.6.3 Listing all the resources......................................................................................154
18.6.4 Listing/zooming a particular resource............................................................155
18.6.5 Creation of a new resources .................................................................................155
18.7 Using permissions ...............................................................................................................156
18.7.1 step 1 - Jdoe trying to access A4 (403 - access unauthorized) .......156
18.7.2 A4 - Jdoe pending approval (alice action)...................................................156
18.7.3 Approving a pending request using REST API.................................................157
18.7.4 Revoking access to a resource.............................................................................158
18.7.5 Listing all permissions ..........................................................................................158
18.8 Pointers...................................................................................................................................159