2. Table des matières
1 History.............................................................................................................................................9
2 Prerequisites..................................................................................................................................10
2.1 Presentation................................................................................................................................10
2.2 Cloning Rh-SSO quickstart examples........................................................................................10
2.3 Cloning Keycloak examples.......................................................................................................11
2.3.1 Clone Project........................................................................................................................11
2.3.2 Compiling keycloak.............................................................................................................11
3 Using Keycloak SPI – adding a custom Event Listener module...................................................12
3.1 Presentation................................................................................................................................12
3.2 Installing event Listener jar module...........................................................................................12
4 Using Eclipse to debug Keycloak SPIs.........................................................................................22
4.1 Presentation................................................................................................................................22
4.2 Requirements..............................................................................................................................22
4.3 Creating a new eclipse debugging workspace............................................................................22
4.4 Importing keycloak examples maven project.............................................................................23
4.5 Launching keycloak server in debug mode................................................................................24
4.6 Attaching Eclipse Debugger to Keycloak...................................................................................25
4.6.1 Setting the Eclipse Debug configuration.............................................................................26
4.6.2 Filling Debug configuration information.............................................................................26
4.6.3 Debug Connexion................................................................................................................28
4.7 Debugging example....................................................................................................................28
4.7.1 Set a breakpoint...................................................................................................................28
4.7.2 Triggering breakpoint in EventListener SPI........................................................................29
5 Keycloak logger.............................................................................................................................31
5.1 Presentation................................................................................................................................31
5.2 Adjusting the log dynamically....................................................................................................31
5.2.1 Reading the current root-logger value.................................................................................31
5.2.2 Updating the root-logger value............................................................................................32
6 Keycloak Multifactor authentication (MFA) using OTP...............................................................33
6.1 Presentation................................................................................................................................33
6.2 Demo_otp realm.........................................................................................................................33
6.3 Modifying demo_otp Authentication Workflow........................................................................33
6.4 Mobile Authenticator..................................................................................................................34
6.5 Authentication of a user for the 1st
time......................................................................................34
6.6 Authentication of a user (after 1st
time)......................................................................................37
6.7 Keycloak OTP............................................................................................................................38
7 MFA with Keycloak.......................................................................................................................39
7.1 Presentation................................................................................................................................39
7.2 Keycloak OTP MFA versus SMS-OTP......................................................................................39
7.3 LOA concepts and MFA usage..................................................................................................39
7.4 Keycloak/RH-SSO Authentication flow and MFA....................................................................40
7.4.1 RH-SSO 7.2/ (Keycloak 3.4.3)............................................................................................40
7.4.2 Keycloak 4.6 (Latest)...........................................................................................................40
7.4.3 Upcoming release 5.X – Jira tickets....................................................................................41
7.5 Keycloak/RH-SSO MFA synthesis.............................................................................................41
8 Mapping LDAP Group to Keycloak Roles....................................................................................42
8.1 Presentation................................................................................................................................42
3. 8.2 LDAP Group to keycloak Roles mapping workflow.................................................................42
8.3 Concrete application: creating an ldap/SSO admin....................................................................42
8.4 Use case example.......................................................................................................................42
8.4.1 Example requirements.........................................................................................................42
8.4.2 Installing keycloak example ldap........................................................................................43
8.4.3 Connecting with Jexplorer to the embedded LDAP server.................................................43
8.4.4 Browsing the embedding ldap.............................................................................................44
8.5 User Federation with Ldap.........................................................................................................45
8.5.1 Setting up ldap user federation connector...........................................................................45
8.5.2 defining LDAP synchronisation..........................................................................................46
8.6 Adding group ldap mapper.........................................................................................................48
8.6.1 Creating ldap group mapping..............................................................................................48
8.6.2 Synchronizing ldap group mapping.....................................................................................49
8.7 Adding SSO Role to keycloak group..........................................................................................50
8.7.1 Keycloak ldap-admin group................................................................................................50
8.7.2 Adding a Keycloak role to this ldap-admin group...............................................................50
8.8 Testing workflow........................................................................................................................51
8.8.1 Creation of a new ldap user.................................................................................................51
8.8.2 Ldap-user part part of ldap-admin group.............................................................................51
8.8.3 Keycloak ldap synchronization............................................................................................51
8.8.4 new user with keycloak role admin rights...........................................................................52
8.9 Logging to the admin console with a new admin user-basis......................................................52
9 Getting Keycloak Access Token from LDAP values.....................................................................54
9.1 Installing wildfly 14...................................................................................................................54
9.1.1 Installation of wildfly 14.....................................................................................................54
9.1.2 Installation of Jboss EAP connector for wildfly..................................................................54
9.2 Starting keycloak auth server (port 8180)..................................................................................55
9.3 Registering ldap-app client into keycloak server......................................................................55
9.4 Import LDAP user......................................................................................................................56
9.4.1 Starting embedded LDAP server.........................................................................................56
9.4.2 Defining LDAP User Federation.........................................................................................56
9.4.3 Defining Role Ldap-mapper................................................................................................57
9.4.4 LDAP role synchronization.................................................................................................58
9.4.5 Postal code...........................................................................................................................59
9.4.6 Syncing Ldap User..............................................................................................................59
9.5 Deploying ldap-portal webapp...................................................................................................61
9.5.1 Fix Keycloak Auth URI.......................................................................................................61
9.5.2 Compiling and installing ldap-portal webapp......................................................................61
9.6 Testing the example....................................................................................................................62
9.6.1 Postal code for user bwilson................................................................................................62
9.6.2 Testing the ldap-portal webapp............................................................................................62
9.7 Examining Source code example...............................................................................................64
9.7.1 ldap-portal source code........................................................................................................64
9.7.2 Java documentation: Security Context................................................................................65
10 Using Client Scope with Keycloak..............................................................................................67
10.1 Presentation..............................................................................................................................67
10.2 Scope and claims Openid Core definition................................................................................67
10.3 Using Scope and Claims...........................................................................................................68
10.4 Using scope with keycloak.......................................................................................................68
4. 10.4.1 Using Keycloak Access Token..........................................................................................68
10.4.2 Keycloak attribute and role scope......................................................................................69
10.4.3 Keycloak access token example using scope.....................................................................69
10.5 Accessing the access token using direct grant..........................................................................69
10.5.1 ROPC workflow definition................................................................................................69
10.5.2 Enabling ROPC with keycloak..........................................................................................70
10.6 Scripting Token Access using ROPC workflow.......................................................................71
10.7 Creating a new scope to expose postalcode claim....................................................................72
10.7.1 Creating info scope within ldap-demo realm.....................................................................72
10.7.2 Mappers of info scope.......................................................................................................73
10.8 Using the new scope in REST API query.................................................................................75
10.9 Configuring keycloak client scope...........................................................................................76
10.9.1 Configuring info scope as an optional client scope...........................................................76
10.9.2 ResT API query displaying info scope..............................................................................76
10.10 Using keycloak Generator to evaluate scope..........................................................................77
11 Understanding client Authenticator security...............................................................................80
11.1 client_id/client_secret security issue........................................................................................80
11.2 Using other Keycloak client authenticator...............................................................................80
11.3 Using Signed JWT client authenticator....................................................................................80
11.4 JWKS_URI...............................................................................................................................81
11.5 Signed JWT allocator – example..............................................................................................81
11.5.1 Product-portal example......................................................................................................82
11.5.2 Registration of the product-portal client application in keycloak......................................82
11.5.3 Keycloak.json file (product-portal app).............................................................................82
11.5.4 Client-app keystore............................................................................................................83
11.6 Log trace...................................................................................................................................83
12 Understanding Token usage.........................................................................................................86
12.1 Token Lifecycle........................................................................................................................86
12.2 Understanding Keycloak session scope....................................................................................86
12.2.1 session creation..................................................................................................................86
12.2.2 Session usage.....................................................................................................................86
12.2.3 Session termination............................................................................................................87
12.2.4 Importance of session control – potential security vulnerability.......................................87
12.3 Keycloak Access Token............................................................................................................87
12.4 Offline access token..................................................................................................................89
12.4.1 Methods to deliver an access token...................................................................................89
12.4.2 Offline token presentation.................................................................................................89
12.4.3 How to use keycloak offline token....................................................................................90
12.4.4 Difference between an offline and refresh token...............................................................90
12.4.5 Offline Session Max Limited.............................................................................................90
12.5 Lifecycle of offline token.........................................................................................................90
12.5.1 Offline token creation........................................................................................................91
12.5.2 Offline token flow operations............................................................................................91
12.5.3 Offline token usage – getting an access token...................................................................91
12.5.4 Revoking offline token......................................................................................................91
13 Examples of Offline token usage.................................................................................................92
13.1 Using offline Token through direct access grant flow..............................................................92
13.1.1 Requirement.......................................................................................................................92
13.1.2 Token lifespan....................................................................................................................92
5. 13.1.3 Setting the maximum invokation of refresh token............................................................93
13.1.4 Script used to offline token................................................................................................94
13.2 Revoking the offline token.......................................................................................................96
13.2.1 Revokation of the offline token through the admin UI......................................................96
13.2.2 Through the user self service panel...................................................................................97
13.3 Necessity of adding offline in client request scope..................................................................97
13.3.1 Request without client scope.............................................................................................97
13.3.2 Request with client scope..................................................................................................98
13.4 Keycloak offline example.........................................................................................................98
13.4.1 Step1 – User needs to log to the app An offline access token is generated.......................99
13.4.2 Step 2 – user logs out from app.........................................................................................99
13.4.3 step3 – the app can access to the resources using the offline access token.....................100
14 Understanding keycloak user Fedaration..................................................................................100
14.1 Overview................................................................................................................................100
14.2 User Federation storage Provider...........................................................................................100
14.3 Keycloak default local userstorage (SQL database)...............................................................100
14.3.1 Synchronizing LDAP users to keycloak..........................................................................100
14.3.2 Synchronizing newly created Keycloak users to LDAP..................................................101
14.3.3 Dealing with keycloak – LDAP synchronization parameter...........................................102
14.4 Using Keycloak user Federation SPI......................................................................................102
14.5 Using Keycloak Provider interfaces.......................................................................................103
14.6 keycloak user storage simple (read-only)...............................................................................103
14.6.1 Deploying providers........................................................................................................103
14.7 User storega simple provider (write only)..............................................................................106
14.7.1 Configuring the write only provider................................................................................106
14.7.2 example-user.properties...................................................................................................106
14.7.3 Logging to keycloak........................................................................................................107
14.7.4 Displaying all the users....................................................................................................107
14.8 Keycloak user storage JPA provider.......................................................................................108
14.8.1 Presentation......................................................................................................................109
14.8.2 Using JPA........................................................................................................................109
14.8.3 Keycloak user storage jpa example.................................................................................109
14.8.4 Testing XA data source with keycloak console management..........................................111
14.8.5 Testing with with the Ejb appl.........................................................................................112
14.8.6 Rendering users visible in the admin console..................................................................112
14.9 Pointers...................................................................................................................................113
15 Understanding Keycloak Authentication...................................................................................114
15.1 Presentation.............................................................................................................................114
15.2 Authentication TAB selection.................................................................................................114
15.3 Authentication Binding...........................................................................................................115
15.4 Authentication Flow................................................................................................................116
15.4.1 Authentication flow presentation.....................................................................................116
15.4.2 Browser authentication flow............................................................................................117
15.4.3 Direct Authentication Grant flow....................................................................................117
15.4.4 Registration Flow.............................................................................................................118
15.4.5 Reset Credentials.............................................................................................................118
15.4.6 First Broker Login Flow..................................................................................................119
15.4.7 Client authentication flow................................................................................................120
15.5 Required Actions....................................................................................................................120
6. 15.6 Customising authenticator flow..............................................................................................121
15.6.1 Reference.........................................................................................................................122
15.6.2 Installing the authenticator example................................................................................122
15.6.3 Deploying the customized authenticator flow.................................................................122
16 Using apache2 mod_auth_openidc module with Keycloak (OpenID Connect)........................129
16.1 Presentation............................................................................................................................129
16.2 openID protocol recap............................................................................................................129
16.3 Putting mod_auth_openidc in place.......................................................................................131
16.4 Enabling mod_auth_openidc module with apache2...............................................................131
16.4.1 Getting hold of the library...............................................................................................131
16.4.2 Configuring keycloak Server for mod_auth_openidc......................................................131
16.5 Configuration of mod_auth_openidc module.........................................................................132
16.6 Example.................................................................................................................................134
16.7 6) Using the hook mod_auth_openidc....................................................................................135
16.8 Keycloak and NGINX............................................................................................................135
17 Protecting Keycloak/RH-SSO in production with a Reverse Proxy Architecture....................136
17.1 1) Why adding a reverse proxy...............................................................................................136
17.2 2) Architectural deployment example....................................................................................136