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 / 304
Table of contents
1 Introduction to Keycloak for Identity and Access Management .............................................................11
1.1 Keycloak overview.............................................................................................................................11
1.2 Keycloak competitors ........................................................................................................................12
1.3 Prerequisites .....................................................................................................................................12
1.3.1 Hardware requirements ............................................................................................................12
1.3.2 Software requirements..............................................................................................................12
1.3.3 Tools..........................................................................................................................................13
1.4 Documentation ..................................................................................................................................14
1.4.1 Keycloak documentation...........................................................................................................14
1.4.2 White papers.............................................................................................................................14
1.5 Keycloak code sources .....................................................................................................................16
1.6 Build Keycloak...................................................................................................................................17
1.7 Environment variables.......................................................................................................................18
2 Starting with Keycloak ............................................................................................................................19
2.1 Overview............................................................................................................................................19
2.2 Install Keycloak .................................................................................................................................19
2.3 Keycloak Layout................................................................................................................................19
2.4 Start Standalone Server distribution .................................................................................................20
2.5 Deployment on Tomcat/Jetty.............................................................................................................22
2.6 Keycloak on Quarkus ........................................................................................................................23
2.7 Keycloak healthcheck........................................................................................................................26
2.8 Considerations on Keycloak persistence ..........................................................................................31
2.9 Keycloak core concepts ....................................................................................................................31
2.10 Path to integration with Keycloak .................................................................................................32
2.11 Integration with Keycloak..................................................................................................................33
2.12 Usages of keycloak and corresponding technologies ..................................................................33
2.13 Access the admin console ............................................................................................................35
2.14 Create Admin account ..................................................................................................................37
2.15 Create a realm ..............................................................................................................................39
2.16 Define roles for users....................................................................................................................40
2.17 Add users......................................................................................................................................42
2.18 Access user account Service........................................................................................................45
2.19 Add a client to realm demo...........................................................................................................46
2.19.1 Client Protocol Types............................................................................................................47
2.19.2 Access Types........................................................................................................................48
2.20 Define roles for the client app.......................................................................................................49
2.21 Create a group..............................................................................................................................51
3 Starting with WildFly...............................................................................................................................53
3.1 Overview............................................................................................................................................53
3.2 Install WildFly server .........................................................................................................................53
3.3 Start WildFly Server ..........................................................................................................................53
3.4 Access the admin console.................................................................................................................54
3.5 Install Keycloak adapters ..................................................................................................................56
3.5.1 OpenID Connect adapter..........................................................................................................56
3.5.2 SAML 2.0 adapter .....................................................................................................................57
3.5.3 Check adapters installation.......................................................................................................59
4 Secure a JavaEE application with Keycloak ..........................................................................................60
4.1 Prerequisites .....................................................................................................................................60
4.2 Basic application deployment............................................................................................................60
4.3 Configure HTTP basic authentication with WildFly ...........................................................................60
4.4 Basic application login.......................................................................................................................61

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 / 304
4.5 Integrate the Vanilla application with Keycloak .................................................................................62
4.5.1 Install Keycloak OIDC adapter..................................................................................................62
4.5.2 Register the Vanilla application with Keycloak .........................................................................62
4.5.3 Display Keycloak Vanilla client information ..............................................................................64
4.5.4 Update Vanilla application configuration in WildFly..................................................................64
4.6 Test the application............................................................................................................................65
5 Use Keycloak with client applications.....................................................................................................67
5.1 Overview............................................................................................................................................67
5.2 Prerequisites .....................................................................................................................................67
5.3 Database service setup.....................................................................................................................68
5.3.1 Create Realm............................................................................................................................68
5.3.2 Enable user registration............................................................................................................68
5.3.3 Create user ...............................................................................................................................69
5.3.4 Create Database service application........................................................................................69
5.3.5 Build and deploy database-service webapp.............................................................................71
5.4 Customer application setup...............................................................................................................72
5.4.1 Create Customer client application...........................................................................................72
5.4.2 Build and deploy customer-portal webapp ...............................................................................75
5.5 Customer application test..................................................................................................................76
5.6 Product application setup..................................................................................................................77
5.6.1 Create Product client application..............................................................................................77
5.6.2 Build product-portal webapp.....................................................................................................81
5.7 Product application Test ....................................................................................................................83
5.8 Common mistakes.............................................................................................................................83
5.8.1 Invalid client secret (WildFly server).........................................................................................83
5.8.2 Invalid user credentials .............................................................................................................84
6 Understanding Oauth2 ...........................................................................................................................85
6.1 Oauth2 Presentation .........................................................................................................................85
6.2 Oauth2 Elements...............................................................................................................................87
6.2.1 Oauth Roles..............................................................................................................................87
6.2.2 Tokens.......................................................................................................................................87
6.2.3 Scopes vs permissions .............................................................................................................87
6.2.4 Types of clients .........................................................................................................................88
6.2.5 Standard OAuth 2.0 / OpenID Connect endpoints ...................................................................88
6.2.6 Callback routes .........................................................................................................................89
6.2.7 OAuth 2.0 grant types...............................................................................................................89
6.2.8 Https is mandatory....................................................................................................................90
6.3 OAuth 2.0 grant types in details ........................................................................................................90
6.3.1 Authorization Code Grant .........................................................................................................90
6.3.2 Implicit.......................................................................................................................................90
6.3.3 Resource Owner Password Credential (ROPC).......................................................................91
6.3.4 Client credentials grant .............................................................................................................92
6.3.5 Refresh token flow ....................................................................................................................92
6.4 Which OAuth 2.0 Grant to Use..........................................................................................................93
6.4.1 Resource owner and client application are same / Machine to machine communication........93
6.4.2 Web / SPA (single page application) / Mobile applications.......................................................93
6.5 Authorization code grant flow with Proof Key for Code Exchange (PKCE) ......................................93
6.6 Use of refresh tokens ........................................................................................................................95
7 Understanding OpenID Connect (OIDC)................................................................................................96
7.1 Overview............................................................................................................................................96
7.2 OpenID sequence flow......................................................................................................................97
7.3 OpenID flows.....................................................................................................................................97
7.3.1 Authorization Code Flow...........................................................................................................97
7.3.2 Implicit Flow ..............................................................................................................................97

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 / 304
7.3.3 Hybrid Flow...............................................................................................................................98
7.3.4 Flow features ............................................................................................................................98
7.3.5 Response types by flow............................................................................................................98
7.4 Authorization Code flow ....................................................................................................................99
7.5 Implicit Flow.....................................................................................................................................103
7.6 ID token analysis .............................................................................................................................105
8 Debug and analyse a Keycloak example .............................................................................................107
8.1 Overview..........................................................................................................................................107
8.2 Prerequisites ...................................................................................................................................107
8.3 Create service-jaxrs application ......................................................................................................107
8.4 Create app-jsp application...............................................................................................................109
8.5 Create a user...................................................................................................................................112
8.6 Login to the app...............................................................................................................................113
8.7 Check Request Headers and Response Headers of the /authenticate endpoint request ..............116
8.8 Use jwt.io debugger.........................................................................................................................117
8.9 Verify the signature..........................................................................................................................119
8.10 Check Cookie within Chrome .....................................................................................................119
9 Use REST API with Keycloak...............................................................................................................121
9.1 Presentation ....................................................................................................................................121
9.2 App-js application............................................................................................................................121
9.3 Realm endpoints - .well-known/openid-configuration .....................................................................121
9.4 admin-cli Client application..............................................................................................................123
9.4.1 Getting an admin Bearer token with the admin CLI................................................................123
9.4.2 Use admin Bearer Token in Rest API query ...........................................................................125
9.4.3 Use another admin user with admin-cli ..................................................................................126
9.4.4 List the number of sessions present on a realm.....................................................................127
9.5 Use Kcadm......................................................................................................................................128
9.5.1 Create .Keycloak registry........................................................................................................128
9.5.2 Use Kcadm .............................................................................................................................130
9.5.3 Security measure with Kcadm ................................................................................................130
9.6 Usage of REST API with realm endpoints.......................................................................................130
9.6.1 App-jsp information.................................................................................................................131
9.6.2 Perform a ROPC query to the /token endpoint.......................................................................131
9.6.3 Call the userinfo endpoint .......................................................................................................132
9.6.4 Call the introspect endpoint ....................................................................................................132
9.7 Call Refresh Token using ROPC.....................................................................................................133
9.7.1 ROPC query to generate access and refresh tokens.............................................................133
9.7.2 Perform the query using the refresh token .............................................................................135
10 Use OpenID protocol to connect to an IDP provider ............................................................................137
10.1 Presentation................................................................................................................................137
10.2 Prerequisites...............................................................................................................................137
10.3 France Connect Endpoints .........................................................................................................138
10.4 France Connect Identity Provider deployment ...........................................................................138
10.5 Create an identity provider..........................................................................................................139
10.6 Add identity provider mappers....................................................................................................139
10.7 Setup the France Connect theme...............................................................................................140
10.8 Test the application .....................................................................................................................141
10.9 Account Linking...........................................................................................................................144
11 SAML V2 Presentation .........................................................................................................................146
11.1 What is SAML ? ..............................................................................................................................146
11.2 SAML 2.0 in short ...........................................................................................................................146
11.2.1 SAML V2 features...............................................................................................................146
11.2.2 Major Key elements ............................................................................................................146
11.3 Examples of SSO flows ..................................................................................................................148

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 / 304
11.3.1 SAML Service Provider Initiated SSO Flow........................................................................148
11.3.2 SAML Identity Provider Initiated SSO Flow ........................................................................149
11.3.3 SAML components..............................................................................................................150
11.4 SAML Components detailed ...........................................................................................................151
11.4.1 SAML 2.0 Protocols ............................................................................................................151
11.4.2 SAML 2.0 Bindings .............................................................................................................152
11.4.3 SAML 2.0 profiles................................................................................................................152
11.5 SAML elements (used by Keycloak)...............................................................................................153
11.5.1 General Adapter Config ......................................................................................................153
11.5.2 SP Element.........................................................................................................................154
11.5.3 SP Keys and Key elements ................................................................................................156
11.5.4 KeyStore element ...............................................................................................................156
11.5.5 Key PEMS...........................................................................................................................157
11.5.6 SP PrincipalNameMapping element...................................................................................157
11.5.7 RoleIdentifiers element .......................................................................................................158
11.5.8 IDP Element........................................................................................................................158
11.5.9 IDP SingleSignOnService sub element ..............................................................................159
11.5.10 IDP SingleLogoutService sub element ...............................................................................159
11.5.11 IDP Keys subelement .........................................................................................................160
11.6 XML SAML Examples .....................................................................................................................161
11.6.1 Post Request example........................................................................................................161
11.6.2 Response Extract ...............................................................................................................162
12 SAML broker example with Keycloak...................................................................................................163
12.1 Presentation................................................................................................................................163
12.2 Prerequisites...............................................................................................................................163
12.3 Import saml-broker-authentication-realm realm in Keycloak ......................................................163
12.4 Import saml-broker-realm realm in Keycloak..............................................................................165
12.5 Build and deploy saml-broker-authentication application ...........................................................167
12.6 Test .............................................................................................................................................169
12.7 Add SAML builtin protocol mapper .............................................................................................174
12.8 Check details of a built-in member (givenName)........................................................................175
12.9 Analyze content of a response with SAML tracer.......................................................................176
12.10 Map SAML attributes at identity provider level ...........................................................................177
12.11 Complete test scenario ...............................................................................................................178
12.12 Account linking............................................................................................................................178
13 SAML Integration with an external identity provider (Okta)..................................................................180
13.1 Overview.....................................................................................................................................180
13.2 Prerequisites...............................................................................................................................180
13.3 Configure Okta as an identity provider .......................................................................................180
13.3.1 Create an Okta account......................................................................................................180
13.3.2 Configure Okta identity provider .........................................................................................184
13.3.3 Assign a user to OKTA_SAML_IDP....................................................................................193
13.4 Configure Keycloak as a service provider ..................................................................................195
13.4.1 Create saml_okta_idp identity provider ..............................................................................195
13.4.2 Add attributes mapping.......................................................................................................196
13.5 Test .............................................................................................................................................197
13.6 Account Linking...........................................................................................................................199
14 Understanding Authorization Services with Keycloak ..........................................................................201
14.1 Presentation................................................................................................................................201
14.2 Key Concepts of Keycloak Authorization service .......................................................................201
14.3 Components of an Authorization Service ...................................................................................202
14.4 Resources...................................................................................................................................202
14.5 Authorization Scopes..................................................................................................................202
14.6 Policies........................................................................................................................................203

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 / 304
14.6.1 Role Policy..........................................................................................................................203
14.6.2 JavaScript Role...................................................................................................................203
14.7 Permission ..................................................................................................................................204
14.7.1 Resource – policy permission match..................................................................................204
14.7.2 Scope – policy permission match .......................................................................................204
14.8 Putting it all together – Tailoring authorization Service to your architecture needs....................204
15 Use a simple Keycloak Authorization example ....................................................................................206
15.1 Secure a Servlet Application.......................................................................................................206
15.2 Prerequisites...............................................................................................................................206
15.3 Configure Keycloak.....................................................................................................................206
15.4 Get the adapter configuration .....................................................................................................211
15.5 Build and Deploy the application ................................................................................................211
15.6 Test the application .....................................................................................................................212
16 Authorization access using Role based users .....................................................................................214
16.1 Overview.....................................................................................................................................214
16.2 Prerequisites...............................................................................................................................214
16.3 Configure Keycloak.....................................................................................................................214
16.4 Build and deploy the application.................................................................................................215
16.5 Authorization example test .........................................................................................................216
16.5.1 Log in with restricted privileges...........................................................................................216
16.5.2 Log in as Premium user......................................................................................................217
16.6 Detailed authorization scheme analysis .....................................................................................218
16.6.1 Resources details ...............................................................................................................219
16.6.2 Scopes details.....................................................................................................................219
16.6.3 Policies details ....................................................................................................................220
16.6.4 Permissions details.............................................................................................................221
17 Fine Grain Authorization – UMA policy.................................................................................................224
17.1 Presentation................................................................................................................................224
17.2 Prerequisites...............................................................................................................................226
17.3 About the Example application ...................................................................................................226
17.4 Configure Keycloak.....................................................................................................................227
17.5 Deploy the Example Applications ...............................................................................................228
17.6 Test the application .....................................................................................................................229
17.6.1 Create albums.....................................................................................................................229
17.6.2 Share albums......................................................................................................................230
17.6.3 View shared albums............................................................................................................234
17.6.4 Request permissions ..........................................................................................................236
17.6.5 Manage permission requests..............................................................................................237
17.6.6 View all resources...............................................................................................................239
17.6.7 Revoke permissions ...........................................................................................................241
17.6.8 Summary.............................................................................................................................243
18 Keycloak LDAP integration...................................................................................................................244
18.1 Presentation................................................................................................................................244
18.2 Prerequisites...............................................................................................................................244
18.3 About the Keycloak LDAP example............................................................................................244
18.4 Run and load the LDAP server ...................................................................................................244
18.5 Examine LDAP example using JXplorer.....................................................................................245
18.6 Configure Keycloak.....................................................................................................................247
18.6.1 Define LDAP synchronization policy...................................................................................249
18.6.2 Configure user federation mappers ....................................................................................250
18.7 Build and deploy the application.................................................................................................252
18.8 Test .............................................................................................................................................254
19 Relational Database Setup...................................................................................................................255
19.1 Presentation................................................................................................................................255

6.
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 9 / 304
19.2 PostgreSQL DB installation and preparation..............................................................................255
19.2.1 Installing PostgreSQL on Ubuntu .......................................................................................255
19.2.2 Installing PostgreSQL on RedHat Linux .............................................................................255
19.2.3 Change PostgreSQL password ..........................................................................................256
19.2.4 Authentication test ..............................................................................................................256
19.2.5 Create keycloak user ..........................................................................................................256
19.2.6 Create keycloak DB ............................................................................................................256
19.2.7 Create keycloak schema ....................................................................................................257
19.3 Keycloak configurations..............................................................................................................257
19.3.1 PostgreSQL driver installation ............................................................................................257
19.3.2 JDBC driver declaration......................................................................................................258
19.3.3 Datasource declaration.......................................................................................................258
19.3.4 Connection Jpa update to accommodate dedicated schema.............................................259
19.4 Test the configuration..................................................................................................................259
20 Import / Export Keycloak configuration.................................................................................................261
20.1 Presentation................................................................................................................................261
20.2 Import/export commands............................................................................................................261
20.2.1 Exporting to a single file......................................................................................................261
20.2.2 Exporting to a directory.......................................................................................................261
20.2.3 Imports................................................................................................................................261
20.3 Options........................................................................................................................................261
21 Protect Keycloak in production with a Reverse Proxy architecture......................................................263
21.1 Why adding a reverse proxy.......................................................................................................263
21.2 Architectural deployment example .............................................................................................263
21.2.1 Role of the DMZ..................................................................................................................263
21.2.2 First firewall (internet - DMZ) ..............................................................................................264
21.2.3 Second Firewall ..................................................................................................................264
21.2.4 Reverse Proxy - DMZ .........................................................................................................264
21.2.5 Keycloak authentication Server - LAN................................................................................264
21.3 HTTPS everywhere ....................................................................................................................264
21.4 Reverse Proxy server used with Keycloak .................................................................................264
22 Keycloak Security.................................................................................................................................265
22.1 Security Best Practices...............................................................................................................265
22.2 Enable SSL/HTTPS for the Keycloak Server .............................................................................265
22.2.1 PKI – Self Cert – CA Authorithy ..........................................................................................265
22.2.2 Generate self cert ...............................................................................................................265
22.2.3 Customize standalone.xml with ssl.....................................................................................266
22.2.4 Check SSL connection using openssl ................................................................................266
22.2.5 Check HTTPS connection ..................................................................................................268
22.3 Outgoing Http Requests .............................................................................................................269
22.4 Differences between when using self signed and signed certificates ........................................270
23 Keycloak Networking............................................................................................................................271
23.1 Keycloak Port presentation – standalone.xml (standalone-ha.xml) ...........................................271
23.2 Usage of each port .....................................................................................................................271
23.3 Disabling http and AJP for Keycloak...........................................................................................272
23.4 Keycloak Multicast Groups .........................................................................................................272
23.5 Keycloak multicast Group with clustering ...................................................................................273
23.5.1 Jgroups - multicast..............................................................................................................273
23.5.2 Mod_Cluster - multicast......................................................................................................273
24 Keycloak Clustering Operating Modes.................................................................................................275
24.1 Presentation................................................................................................................................275
24.2 Standalone clustered mode........................................................................................................275
24.2.1 Configure a shared external database ...............................................................................277
24.2.2 Set up a load balancer........................................................................................................277

7.
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 10 / 304
24.2.3 Enable HTTPS/SSL with a Reverse Proxy.........................................................................278
24.2.4 Test the cluster....................................................................................................................279
24.3 Domain clustered mode..............................................................................................................280
24.3.1 Master node configuration ..................................................................................................281
24.3.2 Slave node configuration ....................................................................................................281
24.4 Clustered Domain Example........................................................................................................282
24.4.1 Prerequisites.......................................................................................................................282
24.4.2 Configure the slave secret key ...........................................................................................282
24.4.3 Create an admin master user .............................................................................................284
24.4.4 Start the servers..................................................................................................................285
24.5 Add app_vanilla profile client application to the cluster..............................................................286
24.6 Limitation of the domain cluster example ...................................................................................287
25 Mod_cluster with Standalone HA cluster deployment ..........................................................................287
25.1 Presentation................................................................................................................................287
25.2 Mod_cluster – Apache SW load Balancer ..................................................................................287
25.2.1 Presentation........................................................................................................................287
25.2.2 Mod_cluster and multicast group........................................................................................287
25.2.3 Mod_cluster with Keycloak .................................................................................................287
25.3 Clustering standalone HA example ............................................................................................288
25.3.1 Presentation........................................................................................................................288
25.3.2 Limitation.............................................................................................................................288
25.3.3 Set Keycloak requires SSL to none ....................................................................................288
25.3.1 Mod_Cluster configuration..................................................................................................289
25.3.2 Apache installation..............................................................................................................289
25.3.3 Mod_Cluster configuration..................................................................................................290
25.3.4 Commands used.................................................................................................................291
25.3.5 Test Mod_cluster.................................................................................................................291
25.4 Testing application failover..........................................................................................................292
26 SPI testing integration – High available environment...........................................................................294
26.1 Overview.....................................................................................................................................294
26.2 Event SPI....................................................................................................................................294
26.2.1 Deploying the Jar file ..........................................................................................................294
26.2.2 Registering the SPI in standalone-ha.xml ..........................................................................294
26.3 SPI various use cases ................................................................................................................294
26.3.1 Use case 1 – Both nodes are Up........................................................................................294
26.3.2 Use case 2 – Node1 brought Down....................................................................................295
26.4 SPI interaction with keycloak in clustering mode........................................................................296
27 Keycloak Clustering best practices – Recommendation......................................................................297
28 Annex : Oauth 2.0, OIDC, PKCE, Refresh tokens (French) ................................................................298
28.1 Considération sur la sécurité des applications Web...................................................................298
28.2 Introduction à OAuth 2................................................................................................................298
28.3 Introduction d’OpenID Connect (OIDC)......................................................................................298
28.4 Oauth 2 en détails.......................................................................................................................299
28.4.1 Vocabulaire .........................................................................................................................299
28.4.2 Flux de codes d’autorisation (Authorization Code Flow) ....................................................299
28.4.3 Flux de codes d'autorisation avec PKCE (Authorization Code with PKCE Flow) ..............301
28.4.4 Flux implicite (Implicit Flow)................................................................................................303
28.4.5 Jeton de rafraîchissement ..................................................................................................304