Install Keycloak with MySQL (2024)

In this tutorial, we'll demonstrate how to install Keycloak with MySQL database on Windows or Linux.

Q: What is Keycloak?

Keycloak is a modern application and service-oriented open source Identity and Access Management system. Single-Sign-On (SSO), Identity Brokering and Social Login, User Federation, Client Adapters, an Admin Console, and an Account Management Console are some of the features offered by Keycloak.

Follow below steps to download and install the Keycloak.

1. Goto keycloak and download the zip file.

2. Extract the downloaded zip and go to bin folder.

3. Start the Keycloak by using standalone from the keycloak-15.1.1 -> bin folder.

   D:\keycloak-15.1.1\bin>standalone

4. The Keycloak will start at default port 8080.

5. Keycloak uses h2 database as default database.

6. Access Keycloak Login page at http://localhost:8080/auth.

Follow below steps to change the H2 database to MySql and default port to 9090.

MYSql with Keycloak

1. Create a schema in MySql database to store keycloak data.

2. Download the mysql java connector jar from mysql java connector jar.

3. After extracting, verify that the mysql server has the same version as the downloaded jar.

   From MySql database, go to Help -> About Workbench to verify the version.


4. Create the new folder mysql\main under keycloak-15.1.1 -> modules -> system -> layers -> keycloak -> com folder and place the mysql-connector jar.
5. Create module.xml file with below content at same place.

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.3" name="com.mysql">
   
       <resources>
           <resource-root path="mysql-connector-java-8.0.28.jar"/>
       </resources>
   
       <dependencies>
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </dependencies>
   </module>


6. Edit existing H2 code with below modified code from standalone.xml file from keycloak-15.1.1 -> standalone -> configuration path to add mysql database.
   Existing H2 Code

   <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
           <connection-url>jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE</connection-url>
           <driver>h2</driver>
           <security>
               <user-name>sa</user-name>
               <password>sa</password>
           </security>
   </datasource>
   <drivers>
            <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
            </driver>
   </drivers>

   Modified Code for MySQL database

   Update the connection-url , username and password according to your database configuration.

   <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
            <connection-url>jdbc:mysql://localhost/keycloakdb</connection-url>
            <driver>mysql</driver>
            <security>
                <user-name>root</user-name>
                <password>root</password>
            </security>
   </datasource>
   <drivers>
            <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
            </driver>
   		<driver name="mysql" module="com.mysql">
                <driver-class>com.mysql.jdbc.Driver</driver-class>
            </driver>
   </drivers>

7. From the same file, change the port from 8080 to 9090.

   <socket-binding name="http" port="${jboss.http.port:9090}"/>

8. Start the Keycloak by using standalone from the keycloak-15.1.1 -> bin folder.

   D:\keycloak-15.1.1\bin>standalone

9. We can see now Keycloak is using mysql database.

10. In the MySql database schema, default Keycloak tables will be created.

11. Now access the keycloak from http://localhost:9090/auth

12. Now lets Create Users/Roles in Realm.