Configuring Keycloak to use Oracle Database

Keycloak team has done a really great job on how to configure to Keycloak to use RDBMS. But they have taken example of PostgreSQL to explain the steps for it.

I will share the steps required to configure Oracle database. For this example, I am taking Keycloak 7.0.0 and Oracle 12 Database.

If you haven’t installed Keycloak, you can follow this guide to setup Keycloak on your machine.

Once you are done with installing Keycloak on your machine, you can follow below steps:

1. Download JDBC jar from Oracle:
   You need to find and download JDBC jar required for your version of Oracle database. For Oracle 12, you can download the jar from this link. You need to sign-up(it’s free!!) then you can download the jar.
2. You need to create directory structure as shown in the image.

<keycloak-installation-directory>\modules\system\layers\keycloak\com\oracle\main

Inside that folder, copy the downloaded jar and create an empty module.xml file.

Folder Structure for installing Oracle JDBC Module

3. Inside module.xml, add below snippet. Just make sure that jar file name should be same in resource-root path

<?xml version=”1.0" ?>
<module xmlns=”urn:jboss:module:1.3" name=”com.oracle”>
 <resources>
 <resource-root path=”ojdbc8.jar”/>
 </resources>
 <dependencies>
 <module name=”javax.api”/>
 <module name=”javax.transaction.api”/>
 </dependencies>
</module>

4. Now you are set with the modules. But Keycloak won’t know about this module unless you registers it in standalone.xml, module.xml or standalone-ha.xml. (That depends on how you are running your server.)

5. I am running Keycloak in standalone mode, so I will update standalone.xml file. In standalone.xml, search for drivers and add an entry for Oracle as mentioned below:

<driver name="oracle" module="com.oracle">
  <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
 </driver>

After that also update KeycloakDS as shown below

<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:oracle:thin:@localhost:1521/orcl</connection-url>
 <driver>oracle</driver>
 <security>
  <user-name>username</user-name>
  <password>password</password>
 </security>
 <!--<validation>
  <background-validation>true</background-validation>
  <background-validation-millis>60000</background-validation-millis>
 </validation>-->
 <pool>
  <max-pool-size>20</max-pool-size>
 </pool>
</datasource>

Once you have made those changes, your standalone.xml file should look similar to this.

And don’t forget to update the server host, username and password !! ;-)

That’s it.

Now, once you start Keycloak server, it would start with Oracle as database.

Let me know, if you face any issues while following the above steps.

Update 1: Tried with latest release(10.0.0) of Keycloak as well.

Happy Coding :-)

References:

https://www.keycloak.org/docs/latest/server_installation/#_database