Skip to content

Keycloak Migration to Oracle

This document outlines key considerations and changes resulting from the Keycloak migration to an Oracle database.

Central Oracle Database Setup (Critical for HAJ)

Keycloak requires a central database to store its configuration, users, roles, and other persistent data. For High Availability, both Keycloak nodes must connect to the same database instance. This database is the single source of truth for our Keycloak deployment. This is especially critical for the infrastructure in HAJ.

Realm Import Considerations

Important

When importing a Keycloak realm, ensure that the webOrigins field is properly configured to avoid errors.

webOrigins Configuration: The webOrigins array must contain a value. To specify an empty web origin, use a plus sign (+):

"webOrigins": ["+" ],

Realm Export

Important

Secrets are not exported. Add secrets to clients manually:

"clientId": "autotest",

"secret": "MyPassword"

Oracle JDBC Connection String Formats

The format of the Java Database Connectivity (JDBC) connection string for Oracle depends on whether you're connecting via a Service ID (SID) or a Service Name

  • Using SID: jdbc:oracle:thin:@[HOST]:[PORT]:[SID]
  • Using Service Name: jdbc:oracle:thin:@[HOST]:[PORT]/SERVICE

Dockerfile Changes

Several modifications have been made to the Keycloak Dockerfile to accommodate Oracle migration and optimize the build and startup process.

  • Oracle JDBC Driver: The Oracle JDBC driver has been added to the Keycloak installation within the Dockerfile.

  • Environment Variable Relocation: The following environment variables have been moved from the Docker Compose file directly into the Dockerfile:

    • ENV KC_DB=oracle
    • ENV KC_HEALTH_ENABLED=true
    • ENV KC_METRICS_ENABLED=true

  • Optimized Build Process: Keycloak is built during the image creation stage rather than at container startup. This significantly accelerates the Keycloak container's startup time.

Changelog

Date Author Message
2026-02-25 aresnikowa QC-50171: in Keycloak folder, adjusted admonitions
2026-02-25 aresnikowa Merge remote-tracking branch 'origin/master'