Keycloak SSO with Google Workspace and Oracle APEX: A Practical Setup Guide

A step-by-step architecture for connecting Google Workspace, Keycloak, and Oracle APEX with secure callbacks, database network access, and application authorization.

A reliable Oracle APEX SSO implementation is not just an OAuth client configuration. It is a chain of trusted endpoints, credentials, database network permissions, user mapping, and application authorization. This guide describes the sequence that keeps each layer testable.

1. Start with a Dedicated Keycloak Environment

Run Keycloak with a pinned image and PostgreSQL rather than the embedded development database.
Create a dedicated realm for the organization and define application roles separately from authentication.
Keep the Keycloak management interface and database on private network paths.
Use environment variables or a secret manager for administrator passwords and client secrets.

2. Put HTTPS and the Public Hostname in Place First

Create the authentication DNS record at the authoritative provider and confirm where Cloudflare, an F5, or another edge proxy sits.
Route the public hostname through Nginx or Apache to Keycloak on loopback.
Install a trusted certificate and configure forwarded host, port, and protocol headers from trusted proxies only.
Verify the realm discovery document before configuring any application client.

3. Configure Google Workspace as the Identity Provider

Create an internal Google OAuth application for the Workspace organization.
Register the Keycloak broker callback, not the Oracle APEX callback: /realms//broker/google/endpoint.
Use the openid, email, and profile scopes and keep the Google client secret only in Keycloak or an approved secret store.
Use Workspace organization controls for employee access; do not treat an email suffix alone as proof of authorization.

4. Create a Separate Confidential APEX Client

Create a confidential Keycloak client specifically for Oracle APEX, such as clariont-apex.
Register the exact APEX/ORDS callback generated by the installed deployment.
Keep the Google OAuth client ID and the Keycloak APEX client ID separate; confusing them causes a Client not found error.
Store the Keycloak client secret in the APEX credential store, never in page code or a public application item.

5. Do Not Skip the Oracle Database Network Layer

Grant the actual APEX parsing schema connect and resolve access to the Keycloak hostname on port 443.
Configure the APEX instance wallet path in the PDB that actually hosts the application.
Trust the certificate chain in the Oracle wallet and test the discovery URL with UTL_HTTP before testing browser login.
Check the active PDB instead of assuming the CDB or a different development PDB is serving the application.

6. Separate Authentication from Application Authorization

Use an OIDC claim such as preferred_username or a stable subject for the APEX username mapping.
Make the Keycloak authentication scheme current only after discovery and callback tests pass.
Assign APEX Reader, Contributor, and Administrator roles explicitly; successful Google login must not grant administrator access.
Test login, logout, expired sessions, an unassigned user, and a suspended Workspace account.

The most useful troubleshooting pattern is to identify the first boundary that fails: Google redirect validation, Keycloak token exchange, Oracle discovery access, APEX username mapping, or application authorization. Treating each boundary independently makes SSO predictable and keeps security decisions visible.