README

KeyEdge: Delphi 12 & Keycloak OIDC Integration

KeyEdge is a reference implementation for integrating OpenID Connect (OIDC) authentication into Delphi VCL applications. It utilizes the modern TEdgeBrowser component (WebView2) to handle the Authorization Code Flow with a Keycloak identity server.

🚀 Overview

This project demonstrates:

• Initializing and configuring the WebView2 (Edge) engine in Delphi.
• Orchestrating a local Keycloak + PostgreSQL environment via Docker.
• Intercepting OAuth2 redirect codes and exchanging them for JWT Access Tokens.
• Clean Code practices using Delphi 12 features like inline variables.

🛠 Prerequisites & Installation

1. Install the WebView2 SDK (Delphi GetIt)

Before compiling the project, you must install the official SDK package within RAD Studio:

1. Open RAD Studio 12.
2. Go to Tools > GetIt Package Manager.
3. Search for "WebView2".
4. Select and install the Edge WebView2 SDK package.
   • This step provides the necessary source files like Winapi.WebView2.pas and Winapi.ActiveX.pas.

2. Infrastructure (Docker)

This repository includes a docker-compose.yml that sets up Keycloak 26+ and a PostgreSQL 15 database.

• Start the services:

docker-compose up -d

• Access Keycloak Admin Console:
• URL: http://localhost:8080
• User: admin
• Password: admin_password

3. WebView2 Runtime & DLL

Your Windows environment must have the Evergreen WebView2 Runtime installed. Additionally, you must place the WebView2Loader.dll in your project's output folder.

Where to find the DLL:

• For Win32 builds: C:\Program Files (x86)\Embarcadero\Studio\23.0\bin\sub_publisher\i386\WebView2Loader.dll
• For Win64 builds: C:\Program Files (x86)\Embarcadero\Studio\23.0\bin\sub_publisher\x64\WebView2Loader.dll

⚙️ Keycloak Configuration

1. Create a Realm: Name it test_realm.
2. Create a Client: * Client ID: test-client
   • Capability Config: Enable Standard Flow.
   • Valid Redirect URIs: http://localhost:9000/callback
   • Web Origins: *
3. Create a User: Go to Users, create a new user, and set a permanent password in the Credentials tab.

📂 Project Structure & Build

Project Options

To keep the repository clean, the project is configured to output compiled files into platform-specific folders:

• Output directory: .\$(Platform)\$(Config)
• Unit output directory: .\$(Platform)\$(Config)\DCU

How to Run

1. Open KeyEdge.dproj in Delphi 12.
2. Ensure the correct WebView2Loader.dll is in the output folder (Win32\Debug or Win64\Debug).
3. Compile and Run (F9).

📝 Implementation Notes

Low-Level Interoperability

• Delphi: Compiles to high-performance native machine code.
• WebView2Loader.dll: A C++/COM-based bridge that allows the native application to host the Chromium-based Edge renderer.
• Networking: The login process uses local loopback (localhost) sockets to communicate between the native process and the containerized Keycloak service.

📄 License

This project is for educational purposes. Keycloak, PostgreSQL, and Microsoft Edge are trademarks of their respective owners.