feat: add PostgreSQL OAuth Validator for Keycloak (kc_validator)

Initial implementation of the `kc_validator` extension, providing OAuth-based
authentication integration between PostgreSQL and Keycloak.

Includes:

- Core C extension
- Dockerfile for building and testing
- Example manifests for CloudNativePG and Keycloak
- Keycloak demo realm export
- Updated `.gitignore`
- Refreshed `README.md` with usage, configuration, and quick start instructions

Signed-off-by: Yoshiyuki Tabata <yoshiyuki.tabata.jy@hitachi.com>

Author: y-tabata

.gitignore

@@ -1,30 +1,24 @@
-# If you prefer the allow list template instead of the deny list, see community template:
-# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
-#
-# Binaries for programs and plugins
-*.exe
-*.exe~
-*.dll
-*.so
-*.dylib
+# PostgreSQL extension build artifacts
+src/*.o
+src/*.so
+src/*.bc
+src/.deps/
+src/*.log
 
-# Mac
-.DS_Store
-
-# Test binary, built with `go test -c`
-*.test
-
-# Output of the go coverage tool, specifically when used with LiteIDE
-*.out
+# Docker build cache / certs
+docker/certs/*.key
+docker/certs/*.csr
+docker/certs/*.crt
 
-# editor and IDE paraphernalia
-.idea
+# Editor/IDE files
+.DS_Store
+.idea/
 *.swp
 *.swo
 *~
+.vscode/
+*.bak
 
-# Dependency directories (remove the comment below to include it)
-# vendor/
-
-# Go workspace file
-go.work
+# Misc
+*.test
+*.out

README.md

@@ -2,5 +2,138 @@
 
 # PostgreSQL OAuth Validator for Keycloak
 
-TODO
+**Requires**: PostgreSQL 18+
 
+This module enables PostgreSQL 18 to delegate authorization decisions to Keycloak using OAuth tokens, leveraging Keycloak Authorization Services for fine-grained, token-based access control.
+It sends a permission request to Keycloak's token endpoint using `grant_type=urn:ietf:params:oauth:grant-type:uma-ticket` and expects a decision response (`response_mode=decision`), which is a Keycloak-specific extension.
+It is designed for use with CloudNativePG, allowing database role elevation to be controlled by Keycloak policies.
+
+---
+
+## Features
+
+- **Keycloak-based authorization for PostgreSQL roles**
+  - Delegates database role elevation decisions to Keycloak Authorization Services using OAuth tokens.
+- **Permission string construction**
+  - Builds permission strings as `<resource_name>#<scope>` and sends permission requests to Keycloak's token endpoint (`grant_type=urn:ietf:params:oauth:grant-type:uma-ticket`, `response_mode=decision`).
+- **Configurable via PostgreSQL GUC parameters**
+  - All integration settings (endpoints, resource names, timeouts, debug, etc.) are controlled via GUCs.
+- **Secure HTTP communication**
+  - Uses libcurl for HTTP requests with configurable timeouts and safe logging.
+- **Optional JWT issuer verification**
+  - Can verify the `iss` claim in JWT tokens for additional security.
+
+---
+
+## Example: CloudNativePG Configuration
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: pg-oauth
+spec:
+  imageName: pg18-kc-validator:18.0      # Image containing kc_validator.so
+  instances: 1
+
+  postgresql:
+    parameters:
+      oauth_validator_libraries: "kc_validator"
+      kc.token_endpoint: "https://<keycloak>/realms/<realm>/protocol/openid-connect/token"
+      kc.audience: "postgres-resource"
+      kc.resource_name: "appdb"       # Resource name in Keycloak
+      kc.client_id: "postgres-resource"
+      kc.http_timeout_ms: "2000"
+      kc.expected_issuer: "https://<keycloak>/realms/<realm>"
+      kc.debug: "on"
+      kc.log_body: "on"
+      log_min_messages: "debug1"
+    pg_hba:
+      - host all all 0.0.0.0/0 oauth issuer="https://<keycloak>/realms/<realm>" scope=db_access validator="kc_validator" delegate_ident_mapping=1
+```
+
+For a full example, see `examples/cnpg/cluster.yaml`.
+
+---
+
+## Keycloak Configuration Steps
+
+1. **Realm**
+   Create or use an existing realm (e.g., `demo`).
+
+2. **Resource Server Client** (`kc.audience`)
+   Create a client for Authorization Services (e.g., `postgres-resource`).
+   Enable Authorization Services and add scopes as needed (e.g., `app_readonly`, `app_readwrite`).
+
+3. **Validator Client** (`kc.client_id`)
+   A client allowed to call the token endpoint for permission decisions.
+
+4. **Resource & Permission**
+   Resource name: `<kc.resource_name>` (e.g., `appdb`).
+   Scope name: `<scope>` (e.g., `app_readonly`, `app_readwrite`).
+   Permission name: `<resource_name>#<scope>` (e.g., `appdb#app_readonly`).
+   Create a permission for each database role you want to allow (e.g., DB role `app_readonly` maps to Keycloak scope `app_readonly`, permission name `appdb#app_readonly`).
+
+5. **Policies**
+   Attach policies to permissions so that only intended users can access specific scopes.
+
+6. **Issuer Verification (optional)**
+   Set `kc.expected_issuer` to your realm's issuer URL (e.g., `https://<keycloak>/realms/<realm>`).
+
+---
+
+## Quick Start with psql and Device Flow
+
+You can quickly test the validator using Keycloak's Device Flow and psql:
+
+1. **Connect to PostgreSQL using psql with OAuth parameters:**
+
+    ```bash
+    psql "host=<keycloak> \
+        user=app_readonly \
+        dbname=appdb \
+        oauth_issuer=https://<keycloak>/realms/demo \
+        oauth_client_id=appA \
+        oauth_client_secret=<client secret> \
+        oauth_scope='db_access'"
+    ```
+
+    When you run this command, psql will display a Device Authorization URL and a device code.
+
+2. **Authenticate via browser:**
+
+    - Open the displayed URL in your browser.
+    - Enter the device code shown by psql.
+    - Log in with your Keycloak username and password.
+
+    Once authentication is complete, psql will automatically obtain an access token and connect to the database.
+
+> Note:
+The DB role (`app_readonly`) should match the Keycloak scope name.
+The validator will request permission `<resource_name>#<scope>` (e.g., `appdb#app_readonly`) from Keycloak Authorization Services.
+
+---
+
+## Build Instructions
+
+### Docker
+
+```bash
+docker build -t pg-kc-validator -f docker/Dockerfile .
+```
+
+---
+
+## Security Notes
+
+- Do not use self-signed certificates (server.crt) in production; always use a trusted CA.
+- Enable `kc.log_body` only for debugging; keep it `off` in production.
+- Place CA certificates in `/usr/local/share/ca-certificates/` and run `update-ca-certificates` in your Docker image.
+
+---
+
+## License
+
+Apache-2.0. See `LICENSE`.
+
+---

docker/Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.7
+FROM postgres:18 AS builder
+ARG DEBIAN_FRONTEND=noninteractive
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+    build-essential libcurl4-openssl-dev postgresql-server-dev-18; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+WORKDIR /work
+COPY src/ ./src/
+RUN make -C src
+
+FROM ghcr.io/cloudnative-pg/postgresql:18-standard-trixie
+ARG DEBIAN_FRONTEND=noninteractive
+USER root
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends libcurl4 ca-certificates; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+COPY --chmod=0644 docker/certs/server.crt /usr/local/share/ca-certificates/kc-root.crt
+RUN update-ca-certificates
+ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
+USER postgres
+COPY --from=builder /work/src/kc_validator.so /usr/lib/postgresql/18/lib/

examples/cnpg/cluster.yaml

@@ -0,0 +1,36 @@
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: pg-oauth
+spec:
+  imageName: pg18-kc-validator:18.0
+  instances: 1
+
+  # Bootstrap from scratch and run our init SQL from a ConfigMap
+  bootstrap:
+    initdb:
+      database: appdb
+      owner: app
+      postInitApplicationSQLRefs:
+        configMapRefs:
+          - name: pg-init-sql
+            key: init.sql
+
+  storage:
+    size: 1Gi
+  postgresql:
+    parameters:
+      oauth_validator_libraries: "kc_validator"
+
+      kc.token_endpoint: "https://<keycloak>/realms/<realm>/protocol/openid-connect/token"
+      kc.audience:       "postgres-resource"
+      kc.resource_name:  "appdb"
+      kc.client_id:      "postgres-resource"
+      kc.http_timeout_ms: "2000"
+      kc.expected_issuer: "https://<keycloak>/realms/<realm>"
+      kc.debug: "on"
+      kc.log_body: "on"
+      log_min_messages: "debug1"
+
+    pg_hba:
+      - host all all 0.0.0.0/0 oauth issuer="https://<keycloak>/realms/<realm>" scope=db_access validator="kc_validator" delegate_ident_mapping=1

examples/cnpg/pg-init-sql.yaml

@@ -0,0 +1,66 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: pg-init-sql
+data:
+  init.sql: |
+    -- Create the 'users' table
+    CREATE TABLE IF NOT EXISTS users (
+      id SERIAL PRIMARY KEY,
+      username VARCHAR(50) NOT NULL UNIQUE,
+      email VARCHAR(100) NOT NULL,
+      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Create the 'orders' table
+    CREATE TABLE IF NOT EXISTS orders (
+      id SERIAL PRIMARY KEY,
+      user_id INTEGER REFERENCES users(id),
+      product VARCHAR(100),
+      amount INTEGER,
+      ordered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Insert sample users
+    INSERT INTO users (username, email) VALUES
+      ('alice', 'alice@example.com'),
+      ('bob', 'bob@example.com');
+
+    -- Insert sample orders
+    INSERT INTO orders (user_id, product, amount) VALUES
+      (1, 'Widget', 3),
+      (2, 'Gadget', 5);
+
+    DO $$
+    BEGIN
+      IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'app_readonly') THEN
+        CREATE ROLE app_readonly LOGIN;
+      END IF;
+      IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'app_readwrite') THEN
+        CREATE ROLE app_readwrite LOGIN;
+      END IF;
+    END$$;
+
+    REVOKE CONNECT ON DATABASE appdb FROM PUBLIC;
+    GRANT  CONNECT ON DATABASE appdb TO app_readonly, app_readwrite;
+
+    REVOKE ALL ON SCHEMA public FROM PUBLIC;
+    GRANT  USAGE ON SCHEMA public TO app_readonly, app_readwrite;
+    GRANT  CREATE ON SCHEMA public TO app_readwrite;
+
+    GRANT SELECT ON ALL TABLES IN SCHEMA public TO app_readonly;
+    GRANT SELECT ON ALL TABLES IN SCHEMA public TO app_readwrite;
+    GRANT INSERT ON ALL TABLES IN SCHEMA public TO app_readwrite;
+
+    GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO app_readonly;
+    GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO app_readwrite;
+
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public
+      GRANT SELECT ON TABLES TO app_readonly;
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public
+      GRANT USAGE, SELECT ON SEQUENCES TO app_readonly;
+
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public
+      GRANT SELECT, INSERT ON TABLES TO app_readwrite;
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public
+      GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO app_readwrite;