OBP Keycloak Provider

Keycloak User Storage SPI that authenticates users via the OBP REST API instead of direct database access. No JDBC drivers, no SQL views — authentication delegates entirely to OBP endpoints.

How it works

1. On first request the provider obtains an admin Direct Login token via POST /obp/v6.0.0/my/logins/direct
2. User lookup: GET /obp/v6.0.0/users/provider/{PROVIDER}/username/{USERNAME}
3. Credential verification: POST /obp/v6.0.0/users/verify-credentials (username + password + provider)
4. Only users whose OBP provider field matches OBP_AUTHUSER_PROVIDER are accepted

Required roles on the OBP admin account: CanGetAnyUser, CanVerifyUserCredentials, CanGetOidcClient

Requirements

• Git 2.2.1 or later
• Docker Engine or Docker Desktop 1.9 or later
• Maven 3.8.5 or later
• Java 17 or later

Quick Start

1. Copy and configure environment variables:

   cp env.sample .env
   nano .env

2. Deploy locally:

   ./development/run-local-postgres-cicd.sh
   # or with OBP themes:
   ./development/run-local-postgres-cicd.sh --themed

Key Environment Variables

Variable	Description
OBP API
OBP_API_URL	Base URL of the OBP API instance (e.g. http://localhost:8080)
OBP_API_USERNAME	OBP admin username (must hold required roles)
OBP_API_PASSWORD	OBP admin password
OBP_API_CONSUMER_KEY	Consumer key registered in OBP for Direct Login
OBP_AUTHUSER_PROVIDER	Mandatory — only users with this provider value are authenticated
Keycloak Admin
KEYCLOAK_ADMIN	Keycloak admin username (default: admin)
KEYCLOAK_ADMIN_PASSWORD	Keycloak admin password (default: admin)
Keycloak Database
KC_DB_URL	Keycloak's internal PostgreSQL JDBC URL
KC_DB_USERNAME	Keycloak database user (default: keycloak)
KC_DB_PASSWORD	Keycloak database password
Ports
KEYCLOAK_HTTP_PORT	HTTP port (default: 7787)
KEYCLOAK_HTTPS_PORT	HTTPS port (default: 8443)
KEYCLOAK_MGMT_PORT	Management/health port (default: 9000)

See env.sample for the full reference.

Provider Features

• ✅ User lookup and authentication via OBP REST API
• ✅ Password verification delegated to OBP (verify-credentials)
• ✅ Provider-based user filtering (OBP_AUTHUSER_PROVIDER)
• ✅ Admin token caching with automatic refresh on expiry
• 🔴 User creation / update / deletion — read-only by design (manage users in OBP)

Login to Keycloak

After deploying, open https://localhost:8443.

Default admin credentials:

user: admin
pass: admin

Click the User federation tab — obp-keycloak-provider will be listed.

Identity Provider brokering (e.g. Google OIDC)

Keycloak can also broker external identity providers (Google, etc.) alongside this federation provider. The two are complementary:

• User federation (this provider) sources existing OBP users for lookup and password authentication.
• Identity providers let users sign in through an external IdP.

On a user's first broker login, Keycloak materializes a local user and links the external identity to it. This provider is intentionally not a UserRegistrationProvider, so Keycloak stores brokered IdP users in its own database rather than attempting to create them in OBP. OBP users remain read-only (see Provider Features); brokered IdP users are managed in Keycloak.

If this provider advertised user registration, the first-broker-login flow would route user creation to it and fail with IDENTITY_PROVIDER_FIRST_LOGIN_ERROR, since OBP user creation is not supported from Keycloak.

Documentation

• docs/ONBOARDING.md — local development onboarding (fresh-start guide)
• env.sample — full environment variable reference
• docs/CICD_DEPLOYMENT.md — CI/CD deployment guide
• development/README.md — development scripts documentation