Download the PHP package ph-ab/keycloak-sso without Composer

keycloak-sso

A small, reusable Keycloak SSO login service for Laravel. Drop it into any project to authenticate users against Keycloak with the OpenID Connect Resource Owner Password grant — token exchange, userinfo, refresh, and logout — with clean, typed error handling.

Extracted from the PH AB API so every project shares one battle-tested SSO implementation instead of copy-pasting the controller logic.

Features

• One-call login: KeycloakSso::login($username, $password).
• Typed exceptions that separate wrong password from SSO is down from SSO is unreachable — so your UI can show the right message and HTTP code.
• Pluggable config resolver — reads .env out of the box; swap in your own (e.g. a system_configs DB table) without touching the package.
• Optional DB-password fallback hook — when Keycloak rejects a credential, let the app try its own legacy users table.
• Structured logging to a configurable channel.
• Token refresh(), logout(), and standalone userInfo().

Requirements

• PHP ^8.2
• Laravel 11 or 12

Installation

The service provider and KeycloakSso facade are auto-discovered. Publish the config file if you want to edit it:

Configuration

Set credentials in .env. The active connection is picked by app()->environment(), falling back to the default connection.

Usage

Other operations:

Optional: DB-password fallback

When Keycloak positively rejects a credential, the manager can ask your app to verify it locally (handy while migrating users into Keycloak). Point the fallback config at an invokable class:

You can also set it at runtime: KeycloakSso::fallbackUsing(fn ($u, $p) => ...).

Load credentials from the database (or anywhere)

The package never touches your database schema. When you want credentials to come from a DB table (or an API, a secrets manager, …), you provide the query and the package just calls it. Pick whichever style you prefer.

No migration, no table, no column config. Your schema stays entirely yours.

Option A — a callback (quickest)

Set the resolver to CallbackConnectionResolver and write your query under credentials. It receives the environment and returns the four values:

That's the whole integration — KeycloakSso::login() now reads from your table. The callback may also return a ConnectionConfig directly.

Priority: by default .env wins — the env-driven connections are used first, and your credentials callback only fills in what .env is missing. This is safe for gradual migration and local overrides. Leave credentials null and .env is used exactly as before.

Want the callback (DB) to win instead? Set credentials_priority => true. Then your query is used first and .env becomes the fallback.

Either way, the same resolver covers both sources — no need to switch resolver back and forth.

If you use php artisan config:cache, point credentials at an invokable class name instead of a closure (closures can't be cached):

Option B — a full resolver class (most control)

For caching, decryption, fallbacks, or anything custom, implement ConfigResolver yourself and point resolver at it:

Both options are validated by ConnectionConfig::fromArray(), so a missing value fails loudly instead of silently logging in against a broken config.

Publishing to Packagist

1. Push this directory to its own public Git repository.
2. Tag a release: git tag v1.0.0 && git push --tags.
3. Submit the repo URL at https://packagist.org/packages/submit and enable the GitHub/Bitbucket hook so new tags auto-update.

The package contains no secrets — all credentials come from the consuming app's .env or config — so it is safe to publish publicly.

License

MIT