Download the PHP package xzawed/keycloak-sdk without Composer

Keycloak SDK for PHP

An idiomatic PHP SDK for Keycloak covering both OIDC/OAuth2 authentication and the Admin REST API behind one consistent facade.

Part of a nine-language polyglot SDK (Java · Python · Node · Go · C# · PHP · Rust · Ruby · Kotlin) — one API shape, nine idioms: github.com/xzawed/KeyCloakSDK.

1.4.0 is on Packagist — composer require xzawed/keycloak-sdk resolves 1.4.0 under Composer's default minimum-stability: stable. A minor release on top of 1.3.0. Security: token, introspection and logout responses — on clientCredentialsToken(), refresh(), exchangeCode(), introspect(), logout(), ClientCredentialsTokenProvider::getToken() and the admin client's own token grant — are now read once, only up to 1,048,576 bytes (after gzip); a usable token padded with 32 MiB of JSON whitespace used to be accepted whole, and a body larger than memory_limit ended the process with an uncatchable fatal error. The cap is 16 times the longest bearer a default Keycloak 26.6 accepts, so no token a server accepts is refused; a larger response — even under a 4xx status — throws KeycloakTransportError (token response exceeds 1048576 bytes and the like), and the admin client sends no admin request. ⚠️ A call through raw() whose token response is over the cap now gets a Guzzle RequestException (catchable as GuzzleException) and sends no admin request, where it used to accept the response; a token, introspection or logout body that cannot be read is now a KeycloakTransportError (… response could not be read). An admin error raised because the access token holds a CR or LF no longer quotes that bearer token in its cause's message — the message is withheld and the original class name kept. Fixed: an OAuth error that ends in a newline is no longer taken as an error code — the messages and oauthError carry it only when it is exactly [a-z_]{1,64}, so the log line that prints the error no longer splits in two. Added: the class constant Xzawed\Keycloak\Admin\ErrorTranslation::TOKEN_PATH, private until now, is public — the one addition to the public API, and the reason this release is a minor one.

⚠️ Coming from 0.1.0? roles()->update() changed signature. It takes the current name as its first argument — update(string $name, Role $role) — because the old one-argument form could not express a rename at all. See Upgrading from 0.1.0.

Requirements

• PHP 8.3+ (composer.json requires ^8.3)
• Keycloak server 26.6.x (verified by the integration suite)

Install

The SDK is developed in the php/ directory of a polyglot monorepo, and Packagist cannot install from a subdirectory. Releases are therefore subtree-split into the dedicated read-only repository xzawed/keycloak-sdk-php, which is what Packagist reads — the package name stays xzawed/keycloak-sdk:

Quickstart

KeycloakClient::create() assembles auth immediately (no network); admin() is created lazily on first call and needs a client secret. Value types are final readonly class, and failures throw the KeycloakException hierarchy.

Audience: validation requires the token's aud to contain clientId. A stock realm does not put the client id in a client-credentials token's aud, so on a default realm either pass expectedAudience: 'my-api' (the audience your realm actually issues), or add an Audience protocol mapper to the client in Keycloak.

Admin failures surface as KeycloakNotFoundError / KeycloakConflictError / KeycloakForbiddenError (all carrying KeycloakAdminError::getStatusCode()), network failures as KeycloakTransportError. admin()->raw() is the escape hatch to the underlying typed client.

Security defaults

• Algorithm pinning — the accepted JWT signature algorithms are pinned (RS256 by default, configurable via signatureAlgorithms:); the header-supplied alg, including none, is never trusted. The SDK decodes the raw header segment itself to gate on alg before verification, because firebase/php-jwt only fills its &$headers out-parameter after a successful decode.
• Hardened claims — exact iss match, aud containment check, mandatory exp (a token without one is rejected), and a bounded clock skew (clockSkew:, default 30s).
• DoS-safe JWKS — a refetch is triggered only by an unresolved key ID (rotation) and never by a bad signature, and is rate-limited by jwksMinRefetchSeconds: (default 30s) — so once the key set has been fetched, no volume of forged random kids makes the SDK issue more than one JWKS request per interval. A failed fetch is bounded separately: consecutive failures back off exponentially (0.2s, doubling, capped at 5s, with jitter), and inside that window the SDK fails fast without contacting the IdP. So a cold cache during an IdP outage no longer turns every validation into a request (measured: 20 attempts → 1 request, down from 20). ⚠️ The SDK never sleeps — it returns the error immediately, so retry pacing stays the caller's decision. ⚠️ Like the refetch gate itself, this state is per-instance: under classic PHP-FPM a fresh store is built per request, so the bound holds within one request.
• OIDC nonce / id_token replay protection — createAuthorizationRequest() always issues a cryptographic nonce, puts it on the authorization URL, and returns it on AuthorizationRequest::$nonce. Pass that value as the optional third argument to exchangeCode() and the SDK fully validates the id_token (signature · iss · aud · exp) before comparing the nonce claim. The id_token's aud must contain clientId (OIDC Core §3.1.3.7) — expectedAudience narrows access-token validation only, so overriding it does not break the exchange. Omit it and id_token validation is skipped (same opt-out as the other eight languages).
• Secret handling — KeycloakConfig, TokenSet and AuthorizationRequest mask secrets, tokens and the PKCE verifier fully (***, no prefix) in both __toString() and json_encode() (all three implement JsonSerializable); TLS verification is on by default and both connect and read timeouts are always applied.

Two scope limits worth knowing. The JWKS cache and its rate limit are per-JwksStore in-memory state, so their reach follows your deployment model: under a long-running worker (Swoole, RoadRunner) they span requests, but under classic PHP-FPM every request builds a fresh store and the limit only binds within that one request. And masking covers this SDK's own __toString() and json_encode(), plus the engine dumps that honour __debugInfo() — var_dump(), print_r() and debug_zval_dump(). It does not cover var_export(), which reads the properties directly and prints the raw value. (⚠️ This line used to say var_dump() and print_r() printed the raw value too; __debugInfo() is implemented on the masked types and SECURITY.md already said so.) PHP also has no erasable string type, so the client secret lives in an ordinary string for its lifetime: masking is defence in depth, not a guarantee about your logs.

Upgrading from 0.1.0

One signature changed, and it is a fix rather than a rearrangement.

roles()->update(Role $role) became roles()->update(string $name, Role $role). The old form took only the representation, and the library underneath builds the request path out of $role->getName() — so the path and the body came from the same value and a rename could not be expressed. Measured on 0.1.0: asking to rename old-name to new-name sent PUT /roles/new-name with body {"name":"new-name"}, and the current name appeared nowhere in the request. Keycloak renames with PUT /{current name} carrying the new name in the body, so that request was not a rename — it was an update aimed at a role that does not exist yet.

The other eight language SDKs always took (name, representation); this brings PHP back in line with them. Nothing else changed — users(), clients(), realms() and groups() already took a separate identifier and are untouched.

Upgrading from 0.1.0-rc.1

0.1.0-rc.2 adds OIDC nonce so id_token replay can be detected, which changes two signatures. One of them can break your code:

1. new AuthorizationRequest(...) gains a required string $nonce. If you construct this type by hand you will get a TypeError for the missing argument. Let the SDK build it instead — $client->auth()->createAuthorizationRequest(...) returns a fully populated instance. Reading fields off the returned object is unaffected (a field was added, none removed).
2. exchangeCode() gains an optional third argument. Two-argument calls keep working unchanged — but that path still does not verify the id_token. To get replay protection, pass the nonce you were given: exchangeCode($code, $verifier, $req->nonce).

Versioning and support

This SDK is 1.0 and follows SemVer: a breaking change to the public API requires a major bump. That promise is machine-backed — CI diffs this lane's public API against the previously published artifact on every build (php-semver-checker, judged on its report body), and a removal or an incompatible change fails the build. ⚠️ The gate compares the API surface. A change that leaves the surface identical but alters behaviour is not caught by it, so read the release notes before upgrading.

Only the newest released version of each language SDK receives security fixes; there are no long-term-support lines and older releases are not backported to.

Each of the nine languages versions independently. All nine reached 1.0.0 in the same release wave because they earned the same guarantee at the same time — they do not move in lockstep afterwards.

Documentation

• Project overview — all nine languages, what is identical and what is not
• Changelog — read this before upgrading; breaking changes are listed per language
• Getting started — install and quickstart for this language
• Compatibility — which Keycloak server range and base libraries each published version shipped against
• Full PHP example
• Deploying a Keycloak server
• Security policy

License

Apache-2.0