saifulferoz / keycloak-admin-client

v1.0.2 2026-08-28 09:03 UTC

Requires

• php: >=8.2
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0|^2.0
• psr/log: ^1.0|^2.0|^3.0
• psr/simple-cache: ^1.0|^2.0|^3.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.8
• guzzlehttp/psr7: ^2.6
• http-interop/http-factory-guzzle: ^1.2
• phpunit/phpunit: ^10.5|^11.0
• symfony/cache: ^6.4|^7.0|^8.0

Suggests

• guzzlehttp/guzzle: To use Guzzle as PSR-18 HTTP client
• psr/simple-cache-implementation: To cache authentication tokens between requests
• symfony/http-client: To use Symfony HttpClient with PSR-18 adapter

MIT

• Saiful Islam Feroz

Published on Packagist.org on 2026-08-28 09:04 UTC

README

Enterprise-grade, PSR-compliant, standalone PHP client for Keycloak Admin REST API.

Features

• PHP 8.2+ Typed & Immutable: Readonly properties, backed enums, strict types.
• Standards Compliant: Built on PHP-FIG standards (PSR-7, PSR-17, PSR-18 HTTP client, PSR-6/16 cache, PSR-3 logging).
• Proactive OAuth2 Token Lifecycle: Automatic token negotiation, proactive renewal before expiration, and token storage caching.
• Rich Domain Model & Fluent Query Builders: Complete DTO coverage with helper methods, query builders with pagination, exact matching, and attribute filtering.
• Domain Exceptions: Maps HTTP status codes to explicit exceptions (UserAlreadyExistsException, UserNotFoundException, RealmNotFoundException, etc.).
• Comprehensive Resource Coverage:
  • Realms: CRUD, clear user/realm/keys cache.
  • Users: CRUD, search, password reset, send verification/action emails, session logout, realm & client role assignments, group memberships.
  • Groups: CRUD, hierarchy / child groups, members, role assignments.
  • Roles: Realm roles & client roles CRUD, composite roles, user mappings.
  • Clients: CRUD, service account users, client secret regeneration.
  • Identity Providers: Instances CRUD.
  • Attack Detection & Sessions: Brute-force status check/clearing, session invalidation.

Complete User Manual & Use Case Guide

For exhaustive examples, request payloads, query builder options, and domain exception patterns for every single Keycloak endpoint, read the Complete User Manual (USER_MANUAL.md).

Installation

composer require saifulferoz/keycloak-admin-client

Quickstart

use Feroz\KeycloakAdmin\KeycloakClient;
use Feroz\KeycloakAdmin\Model\User\UserRepresentation;
use Feroz\KeycloakAdmin\Query\UserQuery;

// 1. Instantiate client using the fluent builder
$client = KeycloakClient::builder()
    ->withBaseUrl('https://iam.example.com')
    ->withAuthRealm('master')
    ->withDefaultTargetRealm('mycompany')
    ->withClientCredentials('admin-cli', 'your-client-secret')
    ->build();

// 2. Manage Users
$users = $client->users(); // uses default target realm 'mycompany'

// Create a new user
$newUser = UserRepresentation::create('[e-mail]', 'johndoe')
    ->withName('John', 'Doe')
    ->withEmailVerified(true)
    ->withAttribute('department', 'Engineering')
    ->withPassword('TemporaryP@ssword123!', temporary: true);

$userId = $users->create($newUser);

// Query users with pagination and search
$query = UserQuery::create()
    ->withSearch('john')
    ->withEnabled(true)
    ->withPagination(page: 1, perPage: 20);

$results = $users->list($query);
foreach ($results as $user) {
    echo $user->username . ' (' . $user->email . ')' . PHP_EOL;
}

// Reset password
$users->resetPassword($userId, 'NewSecretPassword123!');

// 3. Manage Roles & Groups
$client->users()->addRealmRoleMappings($userId, [
    $client->roles()->getRealmRole('admin')
]);