PHPackages hawk-hhg/auth-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. hawk-hhg/auth-client ActiveProject[Authentication & Authorization](/categories/authentication) hawk-hhg/auth-client ==================== A wrapper around the keycloak authentication service to provide a fully fledged authentication and authorization system 1.2.2(6mo ago)182Apache-2.0PHPPHP ^8.3 Since Feb 24Pushed 3mo ago1 watchersCompare [ Source](https://github.com/hawk-digital-environments/hawk-auth-client)[ Packagist](https://packagist.org/packages/hawk-hhg/auth-client)[ RSS](/packages/hawk-hhg-auth-client/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (6)Versions (5)Used By (0) HAWK Auth Client ================ [](#hawk-auth-client) [![codecov](https://camo.githubusercontent.com/12c610e5e1184179e3ed925dddab489c41b1f33c4667354981b8c9a23acef913/68747470733a2f2f636f6465636f762e696f2f67682f4841574b2d4469676974616c2d456e7669726f6e6d656e74732f6861776b2d617574682d636c69656e742f67726170682f62616467652e7376673f746f6b656e3d5a4b5148384c52333145)](https://codecov.io/gh/HAWK-Digital-Environments/hawk-auth-client)[![Create new Release (PHP)](https://github.com/HAWK-Digital-Environments/hawk-auth-client/actions/workflows/php.yml/badge.svg)](https://github.com/HAWK-Digital-Environments/hawk-auth-client/actions/workflows/php.yml) A comprehensive authentication and authorization library that wraps around the Keycloak REST API ( using [hawk-keycloak-auth-server](https://github.com/HAWK-Digital-Environments/hawk-keycloak-auth-server) for additional features). The library provides a sophisticated way to build microservices with secure authentication, authorization, and user management. ### Core Components [](#core-components) - **Authentication Layer**: Handles both stateful (session-based) and stateless (token-based) authentication - **User Management Layer**: Manages users, groups, and roles with efficient caching - **Permission Layer**: Provides fine-grained access control through resource scopes - **Profile Layer**: Manages flexible user profile structures with validation - **Frontend Integration**: TypeScript companion library for seamless client-side integration Features -------- [](#features) ### Authentication [](#authentication) The library provides two authentication approaches: 1. **Stateful Authentication** (Session-based) - Ideal for server-rendered websites - Automatic session management - Built-in token refresh handling - See [stateful-auth example](examples/stateful-auth/index.php) 2. **Stateless Authentication** (Token-based) - Perfect for API implementations - No session state required - Token validation and verification - See [stateless-auth example](examples/stateless-auth/index.php) ### Permission System [](#permission-system) The Guard system provides sophisticated access control: - Resource-based permissions with scopes - Role-based access control - Group hierarchy support - Fine-grained permission checks ``` // Example permission checks $guard->hasAnyRole('admin', 'editor'); $guard->hasAnyGroupOrHasChildOfAny('organization.managers'); $guard->hasAnyResourceScope('document-123', 'read', 'write'); ``` ### Profile Management [](#profile-management) Flexible user profile system with: - Structured field definitions - Field type validation - Admin/User view modes - Grouped fields - Custom field types See the [user-profile example](examples/user-profile/index.php) for implementation details. ### Frontend Integration [](#frontend-integration) TypeScript companion library (`@hawk-hhg/auth-client`) providing: - Event-driven authentication state management - Profile access - Permission checking - Automatic token refresh See the [frontend-api example](examples/frontend-api/index.html) for implementation details. Installation ------------ [](#installation) ### PHP Library [](#php-library) ``` composer require hawk-hhg/auth-client ``` ### JavaScript Companion (Optional) [](#javascript-companion-optional) ``` npm install @hawk-hhg/auth-client ``` Basic Configuration ------------------- [](#basic-configuration) ``` $client = new AuthClient( redirectUrl: 'https://your-app.com/callback', publicKeycloakUrl: 'https://keycloak.example.com', realm: 'your-realm', clientId: 'your-client-id', clientSecret: 'your-client-secret', // Optional: internal Keycloak URL for Docker environments internalKeycloakUrl: 'http://keycloak:8080' ); ``` Examples -------- [](#examples) The library includes several example implementations: - [stateful-auth](examples/stateful-auth/index.php): Session-based authentication - [stateful-auth-force-login](examples/stateful-auth-force-login/index.php): Force login with session-based authentication - [stateless-auth](examples/stateless-auth/index.php): Token-based API authentication - [user-reading](examples/user-reading/index.php): Options for reading users - [user-profile](examples/user-profile/index.php): Profile management - [frontend-api](examples/frontend-api/index.html): Frontend integration - [oauth-flow](examples/oauth-flow/index.php): OAuth authentication flow using the League OAuth2 client - [manage-resources](examples/manage-resources/index.php): Resource management Each example demonstrates a specific use case with detailed comments and working code. The examples come with their own `docker-compose.yml` file you can use to start them locally. Just run `docker-compose up` (or `bin/env up` for more features) in the example directory and open the `http://localhost:8099` URL in your browser. Note, that you must modify the environment variables in the `docker-compose.yml` file to match your Keycloak setup. Alternatively, if you are using the [HAWK Keycloak Infrastructure](https://github.com/HAWK-Digital-Environments/hawk-keycloak-infrastructure), you can copy the `docker-compose.keycloak.yml` file to `docker-compose.override.yml` and start the environment with `docker compose up`. Development Setup ----------------- [](#development-setup) ### CLI Interface [](#cli-interface) The library comes with a powerful CLI interface (`bin/env`) built with bashly, providing commands for development and testing: ``` # Start the environment bin/env up # Starts containers in daemon mode bin/env up -f # Starts containers with attached output # Container management bin/env stop # Stop containers bin/env restart # Restart containers bin/env down # Remove containers bin/env clean # Remove container images # Development tools bin/env logs [service] # View container logs bin/env ssh [service] # SSH into a container bin/env composer [...args] # Run composer commands # Testing bin/env test unit # Run unit tests bin/env test unit -c # Generate coverage report # Frontend bin/env frontend build # Build TypeScript library bin/env frontend watch # Watch TypeScript files ``` ### Docker Setup [](#docker-setup) The library includes Docker support for development and testing. To use the demo environment: 1. Clone the [HAWK Keycloak Infrastructure](https://github.com/HAWK-Digital-Environments/hawk-keycloak-infrastructure) 2. Copy `docker-compose.keycloak.yml` to `docker-compose.override.yml` 3. Start the environment: ``` bin/env up ``` The demo environment automatically starts the examples for you which you can access at `http://localhost:8099`. Testing ------- [](#testing) ``` # Run unit tests bin/env test unit # Generate coverage report bin/env test unit -c ``` Postcardware ------------ [](#postcardware) You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. ``` HAWK Fakultät Gestaltung Interaction Design Lab Renatastraße 11 31134 Hildesheim ``` Thank you :D ### Health Score 40 — FairBetter than 88% of packages Maintenance74 Regular maintenance activity Popularity11 Limited adoption so far Community8 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~80 days Total 4 Last Release 207d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/c0356afb258572c8908df3132ea59545b7642a6b77fd90bc54215e506c42bfb7?d=identicon)[neunerlei](/maintainers/neunerlei) ![](https://www.gravatar.com/avatar/d7f7b4ced5631458f5b870eacc9aaca66d41cfe9b7fa93e60c18b2029008d584?d=identicon)[DigitalEnvironments](/maintainers/DigitalEnvironments) --- Top Contributors [![Neunerlei](https://avatars.githubusercontent.com/u/22350956?v=4)](https://github.com/Neunerlei "Neunerlei (33 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/hawk-hhg-auth-client/health.svg) ``` [![Health](https://phpackages.com/badges/hawk-hhg-auth-client/health.svg)](https://phpackages.com/packages/hawk-hhg-auth-client) ``` ### Alternatives [simplesamlphp/saml2 SAML2 PHP library from SimpleSAMLphp 30317.2M40](/packages/simplesamlphp-saml2)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1225.3M72](/packages/web-auth-webauthn-lib)[web-auth/webauthn-framework FIDO2/Webauthn library for PHP and Symfony Bundle. 50570.7k1](/packages/web-auth-webauthn-framework)[tempest/framework The PHP framework that gets out of your way. 2.1k23.1k9](/packages/tempest-framework)[thenetworg/oauth2-azure Azure Active Directory OAuth 2.0 Client Provider for The PHP League OAuth2-Client 2509.6M48](/packages/thenetworg-oauth2-azure)[heptacom/shopware-platform-admin-open-auth Shopware plugin to allow OAuth providers to provide admin logins 35133.7k](/packages/heptacom-shopware-platform-admin-open-auth) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)