PHPackages blackcube/oauth2 - 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. [HTTP & Networking](/categories/http) 4. / 5. blackcube/oauth2 ActiveLibrary[HTTP & Networking](/categories/http) blackcube/oauth2 ================ OAuth2/JWT toolbox with multi-population support 1.0.0(1mo ago)01↓33.3%1BSD-3-ClausePHPPHP ^8.1 Since Apr 4Pushed 1mo agoCompare [ Source](https://github.com/blackcubeio/oauth2)[ Packagist](https://packagist.org/packages/blackcube/oauth2)[ Docs](https://github.com/blackcubeio/oauth2)[ RSS](/packages/blackcube-oauth2/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (19)Versions (3)Used By (1) Blackcube OAuth2 ================ [](#blackcube-oauth2) OAuth2/JWT toolbox with multi-population support based on BShaffer oauth2 server. [![License](https://camo.githubusercontent.com/6cb285b57819f8de0acfb34923298f4f569f962544e8fe35331da2d163f4e485/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4253442d2d332d2d436c617573652d626c75652e737667)](LICENSE.md)[![Packagist Version](https://camo.githubusercontent.com/27cf6495afefe26ec892401cdb575bbad477df827fc9c871cf91e0a16735f596/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c61636b637562652f6f61757468322e737667)](https://packagist.org/packages/blackcube/oauth2) Installation ------------ [](#installation) ``` composer require blackcube/oauth2 ``` Based On -------- [](#based-on) - [bshaffer/oauth2-server-php](https://github.com/bshaffer/oauth2-server-php) - OAuth2 engine ([documentation](https://bshaffer.github.io/oauth2-server-php-docs/)) - [lcobucci/jwt](https://github.com/lcobucci/jwt) - JWT handling Philosophy ---------- [](#philosophy) This package is a toolbox, not a turnkey solution. It provides interfaces and tools, never concrete implementations. The application that integrates it decides everything: storage, tables, business logic, routes. **Principles:** - Zero imposed tables - Zero imposed storage (no MySQL/Redis in the package) - Multi-population support (admin ≠ customer in the same app) - DRY: scopes can be derived from an existing system (RBAC, config, API...) Configuration ------------- [](#configuration) ### params.php [](#paramsphp) ``` return [ 'blackcube/oauth2' => [ 'name' => 'admin', 'issuer' => 'myapp-admin', 'audience' => 'myapi', 'userQueryClass' => \App\Oauth2\AdminUser::class, 'clientQueryClass' => \App\Oauth2\AdminClient::class, 'refreshTokenQueryClass' => \App\Oauth2\AdminRefreshToken::class, 'cypherKeyQueryClass' => \App\Oauth2\AdminCypherKey::class, 'algorithm' => 'RS256', 'accessTokenTtl' => 3600, // 1h 'refreshTokenTtl' => 2592000, // 30 days 'allowedGrants' => ['password', 'refresh_token'], ], ]; ``` ### di.php [](#diphp) ``` use Blackcube\Oauth2\PopulationConfig; return [ PopulationConfig::class => [ 'class' => PopulationConfig::class, '__construct()' => $params['blackcube/oauth2'], ], ]; ``` Interfaces to Implement ----------------------- [](#interfaces-to-implement) Your application must provide implementations for these interfaces per population: InterfacePurpose`UserInterface`User entity with getId, getIdentifier, queryById, queryByIdentifier, queryByIdentifierAndPassword`ClientInterface`OAuth2 client entity with getId, getSecret, queryById, validateSecret`RefreshTokenInterface`Refresh token entity with save, revoke, queryByToken`ScopeProviderInterface`Available scopes, scopes per client`CypherKeyInterface`Signing keys (RSA/HMAC) with queryById, queryDefaultSupported Grants ---------------- [](#supported-grants) GrantUsagepasswordUser login (mobile, SPA legacy)client\_credentialsService to Service (Node → PHP)authorization\_code + PKCEMobile, modern SPAsrefresh\_tokenToken renewalJWT Claims ---------- [](#jwt-claims) ``` { "sub": "123", "iss": "myapp-admin", "aud": "myapi", "exp": 1234567890, "iat": 1234567800, "scopes": ["category", "node", "order"] } ``` ClaimDescriptionsubSubject - User IDissIssuer - Identifies the populationaudAudience - Token targetexpExpiration timestampiatIssued at timestampscopesGranted scopesAlgorithms ---------- [](#algorithms) AlgorithmTypeUsageRS256Asymmetric**Default** - Multi-servicesRS384AsymmetricMore secure than RS256RS512AsymmetricMaximum securityHS256SymmetricSimple, shared secretHS384SymmetricMore secure than HS256HS512SymmetricMaximum symmetric security**Recommendation:** RS256/RS384/RS512 if multiple services validate tokens. HS\* only if everything stays in the same PHP process. Key Generation -------------- [](#key-generation) ### RSA (RS\*) [](#rsa-rs) ``` # RS256/RS384/RS512 - 2048 bits key (minimum) openssl genrsa -out private.pem 2048 openssl rsa -in private.pem -pubout -out public.pem # RS512 - 4096 bits key (recommended) openssl genrsa -out private.pem 4096 openssl rsa -in private.pem -pubout -out public.pem ``` ### HMAC (HS\*) [](#hmac-hs) ``` # Random 256 bits secret minimum openssl rand -base64 32 > secret.key ``` Middleware Usage ---------------- [](#middleware-usage) ``` use Blackcube\Oauth2\Middlewares\JwtValidatorMiddleware; // In your route configuration Route::get('/api/protected') ->middleware(JwtValidatorMiddleware::class) ->action([ProtectedController::class, 'index']); ``` The middleware injects these attributes into the request: - `jwt` - Full claims array - `userId` - Subject (sub claim) - `population` - Issuer (iss claim) - `scopes` - Granted scopes array What This Package Does NOT Do ----------------------------- [](#what-this-package-does-not-do) - Impose tables - Impose storage (MySQL, Redis, etc.) - Manage RBAC - Decide routes - Impose user/client structure - Manage sessions - Provide views (login, authorize, etc.) License ------- [](#license) BSD-3-Clause. See [LICENSE.md](LICENSE.md). Author ------ [](#author) Philippe Gaultier ### Health Score 37 — LowBetter than 83% of packages Maintenance91 Actively maintained with recent releases Popularity2 Limited adoption so far Community8 Small or concentrated contributor base Maturity43 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 Unknown Total 1 Last Release 43d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/545714?v=4)[pgaultier](/maintainers/pgaultier)[@pgaultier](https://github.com/pgaultier) --- Top Contributors [![pgaultier](https://avatars.githubusercontent.com/u/545714?v=4)](https://github.com/pgaultier "pgaultier (2 commits)") --- Tags psr-7jwtmiddlewareAuthenticationtokenoauth2authorizationmulti-tenantrefresh-tokenmulti-population ### Code Quality TestsCodeception ### Embed Badge ![Health badge](/badges/blackcube-oauth2/health.svg) ``` [![Health](https://phpackages.com/badges/blackcube-oauth2/health.svg)](https://phpackages.com/packages/blackcube-oauth2) ``` ### Alternatives [mezzio/mezzio-authentication-oauth2 OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications. 28483.0k2](/packages/mezzio-mezzio-authentication-oauth2)[mezzio/mezzio-authentication Authentication middleware for Mezzio and PSR-7 applications 121.6M26](/packages/mezzio-mezzio-authentication)[jimtools/jwt-auth PSR-15 JWT Authentication middleware, A replacement for tuupola/slim-jwt-auth 20142.3k3](/packages/jimtools-jwt-auth)[chillerlan/php-oauth A fully transparent, framework agnostic PSR-18 OAuth client. 4210.4k2](/packages/chillerlan-php-oauth)[tkhamez/slim-role-auth Role-based authorization for the Slim framework 1410.3k](/packages/tkhamez-slim-role-auth)[rbdwllr/psr-jwt A PSR 7 compliant JSON Web Token Middleware Library. 1658.0k7](/packages/rbdwllr-psr-jwt) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)