rafalmasiarek / dashboard-kit-addon-sso
OAuth2/OIDC SSO plugin for dashboard-kit — Authorization Code + PKCE, RS256 JWT, JWKS
Package info
github.com/rafalmasiarek/php-dashboard-kit-addon-sso
pkg:composer/rafalmasiarek/dashboard-kit-addon-sso
Requires
- php: >=8.2
- firebase/php-jwt: ^7.0
- rafalmasiarek/dashboard-kit: >=5.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 23:37:05 UTC
README
OAuth2/OIDC SSO addon for rafalmasiarek/dashboard-kit.
Implements the Authorization Code flow with PKCE and RS256-signed JWTs. Exposes standard OpenID Connect protocol endpoints and an admin UI for managing OAuth2 clients.
License
Business Source License 1.1.
Source available; commercial use restricted until 2099-01-01.
See LICENSE for full details.
For alternative licensing, contact us.
Authors
Requirements
- PHP 8.2+
rafalmasiarek/dashboard-kit: *firebase/php-jwt: ^6.0
Installation
composer require rafalmasiarek/dashboard-kit-addon-sso
Quick start
use rafalmasiarek\DashboardKitSso\SsoAddon; $dashboard = Dashboard::create(__DIR__ . '/../', [ 'sso' => [ 'issuer' => 'https://auth.example.com', ], ]); SsoAddon::register($dashboard->getApp(), $dashboard->getContainer()); $dashboard->run();
An RSA private key is generated automatically at {storage_dir}/private.pem on first boot.
Configuration
| Key | Default | Description |
|---|---|---|
issuer |
— | Required. Base URL of the authorization server, no trailing slash |
access_ttl |
3600 |
Access token lifetime in seconds |
refresh_ttl |
2592000 |
Refresh token lifetime in seconds (30 days) |
storage_dir |
{app.root_dir}/storage |
Directory for private.pem |
Config can be passed as the third argument to register() or via app.config['sso'] in Dashboard::create().
Protocol endpoints
| Endpoint | Method | Description |
|---|---|---|
/.well-known/openid-configuration |
GET | OpenID Connect discovery document |
/oauth/jwks.json |
GET | Public RSA key set (JWKS) |
/oauth/authorize |
GET | Authorization endpoint — redirects to login, then back to client |
/oauth/token |
POST | Token endpoint — exchanges code for access/refresh tokens |
/oauth/userinfo |
GET | Returns claims for the authenticated user |
/oauth/revoke |
POST | Revokes an access or refresh token |
Admin UI
Accessible at {adminPrefix}/sso/clients. Requires admin role.
- List, create, and delete OAuth2 clients
- Each client has a
client_id, optionalclient_secret, and one or more redirect URIs
Database
All tables are created automatically (CREATE TABLE IF NOT EXISTS) on first register() call:
sso_clientssso_auth_codessso_access_tokenssso_refresh_tokens
Token verification (resource server)
Tokens are RS256-signed JWTs. Verify them using the public key from /oauth/jwks.json and any standard JWT library:
use Firebase\JWT\JWT; use Firebase\JWT\JWK; $jwks = json_decode(file_get_contents('https://auth.example.com/oauth/jwks.json'), true); $keys = JWK::parseKeySet($jwks); $payload = JWT::decode($accessToken, $keys);
Index
Classes
AuthorizeHandler—rafalmasiarek\DashboardKitSso\HttpDiscoveryHandler—rafalmasiarek\DashboardKitSso\HttpJwksHandler—rafalmasiarek\DashboardKitSso\HttpRevokeHandler—rafalmasiarek\DashboardKitSso\HttpTokenHandler—rafalmasiarek\DashboardKitSso\HttpUserInfoHandler—rafalmasiarek\DashboardKitSso\HttpRsaKeyManager—rafalmasiarek\DashboardKitSso\KeysAccessTokenRepository—rafalmasiarek\DashboardKitSso\RepositoryAuthCodeRepository—rafalmasiarek\DashboardKitSso\RepositoryClientRepository—rafalmasiarek\DashboardKitSso\RepositoryRefreshTokenRepository—rafalmasiarek\DashboardKitSso\RepositorySsoSchemaProvider—rafalmasiarek\DashboardKitSso\SchemaAuthorizationService—rafalmasiarek\DashboardKitSso\ServicePkceValidator—rafalmasiarek\DashboardKitSso\ServiceTokenService—rafalmasiarek\DashboardKitSso\ServiceSsoAddon—rafalmasiarek\DashboardKitSso
AuthorizeHandler
final class — rafalmasiarek\DashboardKitSso\Http\AuthorizeHandler · source
Handles the OAuth2 authorization endpoint. Validates incoming authorization requests, checks session state, and either redirects unauthenticated users to the login page (storing pending params in session) or issues an authorization code and redirects back to the client. Errors that cannot be redirected (invalid client_id, unregistered redirect_uri) are rendered via the oauth/error.twig template to prevent open-redirect attacks.
Depends on: Twig, Auth, AuthorizationService
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles GET /oauth/authorize. Flow: 1. Extract and validate query parameters. 2. Validate client_id and redirect_uri before any redirect (security boundary). 3. If user is not authenticated, store pending params in session and redirect to /login?from=... 4. If user is authenticated, issue an authorization code and redirect to redirect_uri. |
__construct()
AuthorizeHandler __construct()
public function __construct(Twig $view, Auth $auth, AuthorizationService $authService, string $dashboardPrefix)
| Param | Type | Description |
|---|---|---|
$view |
Twig |
Twig renderer for error and consent pages. |
$auth |
Auth |
AuthKit authentication service. |
$authService |
AuthorizationService |
Authorization flow orchestrator. |
$dashboardPrefix |
string |
URL prefix prepended to /login redirect (e.g. ''). |
handle()
AuthorizeHandler handle()
public function handle(Request $request, Response $response): Response
Handles GET /oauth/authorize. Flow: 1. Extract and validate query parameters. 2. Validate client_id and redirect_uri before any redirect (security boundary). 3. If user is not authenticated, store pending params in session and redirect to /login?from=... 4. If user is authenticated, issue an authorization code and redirect to redirect_uri.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request. |
$response |
Response |
PSR-7 response. |
Returns: Response
DiscoveryHandler
final class — rafalmasiarek\DashboardKitSso\Http\DiscoveryHandler · source
Serves the OpenID Connect discovery document. Responds to GET /.well-known/openid-configuration with a JSON object describing the issuer's supported endpoints, algorithms, and capabilities. This is the entry point for OIDC-compliant clients that auto-discover endpoints.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles GET /.well-known/openid-configuration. |
__construct()
DiscoveryHandler __construct()
public function __construct(string $issuer)
| Param | Type | Description |
|---|---|---|
$issuer |
string |
Base URL of the authorization server (no trailing slash). |
handle()
DiscoveryHandler handle()
public function handle(Request $request, Response $response): Response
Handles GET /.well-known/openid-configuration.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request (unused; only GET is expected). |
$response |
Response |
PSR-7 response to write the discovery document into. |
Returns: Response — JSON response with Content-Type application/json.
JwksHandler
final class — rafalmasiarek\DashboardKitSso\Http\JwksHandler · source
Serves the JSON Web Key Set (JWKS) document. Responds to GET /oauth/jwks.json with the public RSA key in JWK format. External clients and resource servers fetch this endpoint to verify JWT signatures without sharing a secret — no direct coordination needed.
Depends on: RsaKeyManager
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles GET /oauth/jwks.json. |
__construct()
JwksHandler __construct()
public function __construct(RsaKeyManager $keyManager)
| Param | Type | Description |
|---|---|---|
$keyManager |
RsaKeyManager |
RSA key manager that provides the public key in JWK format. |
handle()
JwksHandler handle()
public function handle(Request $request, Response $response): Response
Handles GET /oauth/jwks.json.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request (unused). |
$response |
Response |
PSR-7 response to write the JWKS into. |
Returns: Response — JSON response with Content-Type application/json.
RevokeHandler
final class — rafalmasiarek\DashboardKitSso\Http\RevokeHandler · source
Handles the OAuth2 token revocation endpoint (POST /oauth/revoke). Implements RFC 7009: always returns 200 regardless of whether the token was found, to prevent probing for valid tokens. Supports access_token and refresh_token hints. When the hint is absent or ambiguous, tries both. When a refresh token is revoked, the associated access token JTI is also invalidated. When an access token is revoked, any refresh tokens sharing its JTI are also revoked.
Depends on: TokenService, AccessTokenRepository, RefreshTokenRepository
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles POST /oauth/revoke. Per RFC 7009 the server MUST return 200 even when the token is unknown or already revoked — the goal is idempotent invalidation, not error reporting. |
revoke() |
private | void |
Attempts to revoke the token, trying the hinted type first. If the hint is 'refresh_token', tries refresh revocation then falls back to access token revocation. If the hint is 'access_token' or absent, tries access token revocation then falls back to refresh token revocation. |
revokeAccessToken() |
private | bool |
Decodes the JWT to extract the JTI and revokes the access token record. Also revokes any refresh tokens linked to the same JTI. |
revokeRefreshToken() |
private | void |
Hashes the token and revokes the matching refresh token record. Also revokes the linked access token JTI when the refresh token is found. |
__construct()
RevokeHandler __construct()
public function __construct(TokenService $tokenService, AccessTokenRepository $accessTokens, RefreshTokenRepository $refreshTokens)
| Param | Type | Description |
|---|---|---|
$tokenService |
TokenService |
JWT decoder for access token JTI extraction. |
$accessTokens |
AccessTokenRepository |
Access token revocation store. |
$refreshTokens |
RefreshTokenRepository |
Refresh token revocation store. |
handle()
RevokeHandler handle()
public function handle(Request $request, Response $response): Response
Handles POST /oauth/revoke. Per RFC 7009 the server MUST return 200 even when the token is unknown or already revoked — the goal is idempotent invalidation, not error reporting.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request with form-encoded body. |
$response |
Response |
PSR-7 response. |
Returns: Response — HTTP 200 with empty body.
revoke()
RevokeHandler revoke()
private function revoke(string $token, string $typeHint): void
Attempts to revoke the token, trying the hinted type first. If the hint is 'refresh_token', tries refresh revocation then falls back to access token revocation. If the hint is 'access_token' or absent, tries access token revocation then falls back to refresh token revocation.
| Param | Type | Description |
|---|---|---|
$token |
string |
The opaque or JWT token to revoke. |
$typeHint |
string |
'access_token', 'refresh_token', or '' for auto-detect. |
revokeAccessToken()
RevokeHandler revokeAccessToken()
private function revokeAccessToken(string $token): bool
Decodes the JWT to extract the JTI and revokes the access token record. Also revokes any refresh tokens linked to the same JTI.
| Param | Type | Description |
|---|---|---|
$token |
string |
Encoded JWT access token. |
Returns: bool — True when a revocable access token was found.
revokeRefreshToken()
RevokeHandler revokeRefreshToken()
private function revokeRefreshToken(string $token): void
Hashes the token and revokes the matching refresh token record. Also revokes the linked access token JTI when the refresh token is found.
| Param | Type | Description |
|---|---|---|
$token |
string |
Plain-text refresh token. |
TokenHandler
final class — rafalmasiarek\DashboardKitSso\Http\TokenHandler · source
Handles the OAuth2 token endpoint (POST /oauth/token). Supports two grant types: authorization_code — exchanges a code + PKCE verifier for a token pair. refresh_token — rotates a refresh token for a new pair. All error responses follow RFC 6749 Section 5.2: {"error": "...", "error_description": "..."}
Depends on: AuthCodeRepository, PkceValidator, TokenService
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles POST /oauth/token. Reads application/x-www-form-urlencoded body, dispatches to the appropriate grant handler, and returns a JSON token response or error. |
handleAuthorizationCode() |
private | Response |
Processes the authorization_code grant. Validates: code existence, PKCE verifier, redirect_uri match, client_id match, user active status. On success: fetches the user row and issues a token pair. |
handleRefreshToken() |
private | Response |
Processes the refresh_token grant. Consumes the refresh token via TokenService::refresh(), re-fetches the user to ensure current email and role values are used (never trust stale JWT claims). |
fetchUser() |
private | array{id: string, email: string, role: string, active: int}|null |
Fetches a user row by ID. |
errorResponse() |
private | Response |
Writes a JSON error response following RFC 6749 Section 5.2. |
jsonResponse() |
private | Response |
Encodes $data as JSON and writes it to the response body. |
__construct()
TokenHandler __construct()
public function __construct(AuthCodeRepository $authCodes, PkceValidator $pkce, TokenService $tokenService)
| Param | Type | Description |
|---|---|---|
$authCodes |
AuthCodeRepository |
Authorization code store. |
$pkce |
PkceValidator |
PKCE code verifier validator. |
$tokenService |
TokenService |
Issues and refreshes JWT token pairs. |
handle()
TokenHandler handle()
public function handle(Request $request, Response $response): Response
Handles POST /oauth/token. Reads application/x-www-form-urlencoded body, dispatches to the appropriate grant handler, and returns a JSON token response or error.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request. |
$response |
Response |
PSR-7 response. |
Returns: Response — JSON response.
handleAuthorizationCode()
TokenHandler handleAuthorizationCode()
private function handleAuthorizationCode(array $body, Response $response): Response
Processes the authorization_code grant. Validates: code existence, PKCE verifier, redirect_uri match, client_id match, user active status. On success: fetches the user row and issues a token pair.
| Param | Type | Description |
|---|---|---|
$body |
array<string, mixed> |
Parsed form body. |
$response |
Response |
PSR-7 response. |
Returns: Response
handleRefreshToken()
TokenHandler handleRefreshToken()
private function handleRefreshToken(array $body, Response $response): Response
Processes the refresh_token grant. Consumes the refresh token via TokenService::refresh(), re-fetches the user to ensure current email and role values are used (never trust stale JWT claims).
| Param | Type | Description |
|---|---|---|
$body |
array<string, mixed> |
Parsed form body. |
$response |
Response |
PSR-7 response. |
Returns: Response
fetchUser()
TokenHandler fetchUser()
private function fetchUser(string $userId): ?array
Fetches a user row by ID.
| Param | Type | Description |
|---|---|---|
$userId |
string |
UUID of the user. |
Returns: array{id: string, email: string, role: string, active: int}\|null
errorResponse()
TokenHandler errorResponse()
private function errorResponse(Response $response, string $error, string $errorDescription, int $status): Response
Writes a JSON error response following RFC 6749 Section 5.2.
| Param | Type | Description |
|---|---|---|
$response |
Response |
PSR-7 response. |
$error |
string |
RFC 6749 error code. |
$errorDescription |
string |
Human-readable description. |
$status |
int |
HTTP status code (400 or 401). |
Returns: Response
jsonResponse()
TokenHandler jsonResponse()
private function jsonResponse(Response $response, array $data, int $status): Response
Encodes $data as JSON and writes it to the response body.
| Param | Type | Description |
|---|---|---|
$response |
Response |
PSR-7 response. |
$data |
array<string, mixed> |
Data to encode. |
$status |
int |
HTTP status code. |
Returns: Response
UserInfoHandler
final class — rafalmasiarek\DashboardKitSso\Http\UserInfoHandler · source
Handles the OIDC UserInfo endpoint (GET /oauth/userinfo). Accepts a Bearer access token in the Authorization header, verifies the JWT signature, checks for revocation in the database, then re-fetches the user from the users table to return always-current claims (not cached JWT values).
Depends on: TokenService, AccessTokenRepository
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
handle() |
public | Response |
Handles GET /oauth/userinfo. Validates the Bearer token, checks revocation, fetches the user and returns a JSON object with the claims authorized by the token's scopes. |
errorResponse() |
private | Response |
Writes a JSON error response with WWW-Authenticate header. |
jsonResponse() |
private | Response |
Encodes $data as JSON and writes it to the response body. |
__construct()
UserInfoHandler __construct()
public function __construct(TokenService $tokenService, AccessTokenRepository $accessTokens)
| Param | Type | Description |
|---|---|---|
$tokenService |
TokenService |
JWT decoder using the RSA public key. |
$accessTokens |
AccessTokenRepository |
Revocation check store. |
handle()
UserInfoHandler handle()
public function handle(Request $request, Response $response): Response
Handles GET /oauth/userinfo. Validates the Bearer token, checks revocation, fetches the user and returns a JSON object with the claims authorized by the token's scopes.
| Param | Type | Description |
|---|---|---|
$request |
Request |
Incoming PSR-7 request. |
$response |
Response |
PSR-7 response. |
Returns: Response — JSON user claims or a 401/403 error.
errorResponse()
UserInfoHandler errorResponse()
private function errorResponse(Response $response, int $status, string $error, string $description): Response
Writes a JSON error response with WWW-Authenticate header.
| Param | Type | Description |
|---|---|---|
$response |
Response |
PSR-7 response. |
$status |
int |
HTTP status code. |
$error |
string |
OAuth2 error code. |
$description |
string |
Human-readable error description. |
Returns: Response
jsonResponse()
UserInfoHandler jsonResponse()
private function jsonResponse(Response $response, array $data, int $status): Response
Encodes $data as JSON and writes it to the response body.
| Param | Type | Description |
|---|---|---|
$response |
Response |
PSR-7 response. |
$data |
array<string, mixed> |
Data to encode. |
$status |
int |
HTTP status code. |
Returns: Response
RsaKeyManager
final class — rafalmasiarek\DashboardKitSso\Keys\RsaKeyManager · source
Manages the RSA-2048 key pair used for JWT signing and JWKS publication. Generates the key pair on first use and persists the private key as a PEM file under {storageDir}/sso/private.pem. Subsequent calls load from file. The directory and file are created with mode 0700/0600 respectively.
Depends on: \OpenSSLAsymmetricKey
| Property | Type | Visibility | Description |
|---|---|---|---|
$privateKeyPath |
string |
private | Absolute path to the private key PEM file. |
$privateKey |
\OpenSSLAsymmetricKey|null |
private | In-memory cached private key resource. |
$publicKey |
\OpenSSLAsymmetricKey|null |
private | In-memory cached public key resource. |
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
getPrivateKey() |
public | \OpenSSLAsymmetricKey |
Returns the private key resource for JWT signing. Generates and persists the key pair on first call if the PEM file does not exist. |
getPublicKey() |
public | \OpenSSLAsymmetricKey |
Returns the public key resource for JWT verification and JWKS extraction. |
getJwks() |
public | array{keys: array<int, array{kty: string, use: string, alg: string, kid: string, n: string, e: string}>} |
Returns the JWK Set (JWKS) representation of the public key. The returned array is ready to be JSON-encoded and served at /oauth/jwks.json. The RSA modulus (n) and exponent (e) are base64url-encoded without padding. |
generate() |
private | void |
Generates the RSA-2048 key pair and writes the private key PEM to disk. Creates the storage directory with mode 0700 if it does not exist. The PEM file is written with mode 0600. |
load() |
private | void |
Loads the private key from the PEM file on disk. |
ensureKey() |
private | void |
Ensures the key pair is available, generating it if the PEM file is missing. |
base64url() |
private | string |
Encodes binary data as base64url without padding. |
__construct()
RsaKeyManager __construct()
public function __construct(string $storageDir)
| Param | Type | Description |
|---|---|---|
$storageDir |
string |
Absolute path to the application storage root. |
getPrivateKey()
RsaKeyManager getPrivateKey()
public function getPrivateKey(): \OpenSSLAsymmetricKey
Returns the private key resource for JWT signing. Generates and persists the key pair on first call if the PEM file does not exist.
Returns: \OpenSSLAsymmetricKey
| Throws | When |
|---|---|
RuntimeException |
When the key cannot be generated or loaded. |
getPublicKey()
RsaKeyManager getPublicKey()
public function getPublicKey(): \OpenSSLAsymmetricKey
Returns the public key resource for JWT verification and JWKS extraction.
Returns: \OpenSSLAsymmetricKey
| Throws | When |
|---|---|
RuntimeException |
When the public key cannot be derived. |
getJwks()
RsaKeyManager getJwks()
public function getJwks(): array
Returns the JWK Set (JWKS) representation of the public key. The returned array is ready to be JSON-encoded and served at /oauth/jwks.json. The RSA modulus (n) and exponent (e) are base64url-encoded without padding.
Returns: array{keys: array<int, array{kty: string, use: string, alg: string, kid: string, n: string, e: string}>}
| Throws | When |
|---|---|
RuntimeException |
When key details cannot be extracted. |
generate()
RsaKeyManager generate()
private function generate(): void
Generates the RSA-2048 key pair and writes the private key PEM to disk. Creates the storage directory with mode 0700 if it does not exist. The PEM file is written with mode 0600.
| Throws | When |
|---|---|
RuntimeException |
When key generation or file write fails. |
load()
RsaKeyManager load()
private function load(): void
Loads the private key from the PEM file on disk.
| Throws | When |
|---|---|
RuntimeException |
When the file cannot be read or parsed. |
ensureKey()
RsaKeyManager ensureKey()
private function ensureKey(): void
Ensures the key pair is available, generating it if the PEM file is missing.
base64url()
RsaKeyManager base64url()
private function base64url(string $data): string
Encodes binary data as base64url without padding.
| Param | Type | Description |
|---|---|---|
$data |
string |
Raw binary string. |
Returns: string — URL-safe base64 without trailing '=' characters.
AccessTokenRepository
final class — rafalmasiarek\DashboardKitSso\Repository\AccessTokenRepository · source
Manages access token metadata in the sso_access_tokens table. The actual access token is a signed JWT; this table tracks its JTI (JWT ID) for revocation checks and admin UI listing. The JWT itself is not stored.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
create() |
public | void |
Records an issued access token by JTI. |
find() |
public | array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string|null}|null |
Fetches an access token record by JTI. |
revoke() |
public | void |
Marks an access token as revoked by setting revoked_at to the current time. |
allByUser() |
public | array<int, array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string|null}> |
Returns all non-expired, non-revoked access tokens for a given user. Used by the admin UI to display active sessions. |
allActive() |
public | array<int, array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string|null}> |
Returns all active (non-expired, non-revoked) access tokens across all users. Used by the admin UI token listing. |
create()
AccessTokenRepository create()
public function create(string $jti, string $clientId, string $userId, array $scopes, int $ttlSeconds): void
Records an issued access token by JTI.
| Param | Type | Description |
|---|---|---|
$jti |
string |
UUID v4 used as the JWT 'jti' claim. |
$clientId |
string |
Client that requested the token. |
$userId |
string |
UUID of the authenticated user. |
$scopes |
string[] |
Scopes granted to this token. |
$ttlSeconds |
int |
Lifetime in seconds; used to compute expires_at. |
find()
AccessTokenRepository find()
public function find(string $jti): ?array
Fetches an access token record by JTI.
| Param | Type | Description |
|---|---|---|
$jti |
string |
The JWT ID claim. |
Returns: array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string\|null}\|null — Token row or null when not found.
revoke()
AccessTokenRepository revoke()
public function revoke(string $jti): void
Marks an access token as revoked by setting revoked_at to the current time.
| Param | Type | Description |
|---|---|---|
$jti |
string |
The JWT ID of the token to revoke. |
allByUser()
AccessTokenRepository allByUser()
public function allByUser(string $userId): array
Returns all non-expired, non-revoked access tokens for a given user. Used by the admin UI to display active sessions.
| Param | Type | Description |
|---|---|---|
$userId |
string |
UUID of the user. |
Returns: array<int, array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string\|null}>
allActive()
AccessTokenRepository allActive()
public function allActive(): array
Returns all active (non-expired, non-revoked) access tokens across all users. Used by the admin UI token listing.
Returns: array<int, array{jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string\|null}>
AuthCodeRepository
final class — rafalmasiarek\DashboardKitSso\Repository\AuthCodeRepository · source
Manages short-lived authorization codes in the sso_auth_codes table. Each code is single-use: consume() marks used_at and returns null on any subsequent call, preventing replay attacks.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
create() |
public | void |
Persists a new authorization code. |
consume() |
public | array{code: string, client_id: string, user_id: string, redirect_uri: string, code_challenge: string, code_challenge_method: string, scopes: string, expires_at: string}|null |
Atomically marks a code as used and returns its data. Returns null if the code does not exist, has already been used (used_at IS NOT NULL), or has expired. |
create()
AuthCodeRepository create()
public function create(string $code, string $clientId, string $userId, string $redirectUri, string $codeChallenge, string $method, array $scopes, int $ttlSeconds): void
Persists a new authorization code.
| Param | Type | Description |
|---|---|---|
$code |
string |
Cryptographically random code string. |
$clientId |
string |
The client that initiated the flow. |
$userId |
string |
UUID of the authenticated user. |
$redirectUri |
string |
The redirect URI supplied in the authorization request. |
$codeChallenge |
string |
The PKCE code challenge (base64url-encoded SHA-256 of verifier). |
$method |
string |
Challenge method ('S256' or 'plain'). |
$scopes |
string[] |
Requested scopes. |
$ttlSeconds |
int |
Lifetime of the code in seconds. Default: 600. |
consume()
AuthCodeRepository consume()
public function consume(string $code): ?array
Atomically marks a code as used and returns its data. Returns null if the code does not exist, has already been used (used_at IS NOT NULL), or has expired.
| Param | Type | Description |
|---|---|---|
$code |
string |
The authorization code to consume. |
Returns: array{code: string, client_id: string, user_id: string, redirect_uri: string, code_challenge: string, code_challenge_method: string, scopes: string, expires_at: string}\|null
ClientRepository
final class — rafalmasiarek\DashboardKitSso\Repository\ClientRepository · source
Manages OAuth2 client records in the sso_clients table. Clients are identified by a client_id string. Public clients have no secret (client_secret_hash is NULL) and rely solely on PKCE. Confidential clients store a bcrypt hash of their secret.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
find() |
public | array{client_id: string, client_secret_hash: string|null, name: string, redirect_uris: string, is_active: int, created_at: string}|null |
Fetches a single client row by client_id. |
findAll() |
public | array<int, array{client_id: string, client_secret_hash: string|null, name: string, redirect_uris: string, is_active: int, created_at: string}> |
Returns all registered clients ordered by created_at descending. |
create() |
public | void |
Creates a new OAuth2 client record. When $secret is non-null it is stored as a bcrypt hash. Pass null for public (PKCE-only) clients that authenticate solely via code_verifier. is_active/created_at are left to the schema's own defaults (1 / now). |
syncFromConfig() |
public | void |
Upserts a config-declared client. Unlike create(), this keeps client_secret_hash and is_active untouched on update. |
setActive() |
public | void |
Enables or disables a client without deleting it. |
delete() |
public | void |
Permanently removes a client and all its associated tokens. Note: cascade deletes are not enforced by foreign keys here because the sso_* tables do not cross-reference sso_clients with FK constraints. Callers should revoke tokens separately if required. |
validateRedirectUri() |
public | bool |
Checks whether a redirect URI is registered for a given client. Performs an exact string match against every URI stored in redirect_uris. |
getRedirectUris() |
public | string[] |
Returns the list of allowed redirect URIs for a client. |
find()
ClientRepository find()
public function find(string $clientId): ?array
Fetches a single client row by client_id.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client identifier. |
Returns: array{client_id: string, client_secret_hash: string\|null, name: string, redirect_uris: string, is_active: int, created_at: string}\|null — Client row or null when not found.
findAll()
ClientRepository findAll()
public function findAll(): array
Returns all registered clients ordered by created_at descending.
Returns: array<int, array{client_id: string, client_secret_hash: string\|null, name: string, redirect_uris: string, is_active: int, created_at: string}>
create()
ClientRepository create()
public function create(string $clientId, ?string $secret, string $name, array $redirectUris): void
Creates a new OAuth2 client record. When $secret is non-null it is stored as a bcrypt hash. Pass null for public (PKCE-only) clients that authenticate solely via code_verifier. is_active/created_at are left to the schema's own defaults (1 / now).
| Param | Type | Description |
|---|---|---|
$clientId |
string |
Unique client identifier (e.g. 'swagger-ui'). |
$secret |
string|null |
Plain-text secret to hash; null for public clients. |
$name |
string |
Human-readable display name. |
$redirectUris |
string[] |
Allowed redirect URIs (exact match enforced on use). |
syncFromConfig()
ClientRepository syncFromConfig()
public function syncFromConfig(string $clientId, string $name, array $redirectUris): void
Upserts a config-declared client. Unlike create(), this keeps client_secret_hash and is_active untouched on update.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
Unique client identifier (e.g. 'swagger-ui'). |
$name |
string |
Human-readable display name. |
$redirectUris |
string[] |
Allowed redirect URIs (exact match enforced on use). |
setActive()
ClientRepository setActive()
public function setActive(string $clientId, bool $active): void
Enables or disables a client without deleting it.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client identifier. |
$active |
bool |
True to enable, false to disable. |
delete()
ClientRepository delete()
public function delete(string $clientId): void
Permanently removes a client and all its associated tokens. Note: cascade deletes are not enforced by foreign keys here because the sso_* tables do not cross-reference sso_clients with FK constraints. Callers should revoke tokens separately if required.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client identifier. |
validateRedirectUri()
ClientRepository validateRedirectUri()
public function validateRedirectUri(string $clientId, string $redirectUri): bool
Checks whether a redirect URI is registered for a given client. Performs an exact string match against every URI stored in redirect_uris.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client identifier. |
$redirectUri |
string |
The URI to validate. |
Returns: bool — True when the URI is registered and the client is active.
getRedirectUris()
ClientRepository getRedirectUris()
public function getRedirectUris(string $clientId): array
Returns the list of allowed redirect URIs for a client.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client identifier. |
Returns: string[] — Empty array when client is not found.
RefreshTokenRepository
final class — rafalmasiarek\DashboardKitSso\Repository\RefreshTokenRepository · source
Manages refresh token records in the sso_refresh_tokens table. Refresh tokens are stored as SHA-256 hashes of the opaque token string. The plain token is only held in memory and returned to the client once.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
create() |
public | void |
Persists a new refresh token. The token string is hashed with SHA-256 before storage. |
consume() |
public | array{token_hash: string, jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string|null}|null |
Validates and consumes a refresh token in a single operation. Hashes the plain token, looks it up, checks expiry and revocation status, then marks it as revoked. Returns the token row or null when invalid. |
revokeByJti() |
public | void |
Revokes all refresh tokens associated with a given access token JTI. Called when revoking an access token to also invalidate any refresh token that can produce new access tokens from the same grant. |
create()
RefreshTokenRepository create()
public function create(string $token, string $jti, string $clientId, string $userId, array $scopes, int $ttlSeconds): void
Persists a new refresh token. The token string is hashed with SHA-256 before storage.
| Param | Type | Description |
|---|---|---|
$token |
string |
Plain-text opaque token (returned to client; not stored). |
$jti |
string |
JTI of the corresponding access token. |
$clientId |
string |
Client that owns this refresh token. |
$userId |
string |
UUID of the authenticated user. |
$scopes |
string[] |
Scopes associated with this refresh token. |
$ttlSeconds |
int |
Lifetime in seconds. |
consume()
RefreshTokenRepository consume()
public function consume(string $token): ?array
Validates and consumes a refresh token in a single operation. Hashes the plain token, looks it up, checks expiry and revocation status, then marks it as revoked. Returns the token row or null when invalid.
| Param | Type | Description |
|---|---|---|
$token |
string |
Plain-text refresh token provided by the client. |
Returns: array{token_hash: string, jti: string, client_id: string, user_id: string, scopes: string, expires_at: string, revoked_at: string\|null}\|null
revokeByJti()
RefreshTokenRepository revokeByJti()
public function revokeByJti(string $jti): void
Revokes all refresh tokens associated with a given access token JTI. Called when revoking an access token to also invalidate any refresh token that can produce new access tokens from the same grant.
| Param | Type | Description |
|---|---|---|
$jti |
string |
JTI of the access token. |
SsoSchemaProvider
final class — rafalmasiarek\DashboardKitSso\Schema\SsoSchemaProvider · source
Creates the database tables required by the SSO / OAuth2 system. Tables created: sso_clients - registered OAuth2 clients. sso_auth_codes - short-lived authorization codes for PKCE flow. sso_access_tokens - issued JWT access tokens (tracked for revocation). sso_refresh_tokens - long-lived refresh tokens (stored as SHA-256 hashes). Called directly by SsoAddon::register() on every boot; all statements use IF NOT EXISTS.
Depends on: PDO
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
createSchema() |
public | void |
Runs CREATE TABLE IF NOT EXISTS for all SSO tables. Detects driver via PDO::ATTR_DRIVER_NAME and delegates to the appropriate method. |
createMysql() |
private | void |
Creates all SSO tables for MySQL. |
createSqlite() |
private | void |
Creates all SSO tables for SQLite. |
__construct()
SsoSchemaProvider __construct()
public function __construct(PDO $pdo)
| Param | Type | Description |
|---|---|---|
$pdo |
PDO |
Database connection used to determine driver and execute DDL. |
createSchema()
SsoSchemaProvider createSchema()
public function createSchema(): void
Runs CREATE TABLE IF NOT EXISTS for all SSO tables. Detects driver via PDO::ATTR_DRIVER_NAME and delegates to the appropriate method.
createMysql()
SsoSchemaProvider createMysql()
private function createMysql(): void
Creates all SSO tables for MySQL.
createSqlite()
SsoSchemaProvider createSqlite()
private function createSqlite(): void
Creates all SSO tables for SQLite.
AuthorizationService
final class — rafalmasiarek\DashboardKitSso\Service\AuthorizationService · source
Orchestrates the OAuth2 authorization code flow. Validates the incoming authorization request against registered client data, generates authorization codes, and determines whether a user is authenticated. Kept deliberately thin so that AuthorizeHandler remains the HTTP boundary.
Depends on: ClientRepository, AuthCodeRepository
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
validateRequest() |
public | array{error: string, error_description: string}|null |
Validates the core parameters of an authorization request. Checks: - response_type must be 'code' - code_challenge_method must be 'S256' (plain is not accepted) - client_id must resolve to an active client - redirect_uri must be registered for the client (exact match) Returns an error descriptor on failure, null on success. |
generateCode() |
public | string |
Generates and persists an authorization code for an authenticated user. |
normalizeScopes() |
public | string[] |
Normalizes and filters a space-separated scope string. Unknown scopes are silently dropped. If the result is empty or 'openid' is absent, 'openid' is prepended. |
__construct()
AuthorizationService __construct()
public function __construct(ClientRepository $clients, AuthCodeRepository $authCodes)
| Param | Type | Description |
|---|---|---|
$clients |
ClientRepository |
Client registry for validation. |
$authCodes |
AuthCodeRepository |
Authorization code persistence. |
validateRequest()
AuthorizationService validateRequest()
public function validateRequest(string $responseType, string $clientId, string $redirectUri, string $codeChallenge, string $codeChallengeMethod): ?array
Validates the core parameters of an authorization request. Checks: - response_type must be 'code' - code_challenge_method must be 'S256' (plain is not accepted) - client_id must resolve to an active client - redirect_uri must be registered for the client (exact match) Returns an error descriptor on failure, null on success.
| Param | Type | Description |
|---|---|---|
$responseType |
string |
Must be 'code'. |
$clientId |
string |
The requesting client. |
$redirectUri |
string |
The redirect URI from the request. |
$codeChallenge |
string |
The PKCE code challenge. |
$codeChallengeMethod |
string |
Must be 'S256'. |
Returns: array{error: string, error_description: string}\|null — Null on success.
generateCode()
AuthorizationService generateCode()
public function generateCode(string $clientId, string $userId, string $redirectUri, string $codeChallenge, string $method, array $scopes): string
Generates and persists an authorization code for an authenticated user.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
The client initiating the flow. |
$userId |
string |
UUID of the authenticated user. |
$redirectUri |
string |
Validated redirect URI. |
$codeChallenge |
string |
PKCE challenge value. |
$method |
string |
Challenge method (always 'S256'). |
$scopes |
string[] |
Requested and validated scopes. |
Returns: string — The generated authorization code.
| Throws | When |
|---|---|
\Random\RandomException |
When the system PRNG fails. |
normalizeScopes()
AuthorizationService normalizeScopes()
public function normalizeScopes(string $scopeString, array $allowedScopes): array
Normalizes and filters a space-separated scope string. Unknown scopes are silently dropped. If the result is empty or 'openid' is absent, 'openid' is prepended.
| Param | Type | Description |
|---|---|---|
$scopeString |
string |
Raw space-separated scope input. |
$allowedScopes |
string[] |
Scopes the server supports (e.g. ['openid', 'profile', 'email']). |
Returns: string[] — Deduplicated, validated scope list.
PkceValidator
final class — rafalmasiarek\DashboardKitSso\Service\PkceValidator · source
Validates PKCE (Proof Key for Code Exchange) code verifiers against stored challenges. Supports the S256 method (RECOMMENDED, RFC 7636) and the plain method (fallback). S256 transforms the verifier as: BASE64URL(SHA256(ASCII(code_verifier))).
| Method | Visibility | Returns | Summary |
|---|---|---|---|
validate() |
public | bool |
Validates a code_verifier against a previously stored code_challenge. For S256: computes base64url(sha256(codeVerifier)) and compares to codeChallenge. For plain: compares codeVerifier directly to codeChallenge. |
validate()
PkceValidator validate()
public function validate(string $codeVerifier, string $codeChallenge, string $method): bool
Validates a code_verifier against a previously stored code_challenge. For S256: computes base64url(sha256(codeVerifier)) and compares to codeChallenge. For plain: compares codeVerifier directly to codeChallenge.
| Param | Type | Description |
|---|---|---|
$codeVerifier |
string |
The verifier supplied in the token request (43-128 chars, A-Z a-z 0-9 - . _ ~). |
$codeChallenge |
string |
The challenge stored with the authorization code. |
$method |
string |
Challenge method: 'S256' or 'plain'. |
Returns: bool — True when the verifier satisfies the challenge.
TokenService
final class — rafalmasiarek\DashboardKitSso\Service\TokenService · source
Issues and refreshes OAuth2 token pairs (access token + refresh token). Access tokens are RS256-signed JWTs. Refresh tokens are opaque random strings whose SHA-256 hashes are stored in the database.
Depends on: RsaKeyManager, AccessTokenRepository, RefreshTokenRepository
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
issueTokenPair() |
public | array{access_token: string, refresh_token: string, expires_in: int, token_type: string, scope: string} |
Issues a new access token + refresh token pair for an authenticated user. The 'name' claim is included only when the 'profile' scope is present. The 'email' claim is always included. The JTI is a UUID v4 used for revocation tracking. |
refresh() |
public | array{access_token: string, refresh_token: string, expires_in: int, token_type: string, scope: string}|null |
Rotates a refresh token and issues a fresh token pair. The old refresh token is consumed (revoked) before the new pair is issued. Returns null when the refresh token is invalid, expired, or already used. |
decode() |
public | array<string, mixed>|null |
Decodes and verifies an RS256 JWT using the public key. Returns the decoded payload as an associative array, or null on failure. |
generateOpaqueToken() |
private | string |
Generates a cryptographically secure URL-safe opaque token. |
uuid4() |
private | string |
Generates a version-4 UUID string. |
__construct()
TokenService __construct()
public function __construct(RsaKeyManager $keys, AccessTokenRepository $accessTokens, RefreshTokenRepository $refreshTokens, string $issuer, int $accessTtl, int $refreshTtl)
| Param | Type | Description |
|---|---|---|
$keys |
RsaKeyManager |
RSA key pair manager for JWT signing. |
$accessTokens |
AccessTokenRepository |
Access token persistence. |
$refreshTokens |
RefreshTokenRepository |
Refresh token persistence. |
$issuer |
string |
Issuer URL placed in the 'iss' JWT claim (no trailing slash). |
$accessTtl |
int |
Access token lifetime in seconds. Default: 3600. |
$refreshTtl |
int |
Refresh token lifetime in seconds. Default: 2592000 (30 days). |
issueTokenPair()
TokenService issueTokenPair()
public function issueTokenPair(string $clientId, string $userId, string $email, string $role, ?string $firstName, ?string $lastName, array $scopes): array
Issues a new access token + refresh token pair for an authenticated user. The 'name' claim is included only when the 'profile' scope is present. The 'email' claim is always included. The JTI is a UUID v4 used for revocation tracking.
| Param | Type | Description |
|---|---|---|
$clientId |
string |
Client that requested the tokens. |
$userId |
string |
UUID of the authenticated user. |
$email |
string |
User email address. |
$role |
string |
User role (e.g. 'admin', 'user'). |
$firstName |
string|null |
User first name; null when not available. |
$lastName |
string|null |
User last name; null when not available. |
$scopes |
string[] |
Granted OAuth2 scopes. |
Returns: array{access_token: string, refresh_token: string, expires_in: int, token_type: string, scope: string}
refresh()
TokenService refresh()
public function refresh(string $refreshToken, string $clientId, string $email, string $role, ?string $firstName, ?string $lastName): ?array
Rotates a refresh token and issues a fresh token pair. The old refresh token is consumed (revoked) before the new pair is issued. Returns null when the refresh token is invalid, expired, or already used.
| Param | Type | Description |
|---|---|---|
$refreshToken |
string |
The opaque refresh token supplied by the client. |
$clientId |
string |
Client ID from the token request (must match stored value). |
$email |
string |
Current user email (re-fetched by caller; do not use JWT claims). |
$role |
string |
Current user role. |
$firstName |
string|null |
User first name. |
$lastName |
string|null |
User last name. |
Returns: array{access_token: string, refresh_token: string, expires_in: int, token_type: string, scope: string}\|null
decode()
TokenService decode()
public function decode(string $token): ?array
Decodes and verifies an RS256 JWT using the public key. Returns the decoded payload as an associative array, or null on failure.
| Param | Type | Description |
|---|---|---|
$token |
string |
Encoded JWT string. |
Returns: array<string, mixed>\|null — Decoded claims or null when verification fails.
generateOpaqueToken()
TokenService generateOpaqueToken()
private function generateOpaqueToken(): string
Generates a cryptographically secure URL-safe opaque token.
Returns: string — 43-character base64url string without padding.
| Throws | When |
|---|---|
\Random\RandomException |
When the system PRNG fails. |
uuid4()
TokenService uuid4()
private function uuid4(): string
Generates a version-4 UUID string.
Returns: string — UUID v4 in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
| Throws | When |
|---|---|
\Random\RandomException |
When the system PRNG fails. |
SsoAddon
final class — rafalmasiarek\DashboardKitSso\SsoAddon · source
Wires the OAuth2/OIDC SSO system into a dashboard-kit application.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
register() |
public static | void |
Registers the SSO addon into the Slim application. Must be called after Dashboard::create() has built the container and registered the Twig view, since this method injects template paths into the already-constructed FilesystemLoader. |
syncConfigClients() |
private static | void |
Syncs config-declared OAuth2 clients into sso_clients on every boot. A redirect_uri starting with '/' is resolved relative to $issuer. |
registerProtocolRoutes() |
private static | void |
Registers the public OAuth2 protocol routes. These routes are intentionally outside dashboard-kit's auth middleware because the authorize endpoint handles its own session check internally. |
registerAdminRoutes() |
private static | void |
Registers admin UI routes for SSO client and token management. All routes are protected by AuthMiddleware, CsrfMiddleware, and RoleMiddleware(['admin']). Routes: GET /admin/sso/clients — list clients POST /admin/sso/clients — create client POST /admin/sso/clients/{id}/delete — delete client GET /admin/sso/tokens — list active tokens POST /admin/sso/tokens/{jti}/revoke — revoke token |
register()
SsoAddon register()
public static function register(App $app, ContainerInterface $container, array $config): void
Registers the SSO addon into the Slim application. Must be called after Dashboard::create() has built the container and registered the Twig view, since this method injects template paths into the already-constructed FilesystemLoader.
| Param | Type | Description |
|---|---|---|
$app |
App |
Slim application instance. |
$container |
ContainerInterface |
PHP-DI container from Dashboard::create(). |
$config |
array<string, mixed> |
Addon configuration overrides. |
syncConfigClients()
SsoAddon syncConfigClients()
private static function syncConfigClients(ClientRepository $repo, array $clients, string $issuer): void
Syncs config-declared OAuth2 clients into sso_clients on every boot. A redirect_uri starting with '/' is resolved relative to $issuer.
| Param | Type | Description |
|---|---|---|
$repo |
ClientRepository |
Client repository. |
$clients |
array<int, array{client_id: string, name: string, redirect_uris: string[]}> |
Config-declared clients. |
$issuer |
string |
Full issuer base URL (no trailing slash). |
registerProtocolRoutes()
SsoAddon registerProtocolRoutes()
private static function registerProtocolRoutes(App $app, ContainerInterface $container, string $dashboardPrefix, string $issuer): void
Registers the public OAuth2 protocol routes. These routes are intentionally outside dashboard-kit's auth middleware because the authorize endpoint handles its own session check internally.
| Param | Type | Description |
|---|---|---|
$app |
App |
— |
$container |
ContainerInterface |
— |
$dashboardPrefix |
string |
URL prefix (e.g. '' or '/app'). |
$issuer |
string |
Full issuer URL for the discovery document. |
registerAdminRoutes()
SsoAddon registerAdminRoutes()
private static function registerAdminRoutes(App $app, ContainerInterface $container, string $dashboardPrefix): void
Registers admin UI routes for SSO client and token management. All routes are protected by AuthMiddleware, CsrfMiddleware, and RoleMiddleware(['admin']). Routes: GET /admin/sso/clients — list clients POST /admin/sso/clients — create client POST /admin/sso/clients/{id}/delete — delete client GET /admin/sso/tokens — list active tokens POST /admin/sso/tokens/{jti}/revoke — revoke token
| Param | Type | Description |
|---|---|---|
$app |
App |
— |
$container |
ContainerInterface |
— |
$dashboardPrefix |
string |
URL prefix. |