Search by

rafalmasiarek / dashboard-kit-addon-sso

rafalmasiarek

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

Statistics

Installs: 29

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 1

v1.3.2 2026-11-01 18:33 UTC

README

Packagist Version Total Downloads PHP License

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

License: BUSL-1.1

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, optional client_secret, and one or more redirect URIs

Database

All tables are created automatically (CREATE TABLE IF NOT EXISTS) on first register() call:

  • sso_clients
  • sso_auth_codes
  • sso_access_tokens
  • sso_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

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()

source

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()

source

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()

source

public function __construct(string $issuer)
Param Type Description
$issuer string Base URL of the authorization server (no trailing slash).
handle()

DiscoveryHandler handle()

source

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()

source

public function __construct(RsaKeyManager $keyManager)
Param Type Description
$keyManager RsaKeyManager RSA key manager that provides the public key in JWK format.
handle()

JwksHandler handle()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

public function __construct(string $storageDir)
Param Type Description
$storageDir string Absolute path to the application storage root.
getPrivateKey()

RsaKeyManager getPrivateKey()

source

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()

source

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()

source

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()

source

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()

source

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()

source

private function ensureKey(): void

Ensures the key pair is available, generating it if the PEM file is missing.

base64url()

RsaKeyManager base64url()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

public function __construct(PDO $pdo)
Param Type Description
$pdo PDO Database connection used to determine driver and execute DDL.
createSchema()

SsoSchemaProvider createSchema()

source

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()

source

private function createMysql(): void

Creates all SSO tables for MySQL.

createSqlite()

SsoSchemaProvider createSqlite()

source

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()

source

public function __construct(ClientRepository $clients, AuthCodeRepository $authCodes)
Param Type Description
$clients ClientRepository Client registry for validation.
$authCodes AuthCodeRepository Authorization code persistence.
validateRequest()

AuthorizationService validateRequest()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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.