Download the PHP package keenthekeen/oauth-helper without Composer

keenthekeen/oauth-helper

OAuth 2.0 / OpenID Connect helpers for Laravel apps that sign users in with, and call each other through, a shared authorization server. They work with any standard server; only the user directory is Keycloak-specific, and endpoint defaults follow Keycloak's layout.

Names follow one rule: anything that works with any OAuth server says OAuth (or nothing); only code calling Keycloak-only APIs says Keycloak (Directory\Keycloak\*).

Requires PHP 8.3+ and Laravel 13.

Installation

Environment

OAUTH_JWKS_URL and OAUTH_TOKEN_ENDPOINT default to Keycloak's layout under the issuer ({issuer}/protocol/openid-connect/certs and /token); set them for other servers. The directory's admin URL is derived from a Keycloak issuer ({base}/realms/{realm} → {base}/admin/realms/{realm}) unless KEYCLOAK_ADMIN_URL is set.

To keep existing variable names, publish the config and read them there.

API guard

An access token is accepted when it is signed by the server, unexpired, and its aud contains OAUTH_API_AUDIENCE, or APP_URL or a URL under it (RFC 8707 resource indicators). Tokens for the MCP server's URL are refused. An invalid token leaves the request unauthenticated (401) instead of throwing.

Calling other services

token() throws TokenRequestException when the server refuses, and ConnectionException when it cannot be reached. Add more clients under oauth-helper.clients and pass client: 'name'.

Single sign-on

This module is optional: apps with working session tracking and back-channel logout of their own can keep it.

The login flow stays a Socialite driver (oidc_keycloak from socialiteproviders/openidconnect) and the callback stays in the app, since user provisioning differs per app. The package handles what is around it:

Logout (RP-initiated), e.g. from a Logout event listener, which runs before the session is invalidated:

Back-channel logout: register the route outside the web middleware group (the server sends no cookies or CSRF token), then set https://app/auth/sso/backchannel-logout as the client's back-channel logout URL (Keycloak: Backchannel logout URL).

Migration: php artisan vendor:publish --tag=oauth-helper-migrations. The oidc_sessions table is keyed by the local session ID, not by sid: an app served on several domains gets one local session per domain for the same SSO session, and back-channel logout must destroy all of them.

User directory

UserDirectory is the contract; Directory\Keycloak\KeycloakUserDirectory implements it over the Keycloak Admin REST API and is bound by default. Another server can be supported by binding another implementation.

The directory authenticates as the app's own client (OAUTH_CLIENT_ID). For Keycloak, enable Service accounts on it and give its service account realm-management → view-users; never grant manage-users for searching. Note that anyone holding that client's secret can then read the whole realm's users. To limit that, add a separate client under oauth-helper.clients with only this role and select it with oauth-helper.directory.client.

• Wildcards and quotes typed by users are stripped; the matching is chosen with SearchMode only.
• Queries shorter than directory.min_query_length throw InvalidArgumentException; results are capped at directory.max_results.
• Only attributes listed in directory.attributes leave the package (add e.g. employeeId to read it).
• Results are cached for directory.cache_ttl seconds (0 disables).
• DirectoryException is thrown when the directory refuses (e.g. a missing role) or cannot be reached.

Results are personal data. In each app, authorize searches with a Gate, rate-limit them, log who searched for what, and return only the fields the caller needs.

Keycloak's search matches only username, email, first and last name, not custom attributes such as the Thai name. Check against your Keycloak realm whether a Thai-name search finds anyone before offering it.

Thai names

Claim and attribute names are configured in oauth-helper.thai_name (first_name, last_name by default).

MCP server

For an app serving an MCP server with laravel/mcp, where MCP clients sign users in with the authorization server:

Tokens must carry the MCP server's URL (MCP_RESOURCE_URL, default APP_URL/mcp) in aud and the MCP_REQUIRED_SCOPE scope (default mcp:resources). The user is looked up by the email claim in the configured user model; use McpGuard::resolveUsersUsing(fn (array $claims) => ...) for anything else. Auth::guard('mcp')->isStrongAuth() tells whether the user signed in to the MCP client with strong authentication.

On the server, make the MCP client's tokens carry the MCP server's URL in aud (in Keycloak: an audience mapper, or resource indicator support), and create the mcp:resources client scope with consent required.

Testing

Development