Download the PHP package joandysson/hyperf-oidc without Composer

Hyperf OIDC

Generic OpenID Connect adapter for Hyperf applications.

You can use it to integrate login with any compatible OIDC/OAuth2 provider, including Google, Facebook, GitHub, Microsoft Entra ID, Keycloak, Auth0, Ory Hydra and other providers. Each provider still needs its own client credentials, redirect URI and supported endpoint configuration.

The package handles the common OIDC/OAuth2 calls your application needs:

• build the authorization URL;
• exchange an authorization code for tokens;
• refresh tokens;
• use password grant when your provider allows it;
• use client credentials;
• introspect tokens;
• logout with a refresh token.

It does not include provider-specific admin APIs. User creation, realm management and provider administration should be handled by each provider's own SDK or API.

Requirements

• PHP 8.1 or newer
• Hyperf 3.1
• Composer

Install

Publish Config

The published file is:

Published config:

Configuration Reference

Environment

For a generic provider whose endpoints are directly under the issuer:

For Keycloak:

When discovery is enabled, the adapter reads endpoints from OIDC_ISSUER/.well-known/openid-configuration. If discovery fails or the provider does not expose a specific endpoint, the manual endpoint values are used as fallback. If an endpoint value is an absolute URL, it is used as-is. If it is a relative path, it is appended to OIDC_ISSUER.

For providers where discovery is disabled or unavailable, configure endpoints manually:

Usage

Resolve the adapter from the Hyperf container:

Login URL

Use this URL to redirect the user to the provider login page.

The scope argument appends scopes to the configured default scope. If OIDC_SCOPE is openid, passing scope: 'profile email' sends openid profile email.

Request-specific values such as state, extra scopes and PKCE verifiers are passed as method arguments. The adapter does not store them on the service instance, so it remains safe when resolved as a long-lived container service.

PKCE

PKCE is optional and can be enabled per authorization request:

Store $codeVerifier in the user's session. The login URL will include code_challenge and code_challenge_method=S256.

Authorization Callback

After login, your provider redirects back to OIDC_REDIRECT_URI with a code.

If PKCE was used, pass the stored verifier:

Refresh Token

Password Grant

Only use this flow when your provider and security model explicitly allow it.

Client Credentials

Use this flow for service-to-service authentication.

Token Introspection

The second argument is optional:

Logout

Most providers invalidate the session/token and return 200 or 204.

Multiple Providers

You can configure more than one provider and choose the default one:

The default adapter instance uses the configured default provider. To use a specific provider at runtime, use the factory:

Public Clients

If your provider uses a public client, set client_secret to null:

When the secret is null or empty, the adapter omits client_secret from token, introspection and logout requests.

Returned Responses

All network methods return Psr\Http\Message\ResponseInterface.

Use tokenPayload() when the response must contain access_token:

Exceptions

All package-specific exceptions extend Joandysson\HyperfOidc\Exceptions\OidcException.

Current exception types:

• InvalidConfigException: invalid provider config, missing provider, invalid endpoints.
• InvalidResponseException: invalid JSON or non-object JSON payload.
• MissingTokenException: token payload without a valid access_token.
• DiscoveryException: reserved for strict discovery flows; discovery currently falls back silently.

Guzzle exceptions may still be thrown for transport-level failures.

Testing

Install dependencies:

Run unit tests:

Run static analysis:

Run coverage. This requires a coverage driver such as Xdebug:

The coverage script fails when statement coverage is below 90%.

Notes

• Always validate the state value in your callback route before exchanging the authorization code.
• Use HTTPS in production for your issuer and redirect URI.
• Keep provider-specific admin APIs outside this package.
• Configure Keycloak-specific endpoint paths explicitly; generic defaults are intentionally provider-neutral.