Download the PHP package dskripchenko/laravel-oidc without Composer

dskripchenko/laravel-oidc

OpenID Connect for Laravel, without a JOSE library:

• Sign-in through the authorization code flow with PKCE (S256), a state and a nonce kept in the session, the ID token validated against the issuer's JWKS, then the person's userinfo.
• Provider access tokens for an API: an outside client signed in through the same provider calls the API with the provider's token (a JWT), checked against the issuer's JWKS — RS256/384/512 and ES256/384/512 only, never none or HMAC.
• Groups from the provider: the claim read, a "blocked" group, roles from group=role pairs, and a freshness rule for tokens without groups.

The package does not decide who the person is in your application: who a subject is, what groups do and what a provider's token may do are yours, through two small contracts.

PHP 8.3+, Laravel 11–13, ext-openssl.

Install

The provider's endpoints come from <issuer>/.well-known/openid-configuration. The document is kept an hour and taken only when its issuer is the configured one.

Sign-in

The routes and the session are yours; SignInFlow does the protocol.

UserInfo has subject, email (lower case), emailVerified, name (name, else preferred_username), groups (the OIDC_GROUPS_CLAIM claim, null when absent) and the raw claims. verifiedEmail() returns the email only when the provider says email_verified: true — an address it does not vouch for may be anyone's typing and must not match an account.

The state and the nonce are taken out of the session, so a callback works once. finish() requires an ID token in the token response and validates it (OpenID Connect Core, 3.1.3.7) before the userinfo is read:

The leeway is OIDC_ID_TOKEN_LEEWAY seconds (oidc.id_token_leeway, 60 by default): the clock difference forgiven between this server and the provider. The validated claims are in $result->idToken.

Calling APIs on behalf of the person

An application that calls another API with the person's access token (a backend for its own frontend) keeps the tokens of the sign-in on the server:

Store them encrypted, next to the session, and never send them to the browser. When the access token expires, trade the refresh token:

The provider refuses the refresh token (refresh_rejected, any 4xx answer) of a person it blocked or signed out, or of a session it ended — so an application that refreshes on its own schedule follows a block within the access token's lifetime. OidcClient::tokens() returns the same refresh token and lifetime in its array; exchange() gives the TokenSet.

Provider access tokens in an API

A bearer that looks like a JWT is checked; any other bearer passes through to your own tokens. A JWT that does not pass gets 401 (TokenRejected), never a second try as something else. A token is taken when:

OIDC_API_AUDIENCE equal to OIDC_CLIENT_ID is ignored — a token for your own sign-in is not one for the API — unless OIDC_API_AUDIENCE_SAME_AS_CLIENT=true. Providers that type access tokens JWT (Keycloak) need OIDC_API_TOKEN_TYPES=at+jwt,JWT; the audience and the client list still keep their ID tokens out.

JWKS. The same keys as for ID tokens (IssuerKeys). Fetched from the discovery document's jwks_uri through the OutboundHttp contract and kept an hour. An unknown kid refetches at most once a minute: a rotated key is picked up, a stream of made-up key IDs does not make the server call out. A failed fetch is remembered for 30 seconds.

Rate limit. After 30 rejected tokens from one address in a minute the address gets 429 (TooManyAttempts, Retry-After). A genuine token — signed by the provider, for your audience and a known client — that is still refused (expired, not_yet, subject, groups_stale) is counted for its holder, the client and the person, not for the address: a service calling on behalf of many people from one address is not slowed down for all of them because of a few. Claims of a token that did not pass the signature, issuer, audience and client checks are never trusted for this. The first 5 rejections of a minute (per address or holder) dispatch ProviderTokenRejected with the reason and the IP — never the token or its claims — for your audit log.

The token grants nothing by itself: decide what a request with ProviderAccessToken::of($request) !== null may do. Do not mint your own long-lived tokens from it: they would outlive the provider's token and its block.

Groups

decide() gives a role to a member of one of its groups, takes over a role held by hand when the person joins its group, and takes back only a role the provider gave — never one given by hand. You store where a role came from and apply the change.

With a groups claim in an access token, GroupSync::sync() runs as at a sign-in (once a minute per person and set of groups); returning false — a blocked person — rejects the token. A token without the claim is taken only while GroupSync::syncedAt() is within OIDC_API_SYNC_MAX_AGE hours (24), and only if GroupSync::followsGroups().

Contracts

Exceptions

All implement Exceptions\OidcException with a short reason(): ProviderError (discovery, endpoint, token, refresh, refresh_rejected, userinfo, callback), StateMismatch (state), TokenRejected (401, reasons above), TooManyAttempts (429).

Testing

License

MIT. See LICENSE.