Download the PHP package ronu/laravel-federated-auth without Composer

Laravel Federated Auth

Production-ready federated authentication bridge for Laravel 11/12/13, OAuth2, OpenID Connect, Socialite, Apple, Keycloak and custom multi-tenant user systems.

Overview

ronu/laravel-federated-auth is a contract-first Laravel package for integrating external identity providers into real Laravel applications without forcing a specific user model, database schema, guard, token system or tenancy strategy.

It is designed for applications where social login is not enough:

• custom users tables;
• UUID or non-standard primary keys;
• multi-tenant identity links;
• Client, Admin, Veterinarian, Technician or other user types;
• JWT/API guards instead of session auth;
• custom role and permission systems;
• Keycloak or enterprise OIDC;
• native/mobile clients sending id_token directly;
• Apple private relay emails;
• secure redirect flows with package-managed state, plus OIDC nonce and PKCE where the adapter controls the code flow.

Supported providers

Architecture

The provider proves external identity. Your Laravel application owns the local user, tenant scope, roles, account status, local token and response format.

Sequence diagrams

The following diagrams trace the full request pipeline end to end, from the HTTP entry point through FederatedAuthBroker and the extension contracts down to the JSON response.

Both use the browser redirect flow. The native / mobile token flow (POST /{provider}/token → loginFromToken()) skips the redirect and state-consumption phases (steps 1–2) and enters the broker at authenticateIdentity() — every step from validateIdentity() onwards is identical.

Login — returning user (existing identity)

An external identity that is already linked to a local user. The broker resolves the user, enforces account status, touches the link and issues a local token. No user is created (was_provisioned=false, was_linked=false).

Registration — first-time user (auto-provision)

No linked identity exists. After the security validations, the broker optionally matches by verified email, then provisions a new local user (only when auto_provision is enabled), creates the identity link and issues a token (was_provisioned=true, was_linked=true).

Diagrams are generated as standalone SVGs under docs/diagrams.

Installation

federated-auth:migrate runs the package's identity-store migration from inside the package (via --path) without triggering any pending host-app migrations. Supported flags: --rollback, --refresh, --status, --database=, --force, --pretend.

Prefer to manage the schema yourself? Publish the migration into your app and run the standard migrate instead:

Optional documentation publish:

Requirements

Laravel 13 applications require PHP ^8.3, while the package remains installable on PHP ^8.2 when used with Laravel 11 or 12.

Quick configuration

Providers may receive additional authorization-screen parameters from their server-side provider configuration:

This is opt-in and supported by both Socialite-backed and generic OIDC providers. The package filters invalid values and never permits these parameters to override state, nonce, PKCE, client credentials, redirect URI, response type/mode or scopes. For Google, prompt=select_account keeps the user's global Google session open while requiring an explicit account choice for each new application login.

Routes

Browser redirect flow

Provider callbacks usually return only code and state. The package restores the original application context from the consumed state before resolving or creating a provider identity link.

Important security scope: Socialite-backed redirect providers such as Google and Facebook get package-managed one-time state validation. OIDC nonce validation and PKCE are applied by OIDC-style adapters that control the code flow, such as Apple, Keycloak and generic OIDC providers.

Native / mobile token flow

Mobile clients can authenticate using the provider SDK and send the provider token to Laravel.

OIDC token handling is explicit:

Response example

The response is configurable through AuthResponseFormatterInterface, so you can expose only safe user fields.

Security posture

The package is secure-by-design for redirect and token flows, with provider-specific coverage:

• all package-managed redirect flows can use one-time OAuth state;
• all package-managed redirect flows can reject replay through state consumption;
• all package-managed redirect flows can use optional user-agent/IP fingerprint binding;
• Apple, Keycloak and generic OIDC code flows can use OIDC nonce validation;
• Apple, Keycloak and generic OIDC code flows can use PKCE;
• redirect host validation protects dynamic redirect URIs;
• tenant-aware callback context restoration prevents callback logins from losing tenant scope;
• native/mobile OIDC token flows preserve explicit id_token vs access_token handling;
• provider tokens are not stored by default;
• public social providers should not auto-provision privileged users.

Recommended production settings:

FEDERATED_AUTH_PKCE_ENABLED and FEDERATED_AUTH_OIDC_NONCE_ENABLED affect OIDC-style adapters that control the code flow. Socialite-backed providers such as Google and Facebook still receive package-managed state, but package-level nonce/PKCE is not applied there unless a dedicated adapter controls that provider flow.

FEDERATED_AUTH_OIDC_CLOCK_SKEW_SECONDS is a small tolerance for normal clock differences between the application server and the identity provider. The Google PKCE adapter applies it only while validating the provider id_token and restores the JWT library's previous global leeway afterwards. Keep the default small and synchronize the server clock; do not use a large value to hide a clock that is out of sync.

Multi-channel applications: trusted route context

AuthContext::fromRequest() reads channel, user_type, tenant_id and guard from the request body, query string or headers. That is fine for a single-channel application.

It is not fine when those values select the OAuth client, the callback URI and the user type that will be accepted — then the caller would be choosing the terms of their own authentication. Use fromTrustedRoute() instead:

Default keys live in federated-auth.trusted_route.keys. A route without the defaults yields a null channel, and ProviderConfig is fail-closed: it refuses to resolve a client rather than inferring one from the caller.

Separating flows that share one provider

An application often exposes more than one OAuth entry point on the same provider — plain sign-in and an invitation-gated registration, for example. The state store proves a state is authentic, unexpired, unused and bound to the same browser. It cannot prove it is being spent on the flow it was created for, so a state minted by the permissive flow would otherwise be redeemable at the restrictive one.

Comparison is strict, and a state carrying no value for an expected key fails: the point is to prove the state was minted with it.

Observability

The package dispatches an event at every stage of a flow:

ExternalRedirectIssued carries a truncated SHA-256 digest of the one-time state, and the same digest is derivable from $event->context->state on the callback side — so the two legs of one attempt can be joined in a log without ever writing a replayable token to it.

A ready-made structured logger ships with the package, off by default so upgrading never starts writing to your log unasked:

It records the provider, channel, user type, tenant, state digest and outcome. It never records the raw state, authorization codes, tokens or client secrets. For failed logins it records the exception class and a bounded exception chain so the exact technical cause remains diagnosable; every message is scrubbed before it reaches the logger because provider errors routinely embed a code or token fragment. If you want a different shape, leave it off and listen to the events yourself.

Persisting errors

Separately from the log, every failure the broker raises — redirect, callback, token login, link and unlink — can be handed to code you control so it lands in your own error table. Also off by default:

A handler may be a queued job (constructed with the payload row and dispatched), a 'Service@method' string, an invokable class or closure, or a class implementing ErrorReporterInterface (which receives the FederatedAuthError DTO instead of the array). Handlers are called with ($payload, $error), and a method declaring only the first parameter still works — an existing handle(array $data) needs no change.

The payload is scrubbed before it leaves the package: authorization codes, state, id_token/access_token/refresh_token, client secrets, Authorization headers, cookies and bare JWTs are redacted from the message, the request dump and the stack trace. That is not configurable off — an error table that outlives the request must not become a credential store. The state_digest survives, so the row still joins to the redirect leg in your log.

Capture never changes control flow: the original exception is always rethrown, and a reporter that throws is swallowed rather than replacing the authentication error. Full reference in docs/18-error-reporting.md.

Identity link model

The package links external identities to local users using this conceptual key:

Do not use email as the federated identity key. Apple can return private relay emails and some providers may return missing or unverified emails.

Extension contracts

Optional ronu/rest-generic-class integration

The package can integrate with ronu/rest-generic-class without depending on it directly.

This enables an ok/data/meta response shape and optional effective permissions in login responses.

Provider recommendations

Documentation

Full documentation lives in docs.

Recommended starting points:

• docs/00-simple-guide.md
• docs/03-core-architecture.md
• docs/08-security-and-edge-cases.md
• docs/12-oauth-hardening.md
• docs/13-apple-provider.md
• docs/14-rest-generic-class-integration.md
• docs/15-guide-integration.md

Testing

Production checklist

• [ ] Configure allowed redirect hosts.
• [ ] Keep OAuth state enabled.
• [ ] Keep OIDC nonce enabled for OIDC-style providers that control the code flow.
• [ ] Keep PKCE enabled for OIDC-style providers that control the code flow.
• [ ] Do not assume Socialite-backed Google/Facebook redirects have package-level nonce/PKCE unless using a dedicated adapter.
• [ ] Do not trust Facebook email verification unless intentionally configured.
• [ ] Do not auto-provision privileged users from public social providers.
• [ ] Confirm tenant scoping in IdentityLinkRepository.
• [ ] Confirm token issuer uses the expected guard.
• [ ] Confirm provider tokens are not stored unless needed.
• [ ] Run PHPUnit and Pint before release.

Philosophy

That separation keeps the package flexible enough for startups, SaaS products, enterprise systems and modular Laravel platforms.

License

The MIT License (MIT). Please see LICENSE.md for more information.