Azureadb2C Spa For Laravel Wire Extender Laravel Package

Getting Started

• Know what this is first. This is a thin extension layer for wika-group/azureadb2c-spa-for-laravel, not a standalone auth package. It exists to make Azure AD B2C bearer-token auth work on Livewire's (wire) request lifecycle. If you have not already read the base package's README and published its config, start there — the extender assumes that setup is in place.
• Install:

  composer require wika-group/azureadb2c-spa-for-laravel-wire-extender
  

  Pair it with a compatible version of the base azureadb2c-spa-for-laravel package; v2.0.0 of the extender may require a newer base version than v1.0.1 did. Check composer.json constraints rather than assuming.
• Publish and configure. Publish the config tag (usually vendor:publish --tag=...; confirm the exact tag in the README), then set the standard B2C env vars the base package expects — tenant/subdomain, client ID, policy/user-flow name, and the audience your API exposes.
• Where to look first:
  1. The package's service provider — it is where middleware and the guard/driver registration happen, and where you confirm what actually gets wired up.
  2. The published config file — for the guard name, middleware alias, and any claim mapping.
  3. The base package's token-validation service — the extender delegates to it.
• First use case: protect a Livewire component so that the SPA's access token is validated on the initial page render and on every subsequent /livewire/update POST. The minimal win is: authenticate in the SPA, attach the bearer token to Livewire requests, and have auth()->user() resolve inside a component without a Laravel session.

Implementation Patterns

• Token propagation from the frontend. The SPA holds the B2C token in JS; Livewire requests originate in the browser and will not carry it automatically. Use Livewire's request hook to attach the header on every request:

  Livewire.hook('request', ({ options }) => {
      options.headers = { ...options.headers, Authorization: `Bearer ${token}` };
  });
  

  Treat this as the critical integration point — most "it works on page load but not on update" bugs live here.
• Middleware on the Livewire endpoint. Apply the extender's middleware to the Livewire update route (or globally, with exclusions) so both the initial document request and the AJAX updates pass through the same guard. Keep the middleware order deterministic: token authentication should run before anything that assumes auth()->check().
• Combine, don't duplicate. Use the base package's middleware for your JSON/API routes and the extender's for Livewire routes. They should share the same token validator and user resolver so claims map identically in both contexts.
• Custom user resolution. Bind a resolver that turns validated B2C claims (oid, sub, emails, name) into your App\Models\User. Keep this in one place — a single resolveUserFromClaims() service — and reuse it in tests and in any queued/console context.
• Testing. Feature-test Livewire components by acting as a user with the guard the package registers, and unit-test the token path separately with a signed fixture token. Keep a helper that mints a valid token for your test tenant so component tests don't depend on network calls to the B2C metadata endpoint.
• Long-lived pages. For dashboards that stay open past token lifetime, plan for refresh: either a short refresh_interval on the Livewire side or an explicit re-auth flow when a 401 comes back from the update endpoint.

Gotchas and Tips

• v2.0.0 is a major bump from v1.0.1. The release notes for this version are only a changelog link, so there is no readable summary of what broke. Before upgrading, diff the changelog commit-by-commit and re-read the README — expect at minimum a config-key rename or a changed middleware/guard registration signature. Pin ^1.0 if you cannot budget the migration.
• Two request shapes, one guard. The initial page load is a plain GET; Livewire updates are POSTs to /livewire/update (and uploads to /livewire/upload-file). Any auth that only covers the first will appear to work until the user clicks something.
• Stateless vs. session friction. B2C SPA tokens are bearer and session-less, but Livewire assumes a session-backed user for things like @auth in Blade, redirects, and wire:navigate continuity. Decide early whether you are maintaining a session after token validation or staying fully stateless; mixing the two is the most common source of "user flickers to logged-out" reports.
• CSRF interaction. Livewire performs its own CSRF handling. If your token middleware short-circuits before the session/CSRF middleware, you can get 419s that look like auth failures. Verify the middleware group ordering.
• Policy/issuer mismatch. Sign-in and sign-up (or profile-edit) user flows issue tokens with different iss values. If you validate issuer against a single hard-coded policy, sign-up tokens will be rejected. Validate against the set of configured policies.
• Claims you should actually check: signature via cached JWKS, aud (your API's exposed scope, not the SPA client ID), iss, exp/nbf with a small clock-skew allowance, and scp/roles if you gate on them.
• JWKS caching. Fetching B2C metadata on every Livewire request will add noticeable latency and can rate-limit you at scale. Confirm the base package caches keys and that the cache survives deploys.
• Debugging: log the decoded (not raw) claim set on rejection along with the specific validation failure. A single 401 with no reason is nearly impossible to diagnose against B2C.
• Extension points: the config-driven user resolver and the guard registration are the two places to customize rather than forking. If you find yourself editing vendor code, you have almost certainly missed a publishable config or a bindable interface.