Download the PHP package returnearly/laravel-cloudflare-zero-trust without Composer

Cloudflare Zero Trust for Laravel

Security-first Cloudflare Access (Zero Trust) authentication for Laravel.

When you put an application behind Cloudflare Access, Cloudflare authenticates every request at the edge — via your identity provider for humans, or via service tokens for machines — and forwards a signed JWT to your origin in the Cf-Access-Jwt-Assertion header. This package verifies that JWT cryptographically and turns it into a first-class Laravel authentication primitive:

• Route middleware that fails closed: signature, issuer, audience, expiry, and claim-shape checks before anything is trusted
• Typed principals — SSO users and service tokens are distinct, verified identities, not loosely-inspected claims
• Multiple accounts and applications — protect your app, your API, and Horizon with different Access policies from one config file
• A Laravel auth guard so auth()->user() works, optionally resolving Access users onto your own User model
• On-demand identity enrichment — groups, IdP attributes, and device posture fetched lazily and cached
• Cached, rate-limited JWKS handling with automatic key-rotation recovery
• Events for observability on every authentication success and failure
• Request-scoped state — safe under Laravel Octane and other long-lived workers

How it works

The package never trusts unverified input: principal classification happens only after cryptographic verification, and CF-Access-Client-Id / CF-Access-Client-Secret headers are never treated as origin credentials (Cloudflare validates those at the edge and mints a signed JWT for your origin).

Requirements

• PHP 8.3, 8.4, or 8.5
• Laravel 12 or 13
• An application protected by Cloudflare Access (typically via Cloudflare Tunnel)

Installation

Publish the config file:

Quick start

1. Find your team domain (Cloudflare Zero Trust dashboard → Settings → Custom Pages) and the Application Audience (AUD) tag for each Access application (Access → Applications → your app → Overview).

2. Define your accounts and applications in config/cloudflare-zero-trust.php:

3. Protect your routes:

4. Use the verified identity:

That's it. Invalid, expired, or missing tokens are rejected before your route runs.

Configuration

Accounts and applications

Each account corresponds to one Cloudflare Zero Trust team (one team domain, one JWKS endpoint). Each application under it corresponds to a Cloudflare Access application with one or more AUD tags. Application names must be unique across all accounts, because middleware and guards refer to applications by name alone.

Configuration is validated eagerly — a missing audience, an unknown principal kind, or a non-HTTPS team domain throws InvalidConfiguration rather than silently misbehaving.

Package options

All top-level options with their environment variables and defaults:

Protecting routes with middleware

The cloudflare-access middleware takes the application name as its parameter:

To protect Laravel Horizon, reference the middleware in config/horizon.php:

What a rejected request gets

The middleware fails closed and never leaks why a token was rejected to the client (the detail goes into events instead):

Requests that expect JSON receive {"message": "..."}; everything else gets a plain-text body.

Working with the verified principal

Once a request has been verified (by the middleware or the guard), the Access support class exposes the verified identity anywhere in your app:

All helpers return null/false on requests that were not verified, so they are safe to call unconditionally. State lives on the request instance (not the container), so it cannot bleed between requests under Octane; every helper also accepts an optional Request argument if you need to inspect a specific request.

UserPrincipal (SSO users)

A user token must carry type=app, a non-empty sub, and a valid email — otherwise it is rejected.

ServicePrincipal (service tokens)

A service token must carry type=app, an empty sub, and a non-empty common_name.

Both principal types implement Laravel's Authenticatable contract, so they also work with the auth guard below. kind() returns a PrincipalKind enum (PrincipalKind::User or PrincipalKind::Service).

Using the auth guard

Register a guard with the cloudflare driver in config/auth.php:

Then authenticate the standard Laravel way:

The guard and the middleware share one verification per request: whichever runs first stores the verified token on the request, and the other reuses it. The guard works standalone, but the package middleware gives you richer rejection behavior (403 vs 401, failure events), so stacking both is a good default:

Resolving Access users onto your own user model

By default the guard returns the package's stateless principals. To map SSO users onto your application's User model, implement ApplicationUserResolver:

A closure works too, if you configure the guard at runtime. Resolution rules:

• The resolver only runs for user principals; service principals are always returned as-is.
• If the resolver returns null, the guard falls back to the UserPrincipal (the request stays authenticated). Throw inside the resolver if an unknown SSO user should be treated as an error.

Service tokens

Machine-to-machine clients authenticate to Cloudflare with CF-Access-Client-Id / CF-Access-Client-Secret headers. Cloudflare validates those at the edge and forwards a signed JWT like any other request — this package only ever validates the resulting Cf-Access-Jwt-Assertion and never treats the client ID/secret pair as origin credentials.

Service tokens are opt-in per application. The default principal set is users only, so add PrincipalKind::Service where machines should be allowed:

An application without PrincipalKind::Service rejects service-token JWTs with 403 even when they are cryptographically valid. Which service tokens can mint a JWT for an application's audience is governed by your Cloudflare Access policy — manage that allowlist in the Cloudflare dashboard, not at the origin.

Identity enrichment

The Access JWT deliberately carries a minimal claim set. When you need more — IdP groups, device posture, geo — the package fetches the full identity from your team domain's /cdn-cgi/access/get-identity endpoint:

Behavior to be aware of:

• Lazy: the endpoint is only called when you ask for the identity. Ordinary authentication never touches it.
• Cached: responses are cached (keyed by the token's identity nonce) for no longer than the JWT's remaining lifetime.
• Users only: identity lookups return null for service principals and on unverified requests.
• Failure handling: Access::identity() throws IdentityUnavailable if enrichment is disabled or the endpoint fails; use Access::tryIdentity() or Access::hasGroup() when you'd rather get null/false.
• Can be disabled globally (CLOUDFLARE_ZERO_TRUST_IDENTITY_ENABLED=false) or per application ('identity_enabled' => false).

Events

Every authentication outcome dispatches an event you can hook for logging, metrics, or alerting. No event ever contains the raw JWT.

reasonCode values include missing_token, malformed_token, invalid_algorithm, unknown_kid, invalid_signature_or_claims, invalid_issuer, invalid_audience, invalid_type, missing_sub, invalid_email, disallowed_principal, and jwks_unavailable — enough granularity to alert on tampering separately from misconfiguration.

JWKS caching and key rotation

Cloudflare rotates your team's signing keys periodically. The package handles this without manual intervention:

• Keys are fetched from {team_domain}/cdn-cgi/access/certs and cached (default 1 hour, configurable store and TTL). The configured store must support atomic locks (Redis, Memcached, database, file, etc.).
• When a token arrives signed by an unknown kid, the key set is refreshed immediately — subject to a rate limit (default 10 refreshes per 60 seconds) so attackers can't use bogus kids to hammer the JWKS endpoint.
• Concurrent refreshes are deduplicated with a cache lock on the same store.
• If a refresh fails but cached keys exist, the cached keys are used; if no keys are available at all, requests fail closed with 503.
• Only RSA/RS256 signing keys are accepted; alg confusion (e.g. none or HS256 tokens) is rejected before signature verification.

Local development

Validation is on by default everywhere. There is deliberately no environment-name bypass — an app that skips auth because APP_ENV=local is one typo away from skipping it in production. To work without Cloudflare in front of you, disable the package explicitly:

When disabled, the middleware passes requests through and the guard returns no user.

To disable a single application while keeping others enforced, set that application's enabled flag (via a per-app env var in config):

Alternatively, run cloudflared locally and keep validation on — this exercises the real code path.

Testing your application

For feature tests that don't exercise authentication, disable the package in phpunit.xml:

To test the authentication path itself, fake the JWKS endpoint and mint your own RS256 tokens with firebase/php-jwt (already installed as a dependency of this package). Generate an RSA key pair in your test, serve its public JWK from the faked certs URL, and sign tokens with the private key:

For a service-token request, replace sub/email with 'sub' => '' and 'common_name' => 'my-client-id.access'. See this package's own test suite for a complete key-pair fixture you can adapt.

Security model

What the package guarantees:

• Claims are trusted only after RS256 signature verification against your team's JWKS.
• Tokens are bound to the configured issuer and to the specific application's AUD tags — a token minted for one application cannot be replayed against another.
• Principal classification (user vs. service) is strict; ambiguous claim shapes are rejected.
• Verified auth state is request-scoped, so it cannot leak between requests under Octane or queue workers.
• Failures are closed: configuration errors, JWKS outages, and unknown applications reject requests rather than letting them through.
• Raw JWTs and secrets are never included in events, logs, or error responses.

What the package cannot do for you:

[!IMPORTANT] Your origin must not be directly reachable from the internet. A valid Access JWT is a bearer credential: anyone who obtains one can replay it against an exposed origin until it expires, bypassing Cloudflare's checks entirely. Put your origin behind Cloudflare Tunnel, mTLS, or equivalent network controls so the only path to your app is through Cloudflare.

See SECURITY.md for the full deployment threat model and the vulnerability disclosure policy.

Development

Contributing

See CONTRIBUTING.md.

Credits

• Tom Schlick
• All contributors

License

The MIT License (MIT). See LICENSE.md for details.