laravel-cloudflare-access maintained by devfactorych
Laravel Cloudflare Access
Sign users into a Laravel app with Cloudflare Access (Zero Trust) SSO.
When enabled, every request in the web middleware group must carry a valid Cloudflare Access JWT. The package verifies it against your team's signing keys, then logs the user into the regular session guard, creating the account on first visit if you allow it. Livewire, CSRF and Fortify keep working as usual.
- Verifies the signature (with automatic key rotation), issuer, audience and email, and optionally the email domain.
- Accepts the
Cf-Access-Jwt-Assertionheader or theCF_Authorizationcookie. - Logging out with Fortify also ends the Cloudflare Access session.
- Disabled by default, so local development keeps the app's normal login.
Installation
composer require devfactorych/laravel-cloudflare-access
php artisan vendor:publish --tag="cloudflare-access-config" # optional
CF_ACCESS_ENABLED=true
CF_ACCESS_TEAM_DOMAIN=https://your-team.cloudflareaccess.com
CF_ACCESS_AUD= # the Access application's "Application Audience (AUD) Tag"
CF_ACCESS_ALLOWED_DOMAINS=example.com # optional, comma-separated
CF_ACCESS_AUTO_PROVISION=true # false = only existing users may sign in
The middleware is added to the web group automatically and runs before auth. If the app is only reachable through Cloudflare, also trust the proxy in bootstrap/app.php so URLs and client IPs are correct:
$middleware->trustProxies(at: '*');
Configuration
| Key | Default | |
|---|---|---|
enabled |
false |
Turn SSO on. |
team_domain |
Your https://<team>.cloudflareaccess.com URL. Also the expected iss claim. |
|
aud |
The Access application's AUD tag. | |
allowed_domains |
[] |
Restrict sign-in to these email domains. |
auto_provision |
true |
Create unknown users on first visit. When false, unknown emails get a 403. |
guard / user_model |
web / guard's model |
Where users are looked up and logged in. |
except |
[] |
Request::is() patterns that skip SSO, e.g. ['webhooks/*']. Pair them with a Bypass policy in Cloudflare. |
register_middleware |
true |
Set to false to add AuthenticateWithCloudflareAccess to your middleware yourself. |
Custom user provisioning
Bind your own implementation of DevFactory\CloudflareAccess\Contracts\ProvisionsUsers. Return the user to log in, or null to deny access:
$this->app->bind(ProvisionsUsers::class, MyProvisioner::class);
Hiding password features
Password, 2FA and passkey screens make no sense under SSO. Return a 404 for them with the cloudflare-access.disabled middleware, and switch off Fortify's features when SSO is on:
Route::livewire('settings/security', 'pages::settings.security')
->middleware(['cloudflare-access.disabled', 'password.confirm']);
// config/fortify.php
'features' => env('CF_ACCESS_ENABLED', false) ? [] : [Features::registration(), /* ... */],
Use CloudflareAccess::enabled() in views to hide the related links.
Testing
CloudflareAccessFake turns SSO on with a local key pair, fakes your team's certs endpoint and issues signed tokens:
use DevFactory\CloudflareAccess\CloudflareAccess;
use DevFactory\CloudflareAccess\Testing\CloudflareAccessFake;
$cloudflare = CloudflareAccessFake::enable();
$this->withHeader(CloudflareAccess::HEADER, $cloudflare->token(['email' => 'jane@example.com']))
->get('/dashboard')
->assertOk();
composer test
License
MIT. See LICENSE.md.