Zum Hauptinhalt springen
Dieser Artikel basiert auf einer Quellcode-Analyse (Branch 1.x). Eine offizielle Dokumentation gibt es noch nicht; das Paket ist vor dem offiziellen Release (Stand: April 2026).

Was ist Sentinel?

Laravel Sentinel ist ein Security-Middleware-Paket, das den Zugriff auf Routen treiberbasiert steuert. Es wird von Taylor Otwell und Mior Muhammad Zaki entwickelt und unterstützt PHP ^8.0 sowie Laravel 8–13. Der Hauptzweck ist der Schutz von Routen der Management-Tools Telescope, Horizon und Pulse. Es genügt, SentinelMiddleware auf eine Route anzuwenden, um den Zugriff über die vom Treiber definierte Autorisierungslogik zu steuern.

Vergleich mit dem bisherigen Vorgehen

Telescope und Horizon boten jeweils eigene Autorisierungsmechanismen über gate.
// Bisheriges Verfahren (etwa im TelescopeServiceProvider)
Gate::before(function ($user) {
    return $user->isAdmin() ? true : null;
});
Dieser Weg hängt vom Authentifizierungsstatus des Nutzers ab: „ohne Login lässt sich nicht entscheiden”. Sentinel arbeitet als Middleware und steuert den Zugriff pro Anfrage – unabhängig davon, ob der Nutzer authentifiziert ist. Zudem lassen sich Regeln für mehrere Management-Tools an einer Stelle definieren.

Installation

composer require laravel/sentinel
Da in composer.json unter extra.laravel.providers der SentinelServiceProvider registriert ist, wird der Service Provider automatisch erkannt. Es muss keine Konfigurationsdatei veröffentlicht werden.

Architektur des Pakets

Verhalten des Standard-Treibers (Laravel-Treiber)

Der Standard-Treiber Laravel steuert nur in der lokalen Umgebung (APP_ENV=local) den Zugriff.
// src/Drivers/Laravel.php
public function authorize(Request $request): bool
{
    if (! $this->app()->environment('local')) {
        return true; // Außerhalb von local immer erlauben
    }

    // Warnung bei Zugriff über Tunnel-Dienste
    if ($this->isPrivateIp($request->ip())
        && ! $request->isFromTrustedProxy()
        && Str::endsWith($request->host(), ['.sharedwithexpose.com', '.ngrok-free.app', '.ngrok.io'])) {
        throw new RuntimeException(
            'Unable to access "..." using "local" environment, ...'
        );
    }

    // Docker-Lokalumgebung erlauben
    if ($this->isRunningOnDockerLocally($request)) {
        return true;
    }

    // Zugriff über Reverse-Proxies prüfen
    return $this->authorizeAccessingViaReverseProxies($request);
}
Zusammenfassung des Ablaufs:
Der Laravel-Treiber gibt außerhalb der local-Umgebung immer true (erlauben) zurück. Für Zugriffssteuerung in der Produktion erstellen Sie einen eigenen Treiber.

Erkennung privater IPs

Die Basismethode isPrivateIp() der Klasse Driver erkennt anhand von Symfonys IpUtils folgende Bereiche als private IPs.
BereichBeschreibung
127.0.0.0/8Loopback (RFC1700)
10.0.0.0/8Privat (RFC1918)
192.168.0.0/16Privat (RFC1918)
172.16.0.0/12Privat (RFC1918)
169.254.0.0/16Link-Local (RFC3927)
::1/128IPv6-Loopback
fc00::/7IPv6 Unique Local
fe80::/10IPv6 Link-Local

Erkennung von Docker-Lokalumgebungen

// src/Drivers/Driver.php
protected function isRunningOnDockerLocally(Request $request): bool
{
    return $request->server->get('REMOTE_ADDR') === '127.0.0.1'
        && file_exists(base_path('.dockerenv'));
}
Wenn REMOTE_ADDR auf 127.0.0.1 steht und die Datei .dockerenv im Projekt-Root existiert, wird eine Docker-Lokalumgebung erkannt.

Einsatz als Middleware

Grundlegende Verwendung

use Laravel\Sentinel\Http\Middleware\SentinelMiddleware;

Route::middleware(SentinelMiddleware::class)->group(function () {
    Route::get('/telescope', function () { /* ... */ });
    Route::get('/horizon', function () { /* ... */ });
    Route::get('/pulse', function () { /* ... */ });
});

Einen Treiber angeben

Sie können den Treibernamen als Argument der Middleware übergeben. Bei einem nicht existierenden Treibernamen wird auf den Default-Treiber zurückgefallen (Verhalten von driverOrFallback()).
Route::middleware([SentinelMiddleware::class . ':custom-driver'])->group(function () {
    // Autorisierung durch benutzerdefinierten Treiber
});

Implementierung der Middleware

// src/Http/Middleware/SentinelMiddleware.php
public function handle(Request $request, Closure $next, ?string $driver = null)
{
    abort_unless(Sentinel::driverOrFallback($driver)->authorize($request), 401);

    return $next($request);
}
Gibt authorize() false zurück, wird mit HTTP 401 abgebrochen. Mit Driver::authorizeOrFail() ließe sich stattdessen eine AuthorizationException werfen (die Middleware selbst nutzt dies nicht).

Eigene Treiber erstellen

Durch Erben von der abstrakten Driver-Klasse und Implementierung der Methode authorize() erstellen Sie einen eigenen Treiber.
use Laravel\Sentinel\Sentinel;
use Laravel\Sentinel\Drivers\Driver;
use Illuminate\Http\Request;

Sentinel::extend('admin-only', function ($app) {
    return new class extends Driver {
        public function authorize(Request $request): bool
        {
            // Nur authentifizierte Nutzer mit admin-Rolle erlauben
            $user = $request->user();

            return $user !== null && $user->hasRole('admin');
        }
    };
});
Die Registrierung von extend() erfolgt beispielsweise in AppServiceProvider::boot().

Utility-Methoden der Basisklasse nutzen

Die Klasse Driver stellt praktische Methoden wie IP-Prüfungen bereit, die eigene Treiber frei verwenden können.
public function authorize(Request $request): bool
{
    // In der Produktion nur private IPs erlauben
    if ($this->app()->environment('production')) {
        return $this->isPrivateIp($request->ip());
    }

    // Lokal nur Docker oder Direktzugriff erlauben
    return $this->isRunningOnDockerLocally($request)
        || $this->authorizeAccessingViaReverseProxies($request);
}

Funktionsweise des SentinelManager

SentinelManager erbt von Illuminate\Support\Manager. Manager ist Laravels Basisklasse für das Treibermuster; über driver() werden Treiberinstanzen aufgelöst und gecacht.
// src/SentinelManager.php
class SentinelManager extends Manager
{
    protected function createLaravelDriver()
    {
        return new Laravel(fn () => $this->getContainer());
    }

    public function getDefaultDriver()
    {
        return 'laravel';
    }

    public function driverOrFallback(?string $driver)
    {
        return rescue(
            fn () => $this->driver($driver),
            value(fn () => $this->driver()),
            false  // nicht loggen
        );
    }
}
driverOrFallback() fällt bei nicht gefundenem Treiber still auf den Default-Treiber zurück. Ein nicht existierender Treibername im Middleware-Argument führt daher nicht zu einem Fehler. SentinelManager wird vom SentinelServiceProvider als Scoped Singleton (scoped) registriert, sodass die Treiber-Instanz innerhalb einer Anfrage wiederverwendet wird.
// src/SentinelServiceProvider.php
public function register(): void
{
    $this->app->scoped(SentinelManager::class, fn ($app) => new SentinelManager($app));
}

Fazit

laravel/sentinel ist ein kleines Paket, das dank des Treibermusters auf Basis von Illuminate\Support\Manager hoch erweiterbar ist.
AspektInhalt
Version1.x
Unterstütztes PHP^8.0
Unterstütztes Laravel8–13
Default-Treibersteuert nur die local-Umgebung
Eigene Treiberüber Sentinel::extend() ergänzbar
Der Standard-Laravel-Treiber ist darauf spezialisiert, in der lokalen Entwicklung Zugriffe über Tunnel-Dienste zu blockieren. Für den Schutz produktiver Umgebungen ist ein eigener Treiber erforderlich. Sobald die offizielle Dokumentation vorliegt, werden konkretere Einsatzmuster deutlicher werden.

Repository laravel/sentinel

Quellcode und aktuelle Änderungen finden Sie im GitHub-Branch 1.x.
Zuletzt geändert am 13. Juli 2026