Skip to content

8. Authentifizierung und Autorisierung

Bei jeder Anfrage stellen sich zwei getrennte Fragen:

  • Wer ist der Benutzer? Das ist die Authentifizierung: Der Benutzer hat sich mit Benutzername und Passwort identifiziert, und jede folgende Anfrage muss belegen, dass sie von ihm stammt;
  • Hat er die Berechtigung, auf diese Seite zuzugreifen? Das ist die Autorisierung: In der Fallstudie verwaltet nur ein Benutzer mit der Rolle ADMIN Ärzte und Klienten.

Der Identitätsnachweis muss bei jeder Anfrage mitgeliefert werden. [Symfony] speichert den angemeldeten Benutzer typischerweise in seiner Session (siehe den Abschnitt über Gültigkeitsbereiche), was die einfachste Lösung für eine Webanwendung ist. Die Fallstudie verwendet in allen ihren Versionen ([ASP.NET Core MVC], [Spring MVC], [NestJS], [Flask], [Laravel]) stattdessen ein Token (JWT, JSON Web Token), das wir auch hier verwenden werden: Nach der Anmeldung erzeugt der Server ein Token, das die Identität des Benutzers enthält, und signiert es mit einem geheimen Schlüssel (das ist das Prinzip hinter dem signierten Cookie in Beispiel 23). Das Token wird in einem Cookie gespeichert; der Browser sendet es bei jeder Anfrage zurück; der Server überprüft die Signatur. Der Benutzer kann sein Token lesen, aber nicht ändern: Jede Änderung macht die Signatur ungültig. Das Format ist standardisiert (RFC 7519), wird von allen Programmiersprachen verstanden, und das Token enthält sein Ablaufdatum. Vor allem muss der Server nichts speichern: Jeder Server, der den Schlüssel kennt, kann das Token überprüfen.

[Symfony] verfügt über eine umfassende Sicherheitskomponente, die durch SecurityBundle integriert wird und deren Elemente wir unverändert verwenden werden:

  • Die URLs der Anwendung werden auf Firewalls (firewalls) verteilt, jede mit ihrer eigenen Methode zur Authentifizierung der Benutzer;
  • Die Authentifizierung übernehmen Authenticators (authenticators): Objekte, die bei jeder Anfrage die Identität des Benutzers bestimmen. [Symfony] bietet mehrere davon (Anmeldeformular, Session, API-Token usw.); wir schreiben unseren eigenen, der das JWT-Token liest. Der Rest der Anwendung sieht nur das Ergebnis: den authentifizierten Benutzer, bereitgestellt durch [#[CurrentUser]], [$this->getUser()] und in den Views durch [app.user];
  • Benutzer werden von einem User-Provider bereitgestellt, und ihre Passwörter werden von der Komponente PasswordHasher gehasht (Algorithmus [bcrypt]);
  • Die Autorisierung ist rollenbasiert: Der Seiten-Schutz wird durch Access-Control-Regeln beschrieben ([access_control]) oder durch das Attribut [#[IsGranted]] der Aktionen; Views prüfen ein Recht mit [is_granted];
  • Anmeldeversuche werden von der Komponente RateLimiter begrenzt (Beispiel 27).

All das wird durch Kernel-Ereignis-Listener erreicht (vorheriges Kapitel): Die Firewall reagiert auf [kernel.request] (Priorität 8), [#[IsGranted]] wird bei [kernel.controller_arguments] gelesen, und Zugriffsverweigerungen sind Exceptions, die bei [kernel.exception] behandelt werden.

Die Erzeugung und Überprüfung der Token übernimmt die Bibliothek [firebase/php-jwt], die am häufigsten verwendete in [PHP], installiert durch die Datei [composer.json] der Beispiele. (Es gibt ein weit verbreitetes Bundle für Token – JWT und [LexikJWTAuthenticationBundle] –, das für APIs entwickelt wurde; für eine Webanwendung genügen wenige Zeilen, und sie veranschaulichen den Mechanismus besser.)

8.1. Beispiel 25: Anmeldung, Token, geschützte Seite

25-jwt/
├── .env
├── config/
│   ├── bundles.php
│   └── packages/
│       ├── framework.yaml
│       └── security.yaml
├── src/
│   ├── Controller/
│   │   ├── AuthController.php
│   │   └── ProfileController.php
│   └── Security/
│       ├── AuthService.php
│       ├── TokenAuthenticator.php
│       ├── User.php
│       └── UsersService.php
├── templates/
│   ├── auth/
│   │   └── login.html.twig
│   ├── layout.html.twig
│   └── profile/
│       └── profile.html.twig
└── ...

8.1.1. Konfiguration: .env, bundles.php und framework.yaml

Das Token wird mit einem geheimen Schlüssel signiert, der nicht fest im Code stehen darf. Es ist an der Zeit, die Konfiguration wirklich vom Code zu trennen. Die für eine Installation spezifischen Einstellungen stehen in der Datei [.env] (Beispiel 01), die nun drei neue Zeilen enthält (einen Kommentar, gefolgt von zwei Variablen):

1
2
3
4
5
6
# .env: die Konfiguration von Beispiel 25 (siehe Beispiel 01)
APP_ENV=dev
APP_SECRET=6144ddf9f821deebee2291ab7742d7a9
# der Schlüssel, der die JWT-Tokens signiert (mindestens 32 Zeichen), und ihre Lebensdauer
JWT_SECRET=a-secret-key-of-at-least-32-characters-for-example-25
JWT_DURATION_MINUTES=60

Der Standard verlangt, dass der verwendete Algorithmus (HMAC-SHA256) einen Schlüssel von mindestens 256 Bit bzw. 32 Byte hat; die Bibliothek weist jeden kürzeren Schlüssel zurück. Der Code selbst liest die Datei [.env] nicht direkt: Die Komponente [Dotenv] (Beispiel 01) hat sie in Umgebungsvariablen umgewandelt, die der Container den Services bereitstellt, die sie anfordern (das sehen wir beim Service [AuthService]). Eine echte Umgebungsvariable hat Vorrang vor der Datei [.env]: Unter [Linux] oder [macOS] würde die Anwendung wie folgt mit einem anderen Schlüssel gestartet:

JWT_SECRET="another-key-of-at-least-thirty-two-characters" php -d variables_order=EGPCS -S localhost:8000 -t public

und unter [Windows] (PowerShell):

$env:JWT_SECRET="another-key-of-at-least-thirty-two-characters"
php -d variables_order=EGPCS -S localhost:8000 -t public

(Die Option [-d variables_order=EGPCS] weist [PHP] an, das Array [$_ENV] mit Umgebungsvariablen zu füllen, was seine Standardkonfiguration nicht immer tut.) In der Produktion werden Secrets häufig dem [Symfony]-Tresor (Secrets Vault, Befehl [bin/console secrets:set]) anvertraut, der sie verschlüsselt im Projekt speichert.

SecurityBundle wird der Liste der Bundles hinzugefügt:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php: die Bundles der Anwendung; das SecurityBundle integriert
// die Security-Komponente (Authentifizierung, Autorisierung)
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
];

Die Session wird hier ausschließlich für das Anti-CSRF-Token des Anmeldeformulars verwendet (Beispiel 21):

1
2
3
4
5
6
7
8
# config/packages/framework.yaml: die Konfiguration des FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # die Session: Sie wird nur für das Anti-CSRF-Token des Login-Formulars verwendet
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true

8.1.2. Sicherheitskonfiguration: config/packages/security.yaml

# config/packages/security.yaml: die Konfiguration des SecurityBundle
security:
    # das Hashing der Passwörter der Benutzer der Klasse User: bcrypt
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    # der User-PROVIDER: das Objekt, das einen Benutzer anhand seines Logins findet
    providers:
        users:
            id: App\Security\UsersService

    # die FIREWALLS: Jede schützt die URLs, die zu ihrem Pattern passen
    firewalls:
        # die Bootstrap-Dateien: keine Sicherheit
        resources:
            pattern: ^/bootstrap/
            security: false
        # alle anderen URLs
        main:
            # stateless: Der Benutzer wird nicht in der Session gespeichert, er wird
            # bei jeder Anfrage anhand seines Tokens wiedergefunden
            stateless: true
            provider: users
            # der Authenticator: Er liest bei jeder Anfrage das Token aus dem Cookie
            custom_authenticators:
                - App\Security\TokenAuthenticator

    # die ZUGRIFFSKONTROLLE: Die URLs, die mit /profile beginnen, erfordern einen authentifizierten
    # Benutzer; die anderen sind öffentlich
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • Zeilen 4–6: der Passwort-Hash-Algorithmus für Benutzer der Klasse [User]: [bcrypt]. (Der Wert [auto] würde den besten verfügbaren Algorithmus auswählen und Hashes anderer Algorithmen überprüfen können);
  • Zeilen 9–11: der User Provider – der Service, der einen Benutzer anhand seiner ID findet (hier unsere Klasse [UsersService]). [Symfony] bietet mehrere: [memory] (eine in dieser Datei geschriebene Liste), [entity] (eine Datenbanktabelle; siehe Fallstudie) ...;
  • Zeilen 14–27: die Firewalls. Jede gilt für die URLs, die ihrem Muster entsprechen ([pattern]), wobei der erste passende Eintrag gewählt wird. Die erste, [resources], deckt die Dateien von [Bootstrap] (Beispiel 15) ohne Sicherheit ab ([security: false]): Man muss keinen Benutzer suchen, um ein Stylesheet auszuliefern. Die zweite, [main], hat keinen besonderen Grund: Sie deckt alle anderen URLs ab;
  • Zeile 23: Die Firewall ist zustandslos (stateless): Der authentifizierte Benutzer wird nicht in der Session gespeichert; er wird bei jeder Anfrage anhand seines Tokens identifiziert;
  • Zeilen 26–27: der Authenticator der Firewall, unsere Klasse [TokenAuthenticator];
  • Zeilen 31–32: Zugriffskontrolle: eine Liste von Regeln, die der Reihe nach geprüft werden und von denen die erste, die zur URL passt, angewendet wird. Die URLs, die mit [/profile] beginnen, erfordern einen authentifizierten Benutzer ([IS_AUTHENTICATED]); die übrigen sind öffentlich.

In einem Standardprojekt wird diese Datei von [Symfony Flex] geschrieben, sobald das Bundle ([composer require security]) installiert wird, und der Befehl [bin/console make:user] von [MakerBundle] erzeugt die Benutzerklasse und ihren Provider.

8.1.3. Benutzer: src/Security/User.php und UsersService.php

<?php
// src/Security/User.php: ein Benutzer. UserInterface: das Interface, das
// Symfony von authentifizierten Benutzern erwartet; PasswordAuthenticatedUserInterface:
// ein Benutzer, der ein Passwort hat

namespace App\Security;

use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

readonly class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    public function __construct(
        public string $login,
        public string $name,
        // die Rolle: USER oder ADMIN
        public string $role,
        // der HASH des Passworts (leer bei einem aus einem Token gelesenen Benutzer)
        public string $passwordHash = '',
        // der Inhalt des Tokens, das den Benutzer authentifiziert hat
        public array $claims = [],
    ) {
    }

    // der Bezeichner des Benutzers: sein Login
    public function getUserIdentifier(): string
    {
        return $this->login;
    }

    // die Rollen im Sinne von Symfony: Strings, die mit ROLE_ beginnen
    public function getRoles(): array
    {
        return ['ROLE_'.$this->role];
    }

    public function getPassword(): string
    {
        return $this->passwordHash;
    }
}
  • Zeile 11: ein Benutzer. [Symfony] erwartet, dass authentifizierte Benutzer die Schnittstelle [UserInterface] implementieren: Deren Methoden liefern die ID und die Rollen des Benutzers. Die Schnittstelle [PasswordAuthenticatedUserInterface] ergänzt das gehashte Passwort. In einer typischen Anwendung implementiert die [Doctrine]-Entität der Benutzertabelle (nächstes Kapitel) diese Methoden;
  • Zeilen 13–23: der Login, der Name, die Rolle, der Passwort-Hash und der Inhalt des Tokens, mit dem der Benutzer authentifiziert wurde (leer bei einem Benutzer, der aus der Benutzerliste geladen wurde). Ein Server speichert ein Passwort niemals, auch nicht in verschlüsselter Form: Würde die Datenbank gestohlen, wären auch die Passwörter gestohlen (und viele Menschen verwenden überall dasselbe Passwort). Er speichert das Ergebnis einer Hashfunktion, einer Einwegfunktion: Man kann den Hash eines Passworts berechnen, aber aus dem Hash lässt sich kein Passwort wiederherstellen. Um ein eingegebenes Passwort zu prüfen, berechnet man seinen Hash und vergleicht ihn mit dem gespeicherten;
  • Zeilen 32–35: Rollen, wie von [Symfony] definiert: Zeichenketten, die mit [ROLE_] beginnen. Die Rolle [USER] aus der Fallstudie wird zu [ROLE_USER].
<?php
// src/Security/UsersService.php: die Benutzer, im Speicher (Beispiel 28
// und die Fallstudie legen sie in einer Datenbank ab). UserProviderInterface: ein User-PROVIDER
// im Sinne von Symfony (siehe config/packages/security.yaml)

namespace App\Security;

use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\Exception\UserNotFoundException;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

class UsersService implements UserProviderInterface
{
    // Wir bewahren NIEMALS ein Passwort auf, nur seinen bcrypt-Hash, ein für alle Mal berechnet
    // mit: php -r "echo password_hash('marie', PASSWORD_BCRYPT);"
    private const USERS = [
        'marie' => ['Marie Pélissier', 'USER', '$2y$10$2DnOgGBiVcyc07su9rj2E.EvOoyPFzHN/h9PLKDuoW5P7UGtclW6W'],
        'admin' => ['Administrator', 'ADMIN', '$2y$10$m5o9euCi0EdgoZkLVw.UsO58RxJcqhMBfVrlLMCIOh2LyGSjuN29K'],
    ];

    public function find(string $login): ?User
    {
        if (! isset(self::USERS[$login])) {
            return null;
        }
        [$name, $role, $hash] = self::USERS[$login];
        return new User($login, $name, $role, $hash);
    }

    // die drei Methoden von UserProviderInterface
    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        return $this->find($identifier) ?? throw new UserNotFoundException();
    }

    // der in der Session gespeicherte Benutzer, der neu geladen werden soll: hier nie aufgerufen,
    // da die Firewall stateless ist
    public function refreshUser(UserInterface $user): UserInterface
    {
        throw new UnsupportedUserException();
    }

    public function supportsClass(string $class): bool
    {
        return $class === User::class;
    }
}
  • Zeilen 17–20: zwei fest codierte Testbenutzer (Beispiel 28 und die Fallstudie speichern sie in einer Datenbank): für jeden Login der Name, die Rolle und der Passwort-Hash. Der Hash wird mit dem Algorithmus bcrypt erzeugt, der für Passwörter entwickelt wurde. Er hat zwei besondere Eigenschaften. Er ist absichtlich langsam, mit einstellbarem Grad der Langsamkeit (der Kostenfaktor, hier auf 10 gesetzt: 2^10 Rechenzyklen, daraus ergibt sich der Hash [$10$]): wenige Dutzend Millisekunden, für einen Benutzer nicht wahrnehmbar, die es für einen Angreifer aber sehr teuer machen, Milliarden von Passwörtern auszuprobieren. Er ist gesalzen: Ein zufällig erzeugtes Salt wird vor dem Hashen mit dem Passwort vermischt und im Hash selbst gespeichert (die 22 Zeichen nach [$10$]); zwei Benutzer mit demselben Passwort haben somit unterschiedliche Hashes. Die Hashes wurden einmalig mit der Funktion [password_hash] von [PHP] (Zeile 16) oder mit dem Befehl [bin/console security:hash-password] von [Symfony] berechnet: Sie bei jeder Anfrage neu zu berechnen wäre unnötige Zeitverschwendung, da die Anwendung bei jeder Anfrage neu aufgebaut wird. [bcrypt] berücksichtigt nur die ersten 72 Bytes eines Passworts: Die Fallstudie trägt dem Rechnung;
  • Zeilen 22–29: der Benutzer zu einem Login oder [null]. [isset] prüft, ob ein Schlüssel existiert; die Zuweisung [[$name, $role, $hash] = ...] zerlegt ein Array: Jede Variable erhält das entsprechende Element;
  • Zeilen 32–47: die drei Methoden der Schnittstelle [UserProviderInterface], die die Klasse zu einem User Provider machen: [loadUserByIdentifier] liefert den zu einem Bezeichner gehörenden Benutzer oder wirft die Exception [UserNotFoundException]; [refreshUser] lädt den in der Session gespeicherten Benutzer neu (bei einer Stateless-Firewall überflüssig); [supportsClass] gibt die Klasse der bereitgestellten Benutzer an. Der Operator [??] gefolgt von [throw] löst die Exception aus, wenn der Ausdruck auf der linken Seite zu [null] ausgewertet wird.

8.1.4. Der Authentifizierungsservice: src/Security/AuthService.php

<?php
// src/Security/AuthService.php: die Prüfung der Passwörter und der JWT-Tokens

namespace App\Security;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
use Throwable;

class AuthService
{
    // der Name des Cookies, das das Token trägt
    public const COOKIE = 'token';

    public function __construct(
        private UsersService $users,
        // der Service zum Hashing der Passwörter (siehe config/packages/security.yaml)
        private UserPasswordHasherInterface $hasher,
        // #[Autowire(env: ...)]: der Wert einer Umgebungsvariable (Datei .env);
        // das Präfix int: wandelt ihn in eine Ganzzahl um
        #[Autowire(env: 'JWT_SECRET')] private string $secret,
        #[Autowire(env: 'int:JWT_DURATION_MINUTES')] public readonly int $durationMinutes,
    ) {
    }

    // der Benutzer oder null, wenn das Login unbekannt oder das Passwort falsch ist.
    // isPasswordValid hasht das eingegebene Passwort mit dem Salt des gespeicherten Hashs
    // und vergleicht dann die beiden Ergebnisse
    public function validate(?string $login, ?string $password): ?User
    {
        if (! $login || $password === null) {
            return null;
        }
        $user = $this->users->find($login);
        if ($user === null || ! $this->hasher->isPasswordValid($user, $password)) {
            return null;
        }
        return $user;
    }

    // das JWT-Token des Benutzers, signiert mit dem geheimen Schlüssel (HMAC-SHA256)
    public function createToken(User $user): string
    {
        $now = time();
        // der Inhalt des Tokens: die „Claims“ (Aussagen über den Benutzer)
        $claims = [
            'sub' => $user->login,
            'name' => $user->name,
            'role' => $user->role,
            'iat' => $now,
            'exp' => $now + $this->durationMinutes * 60,
        ];
        return JWT::encode($claims, $this->secret, 'HS256');
    }

    // der durch ein Token beschriebene Benutzer, dessen Signatur und Ablaufdatum
    // gültig sind; sonst null (gefälschtes, abgelaufenes oder unlesbares Token)
    public function check(string $token): ?User
    {
        try {
            // decode gibt ein Objekt zurück; (array) wandelt es in ein assoziatives Array um
            $claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
        } catch (Throwable) {
            return null;
        }
        return new User($claims['sub'], $claims['name'], $claims['role'], claims: $claims);
    }
}
  • Zeilen 17–26: Der Service erhält den User Provider, den Service zum Hashen von Passwörtern ([UserPasswordHasherInterface], der den in [security.yaml] gewählten Algorithmus anwendet) sowie zwei Konfigurationswerte. Das Attribut [#[Autowire(env: 'NAME')]] liefert den Wert einer Umgebungsvariablen; ein Präfix konvertiert ihn: [int:] in eine Ganzzahl (es gibt weitere: [bool:], [json:], [base64:] ...). Die Gültigkeitsdauer ist eine öffentliche schreibgeschützte Eigenschaft: Der Controller wird sie verwenden;
  • Zeilen 31–41: Überprüfung von Benutzername und Passwort. [isPasswordValid] hasht das eingegebene Passwort mit dem Salt des gespeicherten Hashs und vergleicht die beiden Hashes. Ein unbekannter Benutzername und ein falsches Passwort führen zum selben Ergebnis, [null];
  • Zeilen 44–56: Erzeugung des Tokens. Das Token enthält ein Array von Aussagen (Claims) über den Benutzer. Einige haben standardisierte Namen: [sub] (subject), die ID des Benutzers; [iat] (issued at), das Erstellungsdatum; [exp] (expiration), das Ablaufdatum. Die Datumsangaben sind in Sekunden seit dem 1. Januar 1970 ausgedrückt (die Funktion [time()] von [PHP]). Die übrigen Felder sind optional: hier der Name und die Rolle. [JWT::encode] erzeugt das Token und signiert es mit dem Algorithmus [HS256] (HMAC-SHA256, eine Signatur mit einem gemeinsamen geheimen Schlüssel);
  • Zeilen 60–69: Überprüfung des Tokens. [JWT::decode] prüft die Signatur und das Ablaufdatum und liefert dann die Aussagen zurück (ein Objekt, das mit [(array)] in ein Array umgewandelt wird). Jede Auffälligkeit (gefälschtes, abgelaufenes oder fehlerhaft aufgebautes Token) löst eine Exception aus; [catch (Throwable)] fängt sie alle ab ([Throwable] ist die Schnittstelle für alle Exceptions und Fehler von [PHP]; der Variablenname ist optional, wenn er nicht verwendet wird). Das Objekt [Key] verknüpft den Schlüssel mit einem Algorithmus: Ein Token, das einen anderen Algorithmus angibt (oder gar keinen, [none]), würde abgelehnt. Das gültige Token wird zu einem [User], ohne Hash, zusammen mit seinen Claims (Parameter mit dem Namen [claims]).

8.1.5. Der Authenticator: src/Security/TokenAuthenticator.php

<?php
// src/Security/TokenAuthenticator.php: der AUTHENTICATOR der Firewall (siehe
// config/packages/security.yaml): Bei jeder Anfrage stellt er fest, wer der Benutzer ist,
// anhand des JWT-Tokens im Cookie [token]

namespace App\Security;

use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;

class TokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
    public function __construct(private AuthService $auth)
    {
    }

    // Der Authenticator wird nur aktiv, wenn die Anfrage das Token-Cookie trägt;
    // andernfalls bleibt der Besucher anonym
    public function supports(Request $request): ?bool
    {
        return $request->cookies->has(AuthService::COOKIE);
    }

    // der PASSPORT des Benutzers: wer er ist (das Badge) und wie das zu prüfen ist.
    // Das Token wurde bereits geprüft: Der Passport validiert sich selbst (SelfValidatingPassport)
    public function authenticate(Request $request): Passport
    {
        $user = $this->auth->check($request->cookies->get(AuthService::COOKIE));
        if ($user === null) {
            throw new CustomUserMessageAuthenticationException('invalid token');
        }
        // das Badge: das Login und eine Funktion, die den Benutzer zurückgibt (hier den aus dem
        // Token, ohne die Liste der Benutzer zu konsultieren)
        return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
    }

    // ein gültiges Token: null, die Anfrage setzt ihren Weg zur Action fort
    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        return null;
    }

    // ein ungültiges Token (abgelaufen, gefälscht): ab zu /login, und wir löschen das Cookie
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $response = new RedirectResponse('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }

    // der ENTRY POINT: die Antwort an einen anonymen Besucher, der eine
    // geschützte Seite anfordert; hier eine Weiterleitung auf die Login-Seite
    public function start(Request $request, ?AuthenticationException $authException = null): Response
    {
        return new RedirectResponse('/login');
    }
}

Für jede Anfrage, die die Firewall durchläuft, ruft [Symfony] die Methoden des Authenticators in dieser Reihenfolge auf:

  • Zeilen 28–31: [supports]: Ist der Authenticator an dieser Anfrage beteiligt? Ja, wenn sie das Token-Cookie enthält. Andernfalls geschieht nichts: Der Besucher bleibt anonym;
  • Zeilen 35–44: [authenticate] erstellt einen Passport: die Identität des Benutzers (ein Badge, [UserBadge]) und die zu überprüfenden Nachweise. Ein klassisches Anmeldeformular würde das eingegebene Passwort in den Passport aufnehmen, das [Symfony] selbst überprüfen würde. Hier ist der Nachweis das Token, das bereits von [AuthService] überprüft wurde: Der Passport validiert sich selbst ([SelfValidatingPassport]). Das Badge enthält den Login und eine Funktion, die den Benutzer identifiziert: hier den im Token beschriebenen Benutzer, ohne die Benutzerliste zu befragen (ohne diese Funktion würde [Symfony] den Benutzer beim Provider anfordern). Ein ungültiges Token löst eine Authentifizierungs-Exception aus;
  • Zeilen 47–50: [onAuthenticationSuccess]: Die Authentifizierung war erfolgreich. Die Rückgabe von [null] lässt die Anfrage mit einem authentifizierten Benutzer zur Action durch. (Ein Anmeldeformular würde hier auf die Startseite umleiten);
  • Zeilen 53–58: [onAuthenticationFailure]: Die Authentifizierung ist fehlgeschlagen (Token abgelaufen oder gefälscht). Die Antwort leitet auf die Anmeldeseite um und nutzt die Gelegenheit, das Cookie zu löschen: [clearCookie] fügt der Antwort ein leeres, bereits abgelaufenes Cookie hinzu;
  • Zeilen 62–65: [start] ist die Methode der Schnittstelle [AuthenticationEntryPointInterface]: der Einstiegspunkt der Firewall, d. h. die Antwort, die an einen anonymen Besucher gesendet wird, der eine geschützte Seite anfordert. Hier ist das eine Umleitung auf die Anmeldeseite.

Der Authenticator verweigert keinen Zugriff: Er stellt fest, wer der Benutzer ist, oder dass der Benutzer anonym ist. Das ist die Authentifizierung. Verweigerungen sind Sache der Zugriffskontrolle.

8.1.6. Die Controller

<?php
// src/Controller/AuthController.php: Login und Logout

namespace App\Controller;

use App\Security\AuthService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

class AuthController extends AbstractController
{
    public function __construct(private AuthService $auth)
    {
    }

    #[Route('/', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirect('/profile');
    }

    #[Route('/login', methods: ['GET'])]
    public function form(): Response
    {
        return $this->render('auth/login.html.twig');
    }

    #[Route('/login', methods: ['POST'])]
    public function login(Request $request): Response
    {
        // das Anti-CSRF-Token des Formulars (siehe Beispiel 21)
        if (! $this->isCsrfTokenValid('login', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $login = $request->getPayload()->getString('login');
        $user = $this->auth->validate($login, $request->getPayload()->getString('password'));
        if ($user === null) {
            // eine bewusst vage Meldung: Wir sagen nicht, ob es das Login oder das Passwort ist
            return $this->render('auth/login.html.twig', ['login' => $login,
                'error' => 'Incorrect login or password.']);
        }
        // das Token in einem Cookie: Das JavaScript der Seite kann es nicht lesen
        // (httpOnly); es wird nicht mit POST-Anfragen von anderen Websites gesendet
        // (sameSite); es verschwindet gleichzeitig mit dem Ablauf des Tokens
        $response = $this->redirect('/profile');
        $response->headers->setCookie(Cookie::create(AuthService::COOKIE, $this->auth->createToken($user))
            ->withExpires(time() + $this->auth->durationMinutes * 60)
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // Abmelden: nur per POST (ein einfacher Link, der auf einer anderen Website platziert ist, kann
    // den Benutzer nicht ohne sein Wissen abmelden); wir löschen das Cookie
    #[Route('/logout', methods: ['POST'])]
    public function logout(Request $request): Response
    {
        if (! $this->isCsrfTokenValid('logout', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $response = $this->redirect('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }
}
  • Zeilen 36–38: Das Anmeldeformular ist wie alle Formulare gegen gefälschte Anfragen geschützt (Beispiel 21);
  • Zeilen 40–45: der Anmeldevorgang. Schlägt er fehl, wird das Formular mit dem eingegebenen Benutzernamen und einer bewusst vagen Meldung erneut angezeigt: Die Meldung „unbekannter Benutzername“ würde einem Angreifer verraten, welche Benutzernamen existieren;
  • Zeilen 49–54: Bei Erfolg wird das Token in einem Cookie gespeichert, und der Benutzer wird auf die geschützte Seite umgeleitet (PRG-Schema). Das Cookie ist [httpOnly]: Das [JavaScript] der Seite kann es nicht lesen, was das Token vor Skriptinjektion (XSS) schützt; es ist [SameSite=Lax]: Der Browser sendet es nicht bei einer POST-Anfrage mit, die von einer anderen Website stammt, was die Anwendung vor CSRF-Angriffen schützt; sein Ablaufdatum ([withExpires], hier eine Anzahl von Sekunden seit 1970) entspricht dem des Tokens. In der Produktion würden wir bei HTTPS [withSecure(true)] ergänzen: Das Cookie würde dann niemals über eine unverschlüsselte Verbindung gesendet;
  • Zeilen 59–68: Das Abmelden löscht das Cookie ([clearCookie]). Dies ist eine POST-Action, die durch ein Anti-CSRF-Token geschützt ist: Ein einfacher Link auf [/logout], der auf einer anderen Website oder in einem Bild platziert ist, kann den Benutzer nicht ohne sein Wissen abmelden. Beachten Sie eine Einschränkung von Tokens: Das Token selbst bleibt bis zu seinem Ablauf gültig. Wer eine Kopie davon angefertigt hat, könnte es weiterhin verwenden. Deshalb ist ihre Lebensdauer begrenzt.

[Symfony] kann auch selbst die formularbasierte Anmeldung (den Authenticator [form_login]) und die Abmeldung (die Firewall-Option [logout] ) übernehmen; diese speichern den Benutzer jedoch in der Session, wohingegen wir ein Token wollen.

<?php
// src/Controller/ProfileController.php: eine Seite, die authentifizierten Benutzern vorbehalten ist
// (siehe access_control in config/packages/security.yaml)

namespace App\Controller;

use App\Security\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;

class ProfileController extends AbstractController
{
    // #[CurrentUser]: der authentifizierte Benutzer der Anfrage, derjenige, den der
    // Authenticator gefunden hat
    #[Route('/profile', methods: ['GET'])]
    public function display(#[CurrentUser] User $user): Response
    {
        return $this->render('profile/profile.html.twig', ['user' => $user]);
    }
}
  • Zeile 18: Das Attribut [#[CurrentUser]] liefert den authentifizierten Benutzer, den der Authenticator ermittelt hat. Die Action ist durch die Regel [access_control] aus [security.yaml] geschützt: Es ist garantiert, dass sie einen Benutzer erhält. Wir würden ihn auch über [$this->getUser()] erhalten.

8.1.7. Die Views

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('login') }}">
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login ?? '' }}" required>
    </div>
    <div class="mb-3">
      <label class="form-label" for="password">Password</label>
      <input class="form-control" type="password" id="password" name="password" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  {% if error is defined %}
    <div class="alert alert-danger mt-3">{{ error }}</div>
  {% endif %}
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
{% endblock %}
  • Zeile 6: das Anti-CSRF-Token des Formulars (Beispiel 21);
  • Zeile 9: Der eingegebene Login wird nach einem Fehlschlag erneut angezeigt ([??]: eine leere Zeichenkette, wenn die Variable [login] nicht existiert).
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{{ user.role == 'ADMIN' ? 'administrator' : 'user' }}</b>.</p>
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {% for key, value in user.claims %}
      <tr><td><code>{{ key }}</code></td><td>{{ value }}</td></tr>
    {% endfor %}
  </table>
  {# Abmelden: ein POST-Formular, reduziert auf seinen Button #}
  <form method="post" action="/logout">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('logout') }}">
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • Zeilen 8–10: der Inhalt des Tokens, zu Anschauungszwecken angezeigt. Eine Schleife mit [for] in [Twig] kann die Schlüssel und Werte eines assoziativen Arrays durchlaufen ([for key, value in ...]);
  • Zeilen 13–16: die Abmeldung über ein Formular, das auf eine einzige Schaltfläche reduziert ist.

Der authentifizierte Benutzer steht in allen Views außerdem unter dem Namen [app.user] zur Verfügung.

8.1.8. Ausführung

Fordern wir die geschützte Seite [/profile] an, ohne angemeldet zu sein:

curl -i http://localhost:8000/profile
1
2
3
4
HTTP/1.1 302 Found
...
Location: /login
...

Ein falsches Passwort:

Image

Erfolgreiche Anmeldung. Mit [curl] müssen Sie zuerst das Formular anfordern, um das Anti-CSRF-Token und das Session-Cookie zu erhalten (Beispiel 21), und dann das Formular absenden, wobei Sie das empfangene Cookie beibehalten:

curl -c token.txt -b token.txt http://localhost:8000/login
curl -i -c token.txt -b token.txt -d "_csrf_token=...&login=marie&password=marie" http://localhost:8000/login
1
2
3
4
HTTP/1.1 302 Found
Location: /profile
Set-Cookie: token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJpZSIsIm5hbWUiOiJNYXJpZSBQXHUwMGU5bGlzc2llciIsInJvbGUiOiJVU0VSIiwiaWF0IjoxNzkwNTAyNzM3LCJleHAiOjE3OTA1MDYzMzd9.ijkEBdAyfFX9yFEyHOLAi-WhkFvShYW4mxoPIG2LqOI; expires=Sun, 27 Sep 2026 10:52:17 GMT; Max-Age=3600; path=/; httponly; samesite=lax
...

Das Token besteht aus drei durch Punkte getrennten, jeweils Base64-codierten Teilen: dem Header, dem Inhalt und der Signatur. Die ersten beiden Teile lassen sich ohne Schlüssel decodieren:

{"typ":"JWT","alg":"HS256"}
{"sub":"marie","name":"Marie P\u00e9lissier","role":"USER","iat":1790502737,"exp":1790506337}

(Das [é] wird in seiner JSON-Escape-Form geschrieben, [\u00e9].) Die Ablaufzeit liegt eine Stunde (3.600 Sekunden) nach der Erstellung. Im Browser zeigt die Profilseite denselben Inhalt an:

Image

Ein böswilliger Benutzer verändert sein Token: Er ersetzt im Inhalt die Rolle ***[USER]*** durch ***[ADMIN]***, codiert diesen Teil erneut in Base64 und behält die ursprüngliche Signatur bei. Der Server berechnet die Signatur des veränderten Inhalts neu, die nun nicht mehr übereinstimmt:

curl -i -b "token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<modified content>.ijkEBdAyfFX9yFEyHOLAi-WhkFvShYW4mxoPIG2LqOI" http://localhost:8000/profile
1
2
3
4
HTTP/1.1 302 Found
Location: /login
Set-Cookie: token=deleted; expires=Sat, 27 Sep 2025 09:52:20 GMT; Max-Age=0; path=/; httponly
...

Das gefälschte Token wird abgelehnt und gelöscht (der Wert [deleted] und das abgelaufene Datum weisen den Browser an, das Cookie zu löschen). Um eine gültige Signatur zu erzeugen, müsste man den geheimen Schlüssel kennen – daher ist es wichtig, ihn geheim zu halten und einen langen, zufälligen Schlüssel zu wählen.

8.2. Beispiel 26: Rollen

Beispiel 26 fügt eine Administrationsseite hinzu, die der Rolle ADMIN vorbehalten ist. Es werden nur neue oder geänderte Dateien angezeigt.

8.2.1. Die Konfiguration: config/packages/security.yaml

# config/packages/security.yaml: die Konfiguration des SecurityBundle (siehe Beispiel 25)
security:
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    providers:
        users:
            id: App\Security\UsersService

    # die HIERARCHIE der Rollen: Ein Administrator hat auch die Rechte eines Benutzers
    role_hierarchy:
        ROLE_ADMIN: ROLE_USER

    firewalls:
        resources:
            pattern: ^/bootstrap/
            security: false
        main:
            stateless: true
            provider: users
            custom_authenticators:
                - App\Security\TokenAuthenticator
            # ein authentifizierter Benutzer, der aber das angeforderte Recht nicht hat: unsere 403-Seite
            access_denied_handler: App\Security\AccessDenied

    # /profile: jeder authentifizierte Benutzer; /admin wird durch das Attribut #[IsGranted]
    # seines Controllers geschützt; wir hätten hier schreiben können:
    # - { path: ^/admin, roles: ROLE_ADMIN }
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • Zeilen 12–13: die Rollenhierarchie: Die Rolle [ROLE_ADMIN] schließt die Rolle [ROLE_USER] ein. Ein Administrator hat somit alle Rechte eines Benutzers, ohne dass ihm beide Rollen zugewiesen werden müssen;
  • Zeile 25: Der Handler für verweigerten Zugriff der Firewall ([access_denied_handler]): die Klasse, die die Antwort erzeugt, die an einen authentifizierten Benutzer gesendet wird, der eine Seite anfordert, die er nicht ansehen darf;
  • Zeilen 27–31: Die Seite [/admin] könnte hier mit einer zusätzlichen Regel geschützt werden; stattdessen schützen wir sie in ihrem Controller, um einen alternativen Ansatz zu zeigen.

Der Unterschied zwischen den beiden Verweigerungsantworten ist wichtig: Ein anonymer Besucher, der eine geschützte Seite anfordert, wird zum Einstiegspunkt der Firewall umgeleitet (der Anmeldeseite, Beispiel 25); ein authentifizierter Benutzer ohne die verlangte Rolle erhält einen 403-Fehler (Forbidden): Eine Anmeldung wäre sinnlos, da er bereits authentifiziert ist.

8.2.2. Zugriff verweigert: src/Security/AccessDenied.php

<?php
// src/Security/AccessDenied.php: die Antwort an einen AUTHENTIFIZIERTEN Benutzer, der
// eine für ihn verbotene Seite anfordert (siehe access_denied_handler in security.yaml)

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
use Symfony\Component\Security\Http\Authorization\AccessDeniedHandlerInterface;
use Twig\Environment;

class AccessDenied implements AccessDeniedHandlerInterface
{
    public function __construct(private Environment $twig)
    {
    }

    public function handle(Request $request, AccessDeniedException $accessDeniedException): ?Response
    {
        return new Response($this->twig->render('errors/403.html.twig'), Response::HTTP_FORBIDDEN);
    }
}
  • Zeile 13: Die Klasse implementiert die Schnittstelle [AccessDeniedHandlerInterface], deren einzige Methode [handle] die Verweigerungsantwort liefert;
  • Zeile 21: die 403-Fehlerseite, erzeugt von [Twig] (wie beim [ErrorPage]-Listener in Beispiel 24), mit dem Code 403 ([Response::HTTP_FORBIDDEN], eine Konstante der Klasse [Response]).

Ohne diesen Handler würde die Verweigerung eine Exception [AccessDeniedHttpException] auslösen, und der Benutzer sähe die 403-Fehlerseite von [Symfony] (im Debug-Modus detailliert). Die Seite [templates/errors/403.html.twig] ist eine Standard-Fehlerseite mit einem Link zurück zum Profil.

8.2.3. Der Controller: src/Controller/AdminController.php

<?php
// src/Controller/AdminController.php: eine der Rolle ADMIN vorbehaltene Seite

namespace App\Controller;

use App\Security\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;
use Symfony\Component\Security\Http\Attribute\IsGranted;

class AdminController extends AbstractController
{
    // #[IsGranted]: Die Action wird nur ausgeführt, wenn der Benutzer die Rolle ADMIN hat
    #[Route('/admin', methods: ['GET'])]
    #[IsGranted('ROLE_ADMIN')]
    public function display(#[CurrentUser] User $user): Response
    {
        return $this->render('admin/admin.html.twig', ['name' => $user->name]);
    }
}
  • Zeile 17: Das Attribut [#[IsGranted]] erlaubt die Ausführung der Action nur einem Benutzer, der die erforderliche Berechtigung besitzt, hier die Rolle [ROLE_ADMIN]. Ein anonymer Besucher wird zum Einstiegspunkt umgeleitet; einem authentifizierten Benutzer ohne diese Rolle wird der Zugriff verweigert. Auf die Klasse angewendet, würde das Attribut alle ihre Actions schützen.

Der Controller führt selbst keine Prüfungen durch. Im Code würde man eine Berechtigung mit [$this->isGranted('ROLE_ADMIN')] (liefert einen booleschen Wert) oder [$this->denyAccessUnlessGranted('ROLE_ADMIN')] (löst eine Verweigerungs-Exception aus) prüfen. Für Regeln, die feiner sind als eine Rolle („ein Benutzer darf nur seine eigenen Termine bearbeiten“), erlaubt [Symfony] die Definition von „Votern“ (Voter): Klassen, die eine Berechtigung festlegen und die von [#[IsGranted]] und [is_granted] wie Rollen abgefragt werden.

8.2.4. Die Profil-View

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{{ user.role == 'ADMIN' ? 'administrator' : 'user' }}</b>.</p>
  {# is_granted: hat der Benutzer diese Rolle? Der Block wird nur in diesem Fall angezeigt #}
  {% if is_granted('ROLE_ADMIN') %}
    <p><a href="/admin">The administration area</a></p>
  {% else %}
    <p><a href="/admin">The administration area</a> (which is forbidden to you)</p>
  {% endif %}
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {% for key, value in user.claims %}
      <tr><td><code>{{ key }}</code></td><td>{{ value }}</td></tr>
    {% endfor %}
  </table>
  {# Abmelden: ein POST-Formular, reduziert auf seinen Button #}
  <form method="post" action="/logout">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('logout') }}">
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • Zeilen 7–11: Die Funktion [is_granted] von [Twig] prüft die Berechtigung eines Benutzers. So wird vermieden, dass ein Link angezeigt wird, der zu einem Fehler führen würde; dies ist jedoch nur eine Komfortfunktion: Der eigentliche Schutz kommt von der Action selbst.

8.2.5. Ausführung

Marie mit der Rolle USER folgt dem Link zur Administrationsseite:

Image

Der Administrator hingegen hat Zugriff darauf:

Image

Mit [curl]: ein Benutzer mit der Rolle USER (angemeldet wie in Beispiel 25, mit in der Datei [token.txt] gespeicherten Cookies), gefolgt von einem anonymen Besucher:

curl -i -b token.txt http://localhost:8000/admin
curl -i http://localhost:8000/admin
HTTP/1.1 403 Forbidden
...
        <div class="alert alert-danger">
    <h1 class="h4">Error 403</h1>
    <p class="mb-0">Access denied: this page is reserved for administrators.</p>
  </div>
...
HTTP/1.1 302 Found
...
Location: /login
...

Das einzelne Schützen von Routen hat einen Nachteil: Wird eine übersehen, ist die Seite für alle zugänglich. Die Fallstudie kehrt diese Logik um: Alle URL-Seiten sind standardmäßig durch eine allgemeine [access_control]-Regel geschützt, und nur wenige URL-Seiten (die Anmeldeseite, die Registrierungsseite) sind ausgenommen.

8.3. Beispiel 27: CAPTCHA und Begrenzung der Versuche

Ein Anmeldeformular ist ein Angriffsziel: Ein Programm kann Tausende von Passwörtern pro Minute ausprobieren (Brute-Force-Angriff). Zwei Schutzmaßnahmen ergänzen sich:

  • ein CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart): ein Bild mit einem verzerrten Code, der für einen Menschen leicht, für ein Programm aber schwer lesbar ist;
  • eine Begrenzung der Versuche: Nach drei fehlgeschlagenen Versuchen wird die IP-Adresse des Clients eine Minute lang gesperrt.

Beispiel 27 baut auf Beispiel 25 auf und fügt diese beiden Sicherheitsmaßnahmen hinzu.

8.3.1. Das CAPTCHA-Bild: src/Security/CaptchaDrawing.php

<?php
// src/Security/CaptchaDrawing.php: das Zeichnen eines CAPTCHA, ein SVG-Bild (XML-Text),
// von Hand gebaut

namespace App\Security;

class CaptchaDrawing
{
    public const WIDTH = 150;

    public const HEIGHT = 50;

    // Die „Schrift“: Jedes Zeichen ist eine Liste von Strichen, jeder Strich eine
    // Folge von x,y-Punkten in einem 4 x 6 großen Raster (y nach unten).
    // Zeichen, die zu leicht miteinander zu verwechseln sind, sind ausgeschlossen (0 O, 1 I L).
    private const FONT = [
        'A' => [[0, 6, 2, 0, 4, 6], [0.8, 3.8, 3.2, 3.8]],
        'B' => [[0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3], [0, 0, 3, 0, 4, 1, 4, 2, 3, 3]],
        'C' => [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5]],
        'D' => [[0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0]],
        'E' => [[4, 0, 0, 0, 0, 6, 4, 6], [0, 3, 3, 3]],
        'F' => [[4, 0, 0, 0, 0, 6], [0, 3, 3, 3]],
        'G' => [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5]],
        'H' => [[0, 0, 0, 6], [4, 0, 4, 6], [0, 3, 4, 3]],
        'J' => [[4, 0, 4, 5, 3, 6, 1, 6, 0, 5]],
        'K' => [[0, 0, 0, 6], [4, 0, 0, 3.5], [1.3, 2.6, 4, 6]],
        'M' => [[0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6]],
        'N' => [[0, 6, 0, 0, 4, 6, 4, 0]],
        'P' => [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3]],
        'Q' => [[1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0], [2.5, 4.5, 4, 6.3]],
        'R' => [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3], [2, 3, 4, 6]],
        'S' => [[4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        'T' => [[0, 0, 4, 0], [2, 0, 2, 6]],
        'U' => [[0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0]],
        'V' => [[0, 0, 2, 6, 4, 0]],
        'W' => [[0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0]],
        'X' => [[0, 0, 4, 6], [4, 0, 0, 6]],
        'Y' => [[0, 0, 2, 3, 4, 0], [2, 3, 2, 6]],
        'Z' => [[0, 0, 4, 0, 0, 6, 4, 6]],
        '2' => [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6]],
        '3' => [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3], [3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        '4' => [[3, 6, 3, 0, 0, 4, 4, 4]],
        '5' => [[4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        '6' => [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3]],
        '7' => [[0, 0, 4, 0, 1.5, 6]],
        '8' => [[1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5,
            4, 4, 3, 3]],
        '9' => [[4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5]],
    ];

    // einige dunkle Farben, gut lesbar auf dem hellen Hintergrund
    private const COLORS = ['#1f4e79', '#7b2d26', '#2e6b30', '#5b2c83', '#8a5a00', '#23395d', '#9c2a5b'];

    // ein zufälliger Text. random_int ist ein „kryptografischer“ Generator,
    // unvorhersehbar (anders als rand oder mt_rand, deren Folge erraten werden könnte)
    public static function randomText(int $length): string
    {
        $alphabet = array_keys(self::FONT);
        $text = '';
        for ($i = 0; $i < $length; $i++) {
            $text .= $alphabet[random_int(0, count($alphabet) - 1)];
        }
        return $text;
    }

    // eine zufällige Gleitkommazahl zwischen $minimum und $maximum
    private static function random(float $minimum, float $maximum): float
    {
        return $minimum + ($maximum - $minimum) * random_int(0, PHP_INT_MAX) / PHP_INT_MAX;
    }

    private static function color(): string
    {
        return self::COLORS[random_int(0, count(self::COLORS) - 1)];
    }

    public static function svg(string $text): string
    {
        $l = self::WIDTH;
        $h = self::HEIGHT;
        $pieces = ["<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"$l\" height=\"$h\" viewBox=\"0 0 $l $h\">",
            '<rect width="100%" height="100%" fill="#f5f7fa"/>'];

        // die Zeichen: jedes vergrößert, geneigt, verschoben, und jeder Punkt
        // leicht zufällig bewegt
        $step = ($l - 20) / strlen($text);
        foreach (str_split($text) as $i => $character) {
            $scale = self::random(4.6, 5.6);    // Größe einer Einheit des Rasters, in Pixeln
            $angle = self::random(-0.35, 0.35);   // Rotation im Bogenmaß (etwa ±20°)
            $cx = 10 + $step * ($i + 0.5) + self::random(-3, 3);    // Mittelpunkt des Zeichens
            $cy = $h / 2 + self::random(-4, 4);
            foreach (self::FONT[$character] as $stroke) {
                $d = [];
                for ($k = 0; $k < count($stroke); $k += 2) {
                    // Punkt des Rasters, auf (2, 3) zentriert, verzerrt, gedreht, platziert
                    $x = ($stroke[$k] - 2 + self::random(-0.2, 0.2)) * $scale;
                    $y = ($stroke[$k + 1] - 3 + self::random(-0.2, 0.2)) * $scale;
                    $px = $cx + $x * cos($angle) - $y * sin($angle);
                    $py = $cy + $x * sin($angle) + $y * cos($angle);
                    $d[] = sprintf('%s%.1f %.1f', $k === 0 ? 'M' : 'L', $px, $py);
                }
                $pieces[] = sprintf('<path d="%s" fill="none" stroke="%s" stroke-width="%.1f" '
                    .'stroke-linecap="round" stroke-linejoin="round"/>',
                    implode(' ', $d), self::color(), self::random(2.2, 3));
            }
        }

        // 3 Störlinien: Kurven, die das Bild durchqueren
        for ($n = 0; $n < 3; $n++) {
            $pieces[] = sprintf('<path d="M%.1f %.1f C%.1f %.1f %.1f %.1f %.1f %.1f" fill="none" '
                .'stroke="%s" stroke-width="1.3"/>',
                self::random(0, 20), self::random(5, 45), self::random(30, 60), self::random(0, 50),
                self::random(90, 120), self::random(0, 50), self::random(130, 150), self::random(5, 45),
                self::color());
        }
        $pieces[] = '</svg>';
        return implode('', $pieces);
    }
}

Das Bild liegt im Format SVG (Scalable Vector Graphics) vor: eine Vektorzeichnung, die in XML – also als Text – beschrieben ist, vom Server ohne Grafikbibliothek erzeugt wird und die der Browser direkt in der Seite darstellt. Diese Klasse ist reines [PHP] ohne Framework-Besonderheiten: Sie ist identisch mit der [Laravel]-Version dieses Kurses.

  • Zeilen 16–49: eine minimalistische „Schrift“: Jedes Zeichen ist eine Liste von Strichen, und jeder Strich ist eine Liste von Koordinaten [x, y] in einem Raster von 4 × 6. Leicht zu verwechselnde Zeichen ([0] und [O], [1], [I] und [L]) sind ausgeschlossen;
  • Zeilen 56–64: eine zufällige Zeichenkette, ausgewählt aus den Zeichen der Schrift ([array_keys], die Schlüssel der Tabelle). Die Funktionen [rand] und [mt_rand] von [PHP] erzeugen vorhersagbare Zahlenfolgen (wer einige Werte kennt, kann die nächsten erraten): Sie eignen sich für Simulationen, nicht für Sicherheitszwecke. [random_int] ist ein kryptografischer Generator; er ist nicht vorhersagbar;
  • Zeilen 67–70: eine zufällige Gleitkommazahl, erzeugt aus einer zufälligen Ganzzahl ([PHP_INT_MAX] ist die größte Ganzzahl in [PHP]);
  • Zeilen 77–118: die Zeichnung. Jedes Zeichen wird zufällig skaliert, gedreht und verschoben, und jeder seiner Punkte wird leicht versetzt; jeder Strich wird zu einem Element [<path>] der SVG ([M]: Verschiebung, [L]: Linie). Drei Kurven ([C]: Bézierkurve) durchqueren das Bild, um Texterkennungsprogramme zu stören. Die Funktion [sprintf] formatiert eine Zeichenkette: [%s] fügt eine Zeichenkette ein, und [%.1f] fügt eine Zahl mit einer Nachkommastelle ein. [str_split] zerlegt eine Zeichenkette in Zeichen.

Die Klasse [Captcha] kombiniert die ID eines CAPTCHAs mit seinem Bild:

<?php
// src/Security/Captcha.php: ein CAPTCHA: sein Bezeichner und sein Bild (SVG)

namespace App\Security;

readonly class Captcha
{
    public function __construct(
        public string $id,
        public string $svg,
    ) {
    }
}

8.3.2. Der CAPTCHA-Service: src/Security/CaptchaService.php

<?php
// src/Security/CaptchaService.php: die ausstehenden CAPTCHAs, vom Server im
// Cache aufbewahrt (siehe Beispiel 20)

namespace App\Security;

use Psr\Cache\CacheItemPoolInterface;

class CaptchaService
{
    // die Lebensdauer eines CAPTCHA, in Sekunden
    private const LIFETIME = 600;

    public function __construct(private CacheItemPoolInterface $cache)
    {
    }

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);
        // ein zufälliger, nicht erratbarer Bezeichner: 12 Bytes, von einem
        // kryptografischen Generator gezogen (random_bytes), hexadezimal geschrieben (bin2hex)
        $id = bin2hex(random_bytes(12));
        // die erwartete Antwort im Cache, für 10 Minuten (expiresAfter): Der
        // Cache vergisst sie danach von selbst
        $item = $this->cache->getItem("captcha.$id");
        $this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // Das CAPTCHA wird in jedem Fall VERBRAUCHT: Ein Bild wird nur einmal verwendet
    public function check(?string $id, ?string $answer): bool
    {
        // Ein fehlerhaft aufgebauter Bezeichner kann kein Schlüssel des Caches sein
        if ($id === null || ! ctype_xdigit($id) || $answer === null) {
            return false;
        }
        $item = $this->cache->getItem("captcha.$id");
        // deleteItem: Die Antwort wird aus dem Cache entfernt, ob sie richtig ist oder nicht
        $this->cache->deleteItem("captcha.$id");
        if (! $item->isHit()) {
            return false;    // unbekannter Bezeichner oder abgelaufenes CAPTCHA
        }
        // strcasecmp gibt 0 für zwei gleiche Strings zurück, ohne Beachtung der Groß-/Kleinschreibung
        return strcasecmp($item->get(), trim($answer)) === 0;
    }
}
  • Zeilen 18–29: ein neues CAPTCHA: ein zufälliger Text, ein zufälliger, nicht erratbarer Bezeichner und das Bild. Zu jedem Bezeichner speichert der Server die erwartete Antwort zehn Minuten lang im Cache (Beispiel 20): Die Methode [expiresAfter] des Cache-Elements legt dessen Lebensdauer in Sekunden fest. Nach Ablauf dieser Zeit verwirft der Cache es automatisch. Die Seite erhält nur den Bezeichner und das Bild: Die Antwort verlässt den Server nie;
  • Zeilen 32–46: die Validierung. Der Bezeichner stammt vom Client: Wir prüfen zuerst, ob er aus Hexadezimalziffern besteht ([ctype_xdigit]), da bestimmte Zeichen ([{}()/\@:]) in Cache-Schlüsseln verboten sind und eine Exception auslösen würden. Das Element wird gelesen und dann aus dem Cache entfernt ([deleteItem]): Das CAPTCHA wird in jedem Fall verbraucht, ob erfolgreich oder nicht. Ohne dies könnte ein Programm alle möglichen Antworten für dasselbe Bild ausprobieren. Der Vergleich ignoriert die Groß- und Kleinschreibung ([strcasecmp] liefert 0 für zwei gleiche Zeichenketten, unabhängig von Groß- und Kleinbuchstaben) und Leerzeichen um die Eingabe ([trim]).

8.3.3. Begrenzung der Versuche: config/packages/framework.yaml

# config/packages/framework.yaml: die Konfiguration des FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # die Session: Sie wird nur für das Anti-CSRF-Token des Login-Formulars verwendet
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true
    # die Locks (siehe Beispiel 20): Der Limiter verwendet sie, um fehlerfrei zu zählen
    # die gleichzeitigen Versuche
    lock: 'flock://%kernel.project_dir%/var/lock'
    # die RATE LIMITER (Komponente RateLimiter); dieser, genannt [login],
    # akzeptiert 3 „Tokens“ pro Zeitfenster von 60 Sekunden
    rate_limiter:
        login:
            policy: fixed_window
            limit: 3
            interval: '60 seconds'
  • Zeile 11: Locks (Beispiel 20): Der Limiter verwendet sie, damit zwei gleichzeitige Anfragen seine Zählung nicht verfälschen;
  • Zeilen 14–18: ein Rate Limiter mit dem Namen [login]. Ein Rate Limiter verteilt „Tokens“ (ohne Bezug zum JWT-Token): Jede beschränkte Aktion verbraucht eines, und sind keine mehr übrig, wird die Aktion verweigert. Die Policy [fixed_window] (festes Fenster) gewährt 3 Tokens pro Zeitraum von 60 Sekunden, gezählt ab dem ersten verbrauchten Token. Es gibt weitere Policies: [sliding_window] (ein gleitendes Fenster, gleichmäßiger), [token_bucket] (ein Eimer, der sich mit einer bestimmten Rate füllt). Die Zähler werden im Anwendungs-Cache gespeichert.

Für jeden deklarierten Limiter erstellt [Symfony] einen Limiter-Factory-Service ([RateLimiterFactoryInterface]), den man per Injektion unter einem Parameternamen erhält, der sich aus dem Namen des Limiters gefolgt von [Limiter] zusammensetzt: [$loginLimiter].

8.3.4. Der Controller: src/Controller/AuthController.php

<?php
// src/Controller/AuthController.php: Login (mit CAPTCHA und Begrenzung der
// Versuche) und Logout

namespace App\Controller;

use App\Security\AuthService;
use App\Security\CaptchaService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
use Symfony\Component\Routing\Attribute\Route;

class AuthController extends AbstractController
{
    // $loginLimiter: die Factory des Limiters [login] (siehe config/packages/framework.yaml);
    // der Name des Parameters bezeichnet den Limiter
    public function __construct(
        private AuthService $auth,
        private CaptchaService $captchas,
        private RateLimiterFactoryInterface $loginLimiter,
    ) {
    }

    #[Route('/', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirect('/profile');
    }

    #[Route('/login', methods: ['GET'])]
    public function form(): Response
    {
        return $this->loginPage();
    }

    #[Route('/login', methods: ['POST'])]
    public function login(Request $request): Response
    {
        $inputs = $request->getPayload();
        if (! $this->isCsrfTokenValid('login', $inputs->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $login = $inputs->getString('login');
        // der Limiter DIESES Clients: Der Schlüssel seines Fehlerzählers ist seine IP-Adresse
        $limiter = $this->loginLimiter->create($request->getClientIp());

        // 1. Auf eine gesperrte Adresse wird gar nicht erst gehört; consume(0) fragt den
        // Zähler ab, ohne etwas zu verbrauchen
        $state = $limiter->consume(0);
        if ($state->getRemainingTokens() === 0) {
            $seconds = $state->getRetryAfter()->getTimestamp() - time();
            return $this->loginPage($login, "Too many attempts: try again in $seconds s.");
        }
        // 2. zuerst das CAPTCHA (billig), danach das Passwort (bcrypt, teuer);
        // consume(): ein weiterer Fehlversuch
        if (! $this->captchas->check($inputs->getString('captchaId'), $inputs->getString('captcha'))) {
            $limiter->consume();
            return $this->loginPage($login, 'The image code is incorrect.');
        }
        $user = $this->auth->validate($login, $inputs->getString('password'));
        if ($user === null) {
            $limiter->consume();
            return $this->loginPage($login, 'Incorrect login or password.');
        }
        // Ein erfolgreiches Login löscht die Fehlversuche
        $limiter->reset();
        $response = $this->redirect('/profile');
        $response->headers->setCookie(Cookie::create(AuthService::COOKIE, $this->auth->createToken($user))
            ->withExpires(time() + $this->auth->durationMinutes * 60)
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    #[Route('/logout', methods: ['POST'])]
    public function logout(Request $request): Response
    {
        if (! $this->isCsrfTokenValid('logout', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $response = $this->redirect('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }

    // Jede Anzeige des Formulars baut ein NEUES CAPTCHA
    private function loginPage(?string $login = null, ?string $error = null): Response
    {
        return $this->render('auth/login.html.twig', ['login' => $login, 'error' => $error,
            'captcha' => $this->captchas->generate()]);
    }
}
  • Zeilen 21–26: Der Controller erhält die Factory für den Limiter [login];
  • Zeile 49: der Limiter dieses Clients, [create(key)], liefert einen Limiter, der unter diesem Schlüssel einen eigenen Zähler hat – hier die IP-Adresse des Clients ([getClientIp()]);
  • Zeilen 53–57: Eine gesperrte Adresse wird gar nicht erst angehört. [consume(0)] fragt den Limiter ab, ohne etwas zu verbrauchen; das zurückgegebene Objekt [RateLimit] liefert die Anzahl der verbleibenden Tokens ([getRemainingTokens()]) und den Zeitpunkt, ab dem die Aktion wieder erlaubt ist ([getRetryAfter()]), woraus sich die Anzahl der Sekunden ableiten lässt, die zu warten sind;
  • Zeilen 60–68: Das CAPTCHA wird vor dem Passwort überprüft; seine Überprüfung kostet fast nichts, während [bcrypt] absichtlich langsam ist. Ein Programm, das ein falsches CAPTCHA eingibt, würde daher [bcrypt] nicht auslösen. Jeder Fehlschlag – sei es beim CAPTCHA oder beim Passwort – verbraucht ein Token ([consume()], das standardmäßig eines verbraucht). Nach dem dritten Fehlschlag ist kein Token mehr übrig: Die Adresse ist bis zum Ende des 60-Sekunden-Fensters gesperrt, gezählt ab dem ersten Fehlschlag;
  • Zeile 70: Eine erfolgreiche Anmeldung setzt die fehlgeschlagenen Versuche zurück ([reset()]);
  • Zeilen 91–95: Bei jeder Anzeige des Formulars wird ein neues CAPTCHA erzeugt, auch nach einem fehlgeschlagenen Versuch.

Das SecurityBundle bietet außerdem eine eingebaute Begrenzung der Anmeldeversuche (die Firewall-Option [login_throttling] ), die für seine eigenen Login-Authenticators ([form_login] ...) gilt, nicht für unsere Action. Um die Anzahl der Anfragen für eine Route zu begrenzen, würden wir einen Limiter auf dieselbe Weise verwenden, entweder innerhalb der Action oder in einem Listener für [kernel.request]. Wir haben uns entschieden, nur die fehlgeschlagenen Versuche zu zählen, um einen Benutzer, der sich normal anmeldet, nicht zu behindern.

8.3.5. Die View: templates/auth/login.html.twig

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('login') }}">
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login }}" required>
    </div>
    <div class="mb-2">
      <label class="form-label" for="password">Password</label>
      <input class="form-control" type="password" id="password" name="password" required>
    </div>
    <div class="mb-3">
      <label class="form-label" for="captcha">Copy the code of the image</label>
      {# das SVG-Bild, vom Server erstellt: ohne Maskierung eingefügt (Filter raw) #}
      <div class="mb-1">{{ captcha.svg|raw }}</div>
      {# die Captcha-Kennung wandert in einem versteckten Feld; die Antwort bleibt auf dem Server #}
      <input type="hidden" name="captchaId" value="{{ captcha.id }}">
      <input class="form-control" id="captcha" name="captcha" autocomplete="off" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  {% if error %}
    <div class="alert alert-danger mt-3">{{ error }}</div>
  {% endif %}
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
{% endblock %}
  • Zeile 18: Die SVG-Grafik wird unverändert, ohne Escaping, in die Seite eingefügt (Filter [raw], Beispiel 14). Das ist zulässig: Dieses HTML wurde vom Server erzeugt und enthält keine Benutzereingaben;
  • Zeile 20: die CAPTCHA-ID in einem versteckten Feld;
  • Zeile 21: Der Browser schlägt für dieses Feld keine früheren Eingaben vor.

8.3.6. Ausführung

Image

Ein fehlerhaft abgeschriebener Code:

Image

Nach drei fehlgeschlagenen Versuchen wird die Adresse gesperrt:

Image

Mit [curl] vier Versuche mit einer erfundenen CAPTCHA-ID (nachdem man wie in Beispiel 25 das Session-Cookie und das Anti-CSRF-Token besorgt hat):

curl -b cookies.txt -d "_csrf_token=...&login=marie&password=marie&captchaId=abc&captcha=XXXXX" http://localhost:8000/login
1
2
3
4
      <div class="alert alert-danger mt-3">The image code is incorrect.</div>
      <div class="alert alert-danger mt-3">The image code is incorrect.</div>
      <div class="alert alert-danger mt-3">The image code is incorrect.</div>
      <div class="alert alert-danger mt-3">Too many attempts: try again in 60 s.</div>

Selbst mit dem richtigen Passwort wird der vierte Versuch abgelehnt, ohne bearbeitet zu werden.