Framework
- Paul Maul
- Sebastian Schulz
- Dirk Münker
Die Module zur Zwei-Faktor-Authentifikation dienen der Steigerung der Sicherheit Sicherheit im Umgang mit brandbox, indem die Logins zu brandbox durch diverse zweite Faktoren abgesichert werden können. Die Sicherheitsmechanismen stehen als optionale Pakete für den administrativen Bereich und das Portal zur Verfügung. Die Zwei-Faktor-Authentifizierung kann von Administratoren im geschützten Bereich eingerichtet werden. Die nötigen Konfigurationstabellen finden sich in der Kachel Zwei-Faktor-Authentifizierung im Bereich Sicherheit . Wurde mindestens ein Authentifikationsverfahren für einen Endpunkt konfiguriert und wurden alle Bedingungen für dieses Verfahren erfüllt, so wird dem Nutzer ein zusätzlicher Code beim Login abgefordert.
Für Entwickler
Das Basispaket für die Zwei-Faktor-Authentifizierung ist framework-tfa . Die Basiskomponente Tfa/Tfa. In dieser Basiskomponente befinden sich öffentliche Methoden, um die Zwei-Faktor-Authentifizierung auszulösen und die Eingaben der Authentifikatoren zu verarbeiten. Das Verhalten dieser Methoden ist über Events beeinflussbar. Ein essentielles Merkmal zur Steuerung dieser Events ist der Identifikator des Authentifikators. Tfa/Tfa bietet eine abstrakte Authentifikatorklasse an, welche von den Implementationstellen genutzt werden kann: \Brandbox\FrameworkTfa\Tfa\Tfa\Lib\Struct\TwoFactorAuthenticatorAbstract . Diese abstrakte Klasse folgt dem entsprechenden Interface: \Brandbox\FrameworkTfa\Tfa\Tfa\Lib\Struct\TwoFactorAuthenticatorInterface . Authentifikatoren müssen von dem Interface ableiten, um in brandbox konfigurativ nutzbar zu sein. Die abstrakte Klasse bietet eine statische Methdoe an, um den Identifikator des Authentifikators zu ermitteln, um den Identifikator für die Events nutzen zu können. Darüberhinaus wird bei manchen Einstiegspunkten auch ein Identifikator des Endpoints gefordert und entsprechend in den Events bereitgestellt. Dieser Endpunktidentifikator kann genutzt werden, um die richtige Verhaltensweise sicherzustellen, falls beispielsweise die Zwei-Faktor-Authentifizierung für den administrativen Bereich anders konfiguriert wurde, als für das Portal.
Die Kachel Zwei-Faktor-Authentifizierung trägt den Identifikator FrameworkTfaPanel .
Events
Event | Beschreibung |
|---|---|
| Dieses Event wird genutzt, um das Authentifizierungsverfahren auszulösen. Es wird der Identifikator des Authentifikators und der einzuloggende (verifizierte!) Nutzer erwartet. Anhand des Identifikators wird ein Event Listener eines Authentifikators auf dieses Event reagieren und ggf. den Prozess für den einzuloggenden Nutzer initiieren. Bsp: Verfügt der Nutzer über eine E-Mail, wird der Mail-Authentifikator eine Mail mit dem Code an die E-Mail Adressse des Nutzers senden, sofern es sich um den Identifikator des Mail-Authentifikators handelt. Ausgelöst wird dieses Event durch die Methode |
| Dieses Event bietet die Möglichkeit den Container zur Eingabe des Codes zu beeinflussen. Es wird der Endpunktidentifikator erwartet und über das Event bereitgestellt. Anhand der Konfiguration des Endpunkts kann der Inhalt des Containers bestimmt werden. Ausgelöst wird dieses Event durch die Methode: \Brandbox\FrameworkTfa\Tfa\Tfa\Manager::getContainerSubmitTfaCode |
| Dieses Event wird genutzt, umd den eingegeben Code zu validieren. Es werden der einzuloggende Nutzer, Endpunktidentifikator und Authentifikatoridentifikator erwartet. Die Validität kann über ein boolesches Flag im Event kommuniziert werden. Zum Feedback an den Nutzer steht ein AdvancedResponseStack-Objekt zur Verfügung. |
| Ein Event, welches ein clean up signalisiert. Das Event enthält keine Daten. Es kann bspw. von den Authentifikatoren genutzt werden, um ggf. flüchtige Daten aus der Session zu löschen. Ausgelöst wird dieses Event durch die Methode |
Mail-Authentikator
Ein Authentifikator für die Zwei-Faktor-Authentifizierung ist der Mail-Authentifikator. Dieser Authentifikator erfordert keine besondere Einrichtung. Sofern die Zwei-Faktor-Authentifizierung für einen Endpunkt aktiviert und der Mail-Authentifikator eingestellt wurde, wird beim Login ein Code generiert, in der Session persistiert und an den einzuloggenden Nutzer per Mail versandt.
Die zeitliche Gültigkeit dieses Codes ist in der Konfigurationstabelle Allgemeine Konfiguration (2FA) einstellbar.
Für Entwickler
Der Mail-Authentifikator ist im Paket framework-tfa als Komponente Tfa/Mail enthalten. Die Funktionalität wird durch Eventlistener in den 2FA-Prozess eingebracht.
Eventlistener
Event | Funktion |
|---|---|
| Auf dieses Event wird, wenn bisher kein anderer zweiter Faktor ausgelöst wurde, der Identifikator mit dem Identifikator des Authentifikators übereinstimmt und es sich um einen validen Nutzer handelt. Es wird ein Code generiert und in der Session persistiert. Zudem wird der Startzeitpunkt des 2FA-Prozesses gespeichert, um die zeitliche Gültigkeit des Codes zu limitieren. Der Code wird über eine Mail an den Nutzer übermittelt und die Propagation des Events wird gestoppt. |
| Dieses Event wird genutzt, um Hinweistexte im Formular zur Codeeingabe zu platzieren, die den Nutzer über das Verhalten des Mail-Authentifikators informieren. |
| In dem Eventlistener für dieses Event wird der eingegebene Code auf Korrektheit und zeitliche Gültigkeit geprüft. Die zeitliche Gültigkeit ist der Konfigurationstabelle |
| Durch diesen Eventlistener werden die temporären Daten aus der Session wieder entfernt. |
| Dieses Event wird genutzt, um die Konfigurationstabelle Allgemeine Konfiguration (2FA) zu erweitern. |
OTP-Authentifikator
Ein Authentifikator für die Zwei-Faktor-Authentifizierung ist der OTP-Authentifikator. Dieser Authentifikator muss von den Nutzern selbst eingerichtet werden, um genutzt werden zu können. Dafür ist eine Authenticator-App auf einem Smartphone notwendig (bspw. Free-Otp, Google Authenticator etc.). Pro Nutzer kann nur ein Authenticator eingerichtet werden. Wenn ein Authentifikator eingerichtet wurde, werden außerdem Recovery-Codes erstellt, die es dem Nutzer einmalig erlauben einen Login ohne über App-generierten Code durchzuführen. Das ist notwendig, falls bspw. das Endgerät mit App abhanden kommt. Die Gültigkeitsdauer (Periode) der Codes ist in der Tabelle Allgemeine Konfiguration (2FA) einstellbar.
Es werden derzeit nur TOTP-Authentifikatoren untersützt.
Für Entwickler
Der Otp-Authentifikator ist im Paket framework-tfa als Komponente Tfa/Otp enthalten. Die Funktinalität wird durch Eventlistener in den 2FA-Prozess eingebracht.
Eventlistener
Event | Funktion |
|---|---|
| Auf dieses Event wird, wenn bisher kein anderer zweiter Faktor ausgelöst wurde, der Identifikator mit dem Identifikator des Authentifikators übereinstimmt und es sich um einen validen Nutzer handelt. Verfügt der Nutzer außerdem über einen eingerichteten OTP-Authentifikator, wird das 2FA-Verfahren eingeleitet. |
| Dieses Event wird genutzt, um Hinweistexte im Formular zur Codeeingabe zu platzieren, die den Nutzer über das Verhalten des OTP-Authentifikators informieren. |
| In dem Eventlistener für dieses Event wird der eingegebene Code auf Korrektheit geprüft. Es gibt einen weiteren Eventlistener, der überprüft, ob es sich bei dem eingegebenen Code um einen Recovery-Code handelt. Ist das der Fall, wird der entsprechende Recovery-Code gelöscht. |
| Dieses Event wird genutzt, um die Konfigurationstabelle |
Die Manager-Klasse von Tfa/Otp bietet einige Methoden zur Einrichtung von Authentifikatoren an. Eine zentrale Methode ist \Brandbox\FrameworkTfa\Tfa\Otp\Manager::getFormSetAuthenticator. Diese Methode liefert ein vollständiges Formular, mit dem ein Authentifikator eingerichtet werden kann. Dieses Formular enthält ein Eingabefeld für einen Code und einen QR-Code, der von einer Authenticator-App einzuscannen ist. Mit dem gescannten Code kann nun ein Code erzeugt und eingegeben werden. Wenn Server und Authenticator-App den gleichen Code generieren, wird der Authentifikator gespeichert. Dafür wird die Methode \Brandbox\FrameworkTfa\Tfa\Otp\Manager::createSecret genutzt.
Eingerichtete Authentifikatoren werden in der Tabelle OtpSecret gespeichert. Diese Tabelle enthält die Recovery-Codes und die ProvisioningUrl, die beim Einrichten des Authentifikators genutzt wird.