Einbindung
TwoFA-Optin

Voraussetzung

Legen Sie zunächst ein Konto auf BerlinSMS an, um TwoFA-Optin verwenden zu können. Loggen Sie sich anschließend auf https://twofa.berlinsms.de ein und laden sie sich den Sitekey und den Secretkey herunter.

→ Wie erhalte ich einen Sitekey?

Einbindungen

Clientseitig – per React-Komponente

Clientseitig – per React-Komponente

React Komponente

@berlinsms/react-twofa-component ist ein TypeScript React-Komponente zur Validierung von Telefonnummern oder E-Mail-Adressen unter Verwendung einer Zwei-Faktor-Authentifizierung. BerlinSMS

Installation

bash 
npm -i @berlinsms/react-twofa-component

Verwendung

Die Verifizierung von E-Mails und SMS befindet sich jetzt in derselben Komponente. Die Komponente wechselt automatisch zur zuvor ausgewählten Verifizierungsmethode (https://app.berlinsms.de/keygen).

.js 
import {TwoFA} from '@berlinsms/react-twofa-component';

// Minimale Implementierung:
<TwoFA
    bsmsSitekey = {"Ihr Site-Schlüssel"}
/>

// Vollständige Implementierung: 
<TwoFA
    ref={twoFARef}                    
    bsmsSitekey = {"Ihr Site-Schlüssel"}
    onError = {TwoFAonError}
    onVerify = {TwoFAonVerify}
    onExpire = {TwoFAonExpire}
/>

Parameter

Um diese Komponente zu verwenden, müssen Sie Ihre Einstellungen auf https://app.berlinsms.de/keygen konfigurieren.

Durch Verwendung des erforderlichen bsmsSitekey-Parameters wird Ihre Website validiert und alle vordefinierten Einstellungen geladen. Diese Komponente fordert Ihre ausgewählte Verifizierungsmethode an und lädt automatisch die vordefinierte Konfiguration. Daher ist es nicht erforderlich, manuell zwischen E-Mail-Verifizierung und SMS-Verifizierung zu wechseln. Diese Einstellungen enthalten auch Ihren Captcha-Typ und Schlüssel.

Der ref-Parameter hilft dem Benutzer, den aktuellen Objektstatus im Auge zu behalten. Durch Erstellen einer Referenz können zusätzliche Informationen wie beispielsweise die Status abgerufen werden. Alle Statuscodes können in der Datei TwoFATypes.tsx eingesehen werden und werden unten beschrieben.

Die onError-Funktion wird aufgerufen, wenn ein Fehler auftritt. Dies kann beispielsweise bedeuten, dass die Komponente die API nicht erreichen kann oder der Benutzer keine weiteren Versuche mehr hat. Die Funktion erfordert einen Fehler: String-Parameter, der den Fehler beschreibt.

Die onVerify-Funktion wird aufgerufen, wenn der Benutzer den Code korrekt eingegeben hat und Ihr eigener Webserver nun die Benutzeranfrage validieren kann. Der Token (String)-Parameter ist erforderlich und wird für die endgültige überprüfung benötigt. Optional kann der eingegebene Zwei-Faktor-Code angefordert werden: code?: String

Die Sprache kann durch Verwendung des optionalen Parameters bsmsLanguage festgelegt werden. (bsmsLanguage?: "Eng" | "Ger";) Dieser Parameter nimmt die Werte "Eng" oder "Ger" (Deutsch) an. Die Standardsprache ist Deutsch.

OnExpire wird aufgerufen, wenn die Zeit zum Ausfüllen der Komponente abgelaufen ist. Diese Funktion befindet sich noch in der Entwicklung.

Statuscodes

.js 
verificationType: verificationTypes; // gibt die ausgewählte Verifizierungsmethode zurück (optin(sms) oder optin(mail)
apiReady: boolean; // überprüft, ob die BerlinSMS-API erreichbar ist
isAddressValid: boolean; // überprüft, ob eine SMS/E-Mail an die Telefonnummer gesendet werden kann
codeReady: boolean; // Der Benutzer hat auf Code senden geklickt -> um einen Code zu senden, muss der Benutzer das Captcha lösen, das den Code sendet
codeSend: boolean; // Der Code wurde per SMS an die eingegebene Telefonnummer gesendet
codeVerified: boolean; // Dies ist wahr, wenn der eingegebene Code korrekt ist (onVerify wird aufgerufen)
errorOccured: boolean; // Dies ist wahr, wenn ein Fehler aufgetreten ist (onError wird aufgerufen)
errorMessage: string; // Dies gibt zusätzliches Fehler-Feedback und zeigt es in der Komponente an
// interne Statuscodes
renderstatus: renderStatusTypes; // Zustände für die Statusmaschine zum Rendern des Inhalts
captchaSitekey: string; // Der aktuelle Captcha-Site-Schlüssel
captchaType: "reCaptcha" | "hCaptcha"; // welcher Captchatyp verwendet wird
captchaToken: string; // Captchatoken, wenn das Captcha gelöst ist
validationCode: string; // aktuelle Benutzereingabe des Validierungscodes
challengeToken: string; // Challenge-Token für die BSMS TwoFA-Challenge
// interne Variablen
limitAttempts: number; // signalisiert, wie viele Versuche der Benutzer hat, die TwoFA-Herausforderung zu lösen
verificationAddress: string; // Telefonnummer/E-Mail-Adresse, die der Benutzer eingegeben und an die ein Code gesendet wurde
Clientseitig – per HTML/JS

Clientseitig – per HTML/JS

Wir gehen davon aus, dass bereits ein HTML-Formular zur Benutzerregistrierung existiert.

Beispiel: https://samples.berlinsms.de/twofa-optin/demo-form-noWidget.html

Es soll nun ein Formularfeld hinzugefügt werden, in dass der Seitenbenutzer seine Telefonnummer eintragen kann, welche bereits vor dem Abschicken des Registrierungsformulars verifiziert wird.

Um das Widget einzubinden, muss folgender JavaScript-Tag in das Formular, also in das <form>-Tag im HTML-Dokument eingebunden werden. Am besten vor dem Submit-Button.

<script src="https://static.berlinsms.de/twofa/twofa-optin.js"></script>

Das war es eigentlich schon, das Widget wird angezeigt.

Beispiel: https://samples.berlinsms.de/twofa-optin/demo-form-noSitekey.html

Es gibt mehrere Parameter, mit denen das Widget angepasst werden kann. Wichtig und notwendig ist davon nur einer: bsmsSitekey. Deshalb auch die Fehlermeldung.

Link: Wie erhalte ich einen Sitekey?

Der Sitekey wird als Script-Parameter angehängt.

 <script src="https://static.berlinsms.de/twofa/twofa-optin.js?bsmsSitekey=[Sitekey]"></script>

 Damit ist das Widget  funktionstüchtig.

Beispiel: https://samples.berlinsms.de/twofa-optin/demo-form-noCallback.html

Es fällt jedoch auf, dass das Formular immer noch abgeschickt werden kann, ohne dass die Telefonnummer verifiziert worden ist. Das wäre zwar kein Problem, da die serverseitige Verifizierung feststellen würde, dass die Telefonnummer noch nicht verifiziert worden war. Eleganter ist es jedoch, den Button so lange zu deaktivieren.

Dazu muss der Button eine eindeutige id (z.B. „send-register-form“) erhalten und initial auf „disabled“ gesetzt werden:

<button type=“submit“ id=“send-register-form“  disabled>

Nach der Verifikation kann der Button per Javascript wieder enabled werden. Dazu kann dem Script der Parameter „onSolved“ übergeben werden. Dieser Parameter bekommt als Wert einen Callback, der per Javascript im Formular gahändelt werden muss:

<script src="https://static.berlinsms.de/twofa/twofa-optin.js?bsmsSitekey=[Sitekey]&onSolved=callback"></script>
<script language="javascript">
    function callback() {
        console.log('--->Event: bsmsOnLoadCallback');
        document.getElementById("send-register-form").disabled = true;
    }
</script>

Damit kann man das Formular erst abschicken, nachdem die Telefonnummer eingegeben und validiert worden ist.

Beispiel: https://samples.berlinsms.de/twofa-optin/demo-form.html  

Serverseitig – per PHP

Serverseitig – per PHP

  • Zuerst müssen Sie die Twofa-Optin-Bibliothek von Berlinsms herunterladen und entpacken:
  • Laden Sie die entpackte PHP-Datei in Ihren Webspace hoch und binden Sie sie in Ihrem Projekt ein:
include 'twofa/twofa-optin.php';
define("TWOFA_Secretkey", "[Secret-Key]");
  • Erzeugen Sie ein Objekt der importierte Klasse TwofaOptin. Übergeben Sie den Secretkey als Parameter:
$twofaChallenge = new TwofaOptin(TWOFA_Secretkey);
  • Lesen Sie die Postparameter aus, die Ihnen vom Formular geschickt wurden.
$twofaChallengeToken = $_POST['challengeToken']
  • Führen Sie die Twofa-Optin-Überprüfung durch, indem Sie die Funktion „getChallenge“ auf der oben erzeugten Klasse ausführen. Übergeben Sie den challengeToken als Parameter:
$twofaChallenge = $twofaChallenge->getChallenge($twofaChallengeToken);
  • Werten Sie die Rückmeldung aus. Das zurückgegebene Objekt enthält in der Regel zwei Elemente:
  • solved (boolean): Telefonnummer ist verifiziert
  • verifiedAddress (string): Telefonnummer, die bestätigt werden sollte
if ($twofaChallenge->solved) {
      // twofa-optin-Überprüfung erfolgreich, 
      // "$twofaChallenge->verifiedAddress" enthält die überprüfte Telefonnummer
} else {
      // twofa-optin-Überprüfung nicht erfolgreich
}
Serverseitig – per JS

Serverseitig – per JS

  • Zuerst müssen Sie das Paket “@berlinsms/twofa-verify” installieren:
npm install @berlinsms/twofa-verify
  • Importieren Sie das Paket in Ihrem Projekt:
import { TwofaOptin } from '@berlinsms/twofa-verify';
const twofaSecretkey= "<your_secret_key>";
  • Erzeugen Sie ein Objekt der importierte Klasse TwofaOptin. Übergeben Sie den Secretkey als Parameter:
const twofaOptin = new TwofaOptin(twofaSecretkey);
  • Lesen Sie die Postparameter aus, die Ihnen vom Formular geschickt wurden:
const challengeToken = req.body.challengeToken;
  • Führen Sie die Twofa-Optin-Überprüfung durch, indem Sie die Funktion „getChallenge“ auf der oben erzeugten Klasse ausführen.
  • Übergeben Sie den challengeToken als Parameter:
const twofaChallenge = await twofaOptin.getTwofaChallenge(challengeToken);
  • Führen Sie die Twofa-Optin-Überprüfung durch, indem Sie die Funktion „getChallenge“ auf der oben erzeugten Klasse ausführen.
  • Übergeben Sie den challengeToken als Parameter:
const twofaChallenge = await twofaOptin.getTwofaChallenge(challengeToken);
  • Werten Sie die Rückmeldung aus. Das zurückgegebene Objekt enthält in der Regel zwei Elemente:
  • solved (boolean): Telefonnummer ist verifiziert
  • verifiedAddress (string): Telefonnummer, die bestätigt werden sollte
if (twofaChallenge.solved) {
      // twofa-optin-Überprüfung erfolgreich, 
      // "twofaChallenge.verifiedAddress" enthält die überprüfte Telefonnummer
} else {
      // twofa-optin-Überprüfung nicht erfolgreich
}