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 setzen voraus, dass Sie bereits ein HTML-Formular für die Registrierung von Usern haben.

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

Unser Widget wird ein Formularfeld hinfügen, in dass der Seitenbenutzer seine Telefonnummer eintragen kann. Die Verifizierung der Nummer erfolgt noch vor dem Abschicken des Registrierungsformulars.

Um das Widget zu integrieren, binden Sie folgenden JavaScript-Tag (<form>-Tag) im HTML-Dokument des Formulars ein und platzieren Sie es idealerweise vor dem Submit-Button:

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

Nun wird das Widget angezeigt.

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

Sie können das Widget mit mehreren Parametern anpassen, wobei nur bsmsSitekey zwingend erforderlich ist.

Link: Wie erhalte ich einen Sitekey?

Hängen Sie den Sitekey als Script-Parameter an:

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

 Damit funktioniert nun das Widget.

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

Allerdings empfehlen wir Ihnen, den Button noch nicht zu aktivieren, denn das Formular lässt sich im Moment auch ohne Verifizierung der Telefonnummer abschicken. Die Überprüfung der Rufnummer auf Seiten des Servers würde fehlschlagen.

Um den Button bis zur Verifikation inaktiv zu lassen, setzen Sie ihn initial auf „disabled“. Fügen Sie außerdem eine eindeutige id (z.B. „send-register-form“) hinzu.

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

Um den Button nach der Verifikation wieder auf „enabled“ zu stellen, übergeben Sie dem Script den Parameter „onSolved“. Dieser Parameter bekommt als Wert einen Callback, der nach der Verifikation verarbeitet wird:

<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>

Nun lässt sich das Formular erst nach Eingabe und Validierung der Telefonnummer abschicken.

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

Serverseitig – per PHP

Serverseitig – per PHP

Downloaden und entpacken Sie die TwoFA-Optin-Bibliothek von BerlinSMS:

Link: https://static.berlinsms.de/twofa/twofa-optin.zip

Laden Sie die dekomprimierte PHP-Datei in Ihren Webspace hoch und binden Sie sie in Ihrem Projekt ein:

include 'twofa/twofa-optin.php';

Integrieren Sie anschließend den privaten Schlüssel (Sitekey) von BerlinSMS in Ihren Code.

Link: Wie erhalte ich einen Sitekey?

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 den POST-Parameter aus, den Sie vom Formular erhalten haben.

$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 wurde verifiziert
  • verifiedAddress (string): die bestätigte Telefonnummer
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

Installieren Sie zuerst das Paket „@berlinsms/twofa-verify“:

npm install @berlinsms/twofa-verify

Importieren Sie das Paket in Ihr Projekt:

import { TwofaOptin } from '@berlinsms/twofa-verify';

Binden Sie anschließend den privaten Schlüssel (Secretkey) von BerlinSMS in Ihren Code ein:

Link: Wie erhalte ich einen Sitekey?

const twofaSecretkey= "<your_secret_key>";

Erzeugen Sie ein Objekt der importieren Klasse „TwofaOptin“. Übergeben Sie den Secretkey als Parameter:

const twofaOptin = new TwofaOptin(twofaSecretkey);

Lesen Sie die Postparameter aus, die Sie vom Formular erhalten haben:

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);

Werten Sie die Rückmeldung aus. Das zurückgegebene Objekt enthält in der Regel zwei Elemente:

  • solved (boolean): Telefonnummer wurde verifiziert
  • verifiedAddress (string): die bestätigte Telefonnummer
if (twofaChallenge.solved) {
      // twofa-optin-Überprüfung erfolgreich, 
      // "twofaChallenge.verifiedAddress" enthält die überprüfte Telefonnummer
} else {
      // twofa-optin-Überprüfung nicht erfolgreich
}