Einbindung
TwoFA-Optin

Voraussetzung

Um Twofa-Optin von Berlinsms verwende zu können benötigen sie zuerst ein Berlinsms-Konto. Sobald Sie das erstellt haben, können Sie sich auf der Seite https://twofa.berlinsms.de einloggen und sich Sitekey und Secretkey herunterladen.

Wie erhalte ich einen Sitekey?

Einbindungen

Clientseitig – per React-Komponente

Clientseitig – per React-Komponente

kommt in Kürze

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
}