Zwei-Faktor-Authentifizierung über die OXAPI

Ab V. 4.0 können sich Konten mit aktivierter Zwei-Faktor-Authentifizierung (2FA) auch über die OXAPI anmelden. Bis dahin schlossen sich 2FA und OXAPI gegenseitig aus. Diese Seite richtet sich an Entwickler, die ein headless-basiertes Frontend über die OXAPI anbinden.

Die fachlichen Grundlagen der 2FA (shopweite Aktivierung, Aktivierung durch den Kunden, Code-Gültigkeit, Fehlversuche) sind unter Zwei-Faktor-Authentifizierung beschrieben und gelten für die OXAPI unverändert.

Geltungsbereich

Die OXAPI-2FA gilt für jedes Konto, das sich über die OXAPI anmeldet — unabhängig von den Benutzerrechten. Auch ein Admin-Benutzerkonto mit aktivierter 2FA durchläuft bei der OXAPI-Anmeldung den Challenge-/OTP-Ablauf wie ein Kundenkonto. Die unter Zwei-Faktor-Authentifizierung genannte Ausnahme „Admin-Backend“ betrifft ausschließlich die klassische Shop-Administration (/admin), nicht die OXAPI.

Hintergrund

Für ein Konto mit aktivierter 2FA liefert die Standard-Anmeldung der OXAPI (token- bzw. login-Abfrage aus graphql-base) noch kein vollwertiges Zugriffstoken, sondern zunächst ein Challenge-Token. Dieses Token weist den laufenden 2FA-Vorgang aus (Claims mfa_pending und mfa_exp) und wird nicht mit einem Refresh-Token ausgegeben. Erst nach erfolgreicher Eingabe des per E-Mail versendeten Einmal-Codes (OTP) tauscht der Client das Challenge-Token gegen ein reguläres Zugriffstoken.

Ohne aktivierte 2FA verhält sich die Anmeldung unverändert und liefert direkt ein reguläres Zugriffstoken.

Ablauf der Anmeldung

Vorgehen

Anmelden. Der Client ruft die Standard-Anmeldung (token/login) mit Benutzername und Passwort auf. Bei einem Konto mit aktivierter 2FA versendet der Shop einen 6-stelligen Code an die hinterlegte E-Mail-Adresse und liefert ein Challenge-Token zurück.
Challenge-Token verwenden. Der Client sendet das Challenge-Token als Authorization: Bearer <token> bei allen folgenden 2FA-Aufrufen.
Code prüfen. Der Client übergibt den eingegebenen Code an verifyTwoFactorToken oder verifyTwoFactorLogin und erhält bei Erfolg ein reguläres Zugriffstoken. Das Challenge-Token wird dabei verbraucht und kann nicht erneut verwendet werden.
Optional: Code erneut senden. Ist der Code nicht angekommen, fordert der Client mit resendTwoFactorOtp einen neuen Code an.

Mutations

verifyTwoFactorToken

Prüft den Code gegen den laufenden 2FA-Vorgang und liefert bei Erfolg ein reguläres Zugriffstoken (ohne Refresh-Token) zurück. Erfordert das Challenge-Token als Bearer-Token.

mutation {
  verifyTwoFactorToken(otp: "123456")
}

verifyTwoFactorLogin

Wie verifyTwoFactorToken, liefert aber zusätzlich ein Refresh-Token — also das gleiche Ergebnis wie eine reguläre Anmeldung. Erfordert das Challenge-Token als Bearer-Token.

mutation {
  verifyTwoFactorLogin(otp: "123456") {
    accessToken
    refreshToken
  }
}

resendTwoFactorOtp

Versendet einen neuen Einmal-Code für den laufenden Vorgang. Erfordert das Challenge-Token als Bearer-Token. Die Wartezeit zwischen zwei Versendungen (60 Sekunden) gilt auch hier; wird sie unterschritten, antwortet die Mutation mit einem Fehler.

mutation {
  resendTwoFactorOtp
}

setTwoFactorAuth

Schaltet die 2FA-Einstellung des angemeldeten Kunden ein oder aus. Diese Mutation erfordert ein reguläres Zugriffstoken (nicht das Challenge-Token) und wirkt immer auf das eigene Konto des angemeldeten Benutzers. Der Rückgabewert ist der tatsächlich gespeicherte Zustand.

mutation {
  setTwoFactorAuth(enabled: true)
}

Gültigkeitsdauer des Challenge-Tokens

Das Challenge-Token ist so lange gültig wie der kleinere der beiden Werte „Gültigkeit des API-Challenge“ und „Gültigkeit des OTP-Codes“. Dadurch kann ein Code nie gegen ein bereits abgelaufenes Challenge-Token eingelöst werden. Beide Werte werden in den Moduleinstellungen gepflegt.

Note

Ein über resendTwoFactorOtp neu versendeter Code verlängert die Gültigkeit des Challenge-Tokens nicht. Ein spät angeforderter Code kann daher ablaufen, bevor er eingelöst werden kann — in diesem Fall muss die Anmeldung neu gestartet werden.

Fehlerverhalten

Situation	Meldung
Falscher oder abgelaufener Code	`Invalid or expired two-factor code`
Code-Versand zu früh erneut angefordert (Wartezeit)	`Please wait before requesting a new two-factor code`
Kein gültiges Challenge-Token (fehlt, abgelaufen oder kein 2FA-Vorgang)	`Not a two-factor challenge token` / `Two-factor challenge has expired`

Voraussetzungen

graphql-base ist installiert und aktiviert. Ohne graphql-base stehen die tokenausgebenden 2FA-Mutations nicht zur Verfügung.