Wie richte ich die Zwei-Faktor-Authentifizierung (2FA) ein?

Ab Tarif Basic

Kurzantwort

Öffne dein Profil, gehe zum Abschnitt „Zwei-Faktor-Authentifizierung” und klicke auf „Gerät hinzufügen”. Vergib einen Gerätenamen, scanne den QR-Code mit deiner Authenticator-App (oder tippe den Schlüssel manuell ein) und bestätige mit dem 6-stelligen Code. Ab dann verlangt jede Anmeldung diesen Code. Du kannst mehrere Geräte hinterlegen. Das ist als Backup dringend empfohlen.

Voraussetzungen

Benötigte Rolle Angemeldeter Benutzer

Jeder richtet 2FA für sich selbst ein. Du brauchst eine Authenticator-App (z. B. Google Authenticator, Microsoft Authenticator, Aegis, 1Password). Verlangt deine Organisation 2FA, wirst du direkt nach der Anmeldung zur Einrichtung geführt.

Anleitung

GUI (Weboberfläche)

1. Profil öffnen. Klicke oben rechts auf dein Benutzermenü und wähle „Profil”. Scrolle zum Abschnitt „Zwei-Faktor-Authentifizierung” und klicke auf „Gerät hinzufügen”.

   Screenshot ausstehend erste-schritte-2fa-01 Profilabschnitt 'Zwei-Faktor-Authentifizierung' mit der Schaltfläche 'Gerät hinzufügen' und der Geräteliste

   Der 2FA-Abschnitt im Profil mit der Schaltfläche 'Gerät hinzufügen'.

2. Gerät benennen. Gib einen Gerätenamen ein (z. B. „iPhone” oder „Authenticator”) und klicke auf „Weiter”. Der Name hilft dir, mehrere Geräte auseinanderzuhalten.

   Screenshot ausstehend erste-schritte-2fa-02 Dialog 'Gerät hinzufügen', Schritt 1: Eingabefeld für den Gerätenamen mit Schaltfläche 'Weiter'

   Schritt 1: dem neuen Gerät einen Namen geben.

3. QR-Code scannen. Scanne den angezeigten QR-Code mit deiner Authenticator-App. Kannst du nicht scannen, tippe den unter „Schlüssel (manuell)” angezeigten Code in die App ein.

   Screenshot ausstehend erste-schritte-2fa-03 Dialog 'Gerät hinzufügen', Schritt 2: QR-Code mit dem manuell eintippbaren Schlüssel darunter und einem Feld für den 6-stelligen Code

   Schritt 2: QR-Code scannen oder den Schlüssel manuell eintippen.

4. Code bestätigen. Gib den aktuellen 6-stelligen Code aus der App ein und klicke auf „Bestätigen”. Das Gerät erscheint nun in der Liste als „Aktiv”. Ab jetzt ist 2FA für dein Konto eingeschaltet.

   Screenshot ausstehend erste-schritte-2fa-04 2FA-Geräteliste mit einem bestätigten Gerät und der Statusmarkierung 'Aktiv'

   Nach der Bestätigung ist das Gerät aktiv. 2FA ist eingeschaltet.

Mehrere Geräte (empfohlen): Wiederhole die Schritte, um ein zweites Gerät (z. B. Tablet) als Backup zu hinterlegen. Beim Login gilt jeder Code aus einem deiner bestätigten Geräte.

Gerät entfernen: Über das Papierkorb-Symbol neben dem Gerät und eine Rückfrage. Entfernst du das letzte bestätigte Gerät, wird 2FA automatisch deaktiviert.

Wiederherstellung / Aussperrung: Es gibt keine Backup-Codes. Hast du kein Gerät mehr, kann ein Administrator deine 2FA in der Benutzerverwaltung zurücksetzen (alle Geräte entfernen). Genau deshalb solltest du mindestens ein zweites Gerät hinterlegen.

API (curl)

Die Einrichtung läuft über drei Aufrufe: Gerät anlegen, mit Code bestätigen und bei Bedarf wieder entfernen. Die Endpunkte gelten für dein eigenes Konto (angemeldete Session oder persönlicher API-Token).

Bestehende Geräte auflisten

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/auth/totp/devices

Neues Gerät anlegen (liefert Secret + QR-Code)

curl -X POST https://demo.notory.io/api/v1/auth/totp/devices \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "iPhone" }'

Die Antwort enthält das Secret einmalig sowie eine otpauth://-URI und den QR-Code als Base64-PNG:

Antwort (201 Created, gekürzt)

{
  "device_id": "9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33",
  "name": "iPhone",
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/max.mustermann@example.com%20(iPhone)?secret=JBSWY3DPEHPK3PXP&issuer=Notory",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA…"
}

Bestätige das Gerät mit einem aktuellen Code aus der App:

Gerät bestätigen

curl -X POST https://demo.notory.io/api/v1/auth/totp/devices/9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33/verify \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Antwort (200 OK)

{ "message": "Device confirmed; two-factor authentication is active" }

Ein Gerät entfernst du per DELETE (Antwort 204 No Content):

Gerät entfernen

curl -X DELETE https://demo.notory.io/api/v1/auth/totp/devices/9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33 \
  -H "Authorization: Bearer inv_dein_token"

Mögliche Fehler: 400 (ungültiger Code beim Bestätigen), 404 (Gerät nicht gefunden), 401 (nicht angemeldet / Token ungültig).

Was passiert dabei?

• Mehrere Geräte (Multi-Device): Du kannst beliebig viele benannte Geräte anlegen. Jedes hat ein eigenes Secret und muss einzeln per Code bestätigt werden. Beim Login wird der Code gegen jedes bestätigte Gerät geprüft. Ein passender Code aus einem beliebigen Gerät genügt.
• Aktivierung: 2FA schaltet sich ein, sobald das erste Gerät bestätigt ist (totp_enabled).
• Automatische Deaktivierung: Entfernst du das letzte bestätigte Gerät, wird 2FA automatisch abgeschaltet.
• Erzwungene 2FA: Verlangt deine Instanz oder dein Mandant 2FA, blockiert Notory nach dem Login alle Funktionen, bis du ein Gerät bestätigt hast (Einrichtungsbildschirm).
• Keine Backup-Codes: Es gibt kein Wiederherstellungscode-System. Bei Verlust aller Geräte setzt ein Administrator deine 2FA zurück (Endpunkt users/{id}/totp).
• Secret nur einmal: Das Secret wird ausschließlich beim Anlegen zurückgegeben und nie erneut über die API ausgegeben.
• Audit-Log: Die Bestätigung eines Geräts wird protokolliert; pro Gerät wird last_used_at bei jeder erfolgreichen Verwendung aktualisiert.

Verwandte Themen

• Anmelden: 2FA-Abfrage beim Login
• Profil verwalten
• Benutzer & Rollen: Administrator setzt 2FA zurück
• SSO / OIDC: Alternative zur passwortbasierten Anmeldung