> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifizierung Integrationsleitfaden: Architektur und Go-Live

> So fügt sich eine produktive Didit-Authentifizierung zusammen: Oberflächen, Token-Speicherung, Backend-Prüfung, Sitzungen, Apps und Go-Live.

Dieser Leitfaden erklärt, wie eine Produktionsintegration von Didit Authentication aufgebaut ist, von der ersten Weiterleitung bis zur Go-Live-Checkliste.
Wenn Sie eine Person noch nicht angemeldet haben, beginnen Sie mit dem [Schnellstart](https://docs.didit.me/de/authentication/quickstart.md). Den Code für jedes SDK finden Sie in den Plattform-Schnellstarts.

## Architektur

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

An dem Ablauf sind vier Komponenten beteiligt:

| Komponente | Zuständigkeit |
| - | - |
| Ihre App | Startet die Anmeldung, verwahrt den PKCE-Verifier und `state`, speichert die Tokens und sendet das Zugriffstoken an Ihr Backend. Die SDKs übernehmen all das. |
| Ihre Anmeldedomain | `https://<slug>.auth.didit.me` (oder Ihre [eigene Domain](https://docs.didit.me/de/authentication/branding-and-custom-domain.md#benutzerdefinierte-domain)): die gehosteten Seiten, der Token-Endpoint, die Sitzung, der Discovery-Mechanismus und die Signaturschlüssel. |
| Ihr Backend | Prüft das Zugriffstoken bei jeder geschützten Anfrage, kontrolliert die Sitzung vor sensiblen Aktionen und entscheidet, was die Person tun darf. |
| Didit-Konsole und Webhooks | Konfiguration, die Personen und ihre Sitzungen, Anmeldeereignisse sowie die `auth.*`-Webhooks, die Ihr Server abonniert. |

In Ihrer App darf nie ein Didit-API-Schlüssel oder ein Geheimnis liegen: Der öffentliche Schlüssel ist öffentlich, und der Code-Austausch ist durch PKCE statt durch ein Client-Secret geschützt.

## Gehostete Seiten oder eigene Bildschirme

Legen Sie fest, wo Personen ihre E-Mail-Adresse, ihr Passwort oder ihren Code eingeben.
Die Einstellung ist `sign_in_ui` (standardmäßig `hosted`, alternativ `own`), und Sie können sie später ändern.

| | Gehostete Seiten (empfohlen) | Eigene Bildschirme |
| - | - | - |
| Was Sie entwickeln | Eine Anmeldeschaltfläche und eine Callback-Seite. | Jeden Bildschirm und jeden Zwischenschritt. |
| Methoden | Alle, einschließlich Magic Links, Unternehmens-SSO und Passkeys. | Passwort, E-Mail-Code, Telefoncode, MFA und Schutzprüfungen über die Headless-Methoden der SDKs. Magic Links funktionieren nur auf den gehosteten Seiten. |
| Nächste Schritte | Wird für Sie übernommen: MFA, MFA-Registrierung, Schutzprüfungen und Verifizierung bei der Registrierung. | Ihre Bildschirme behandeln `mfa_required`, `mfa_enrollment_required`, `protection_required` und `verification_required`. Siehe [Anmeldemethoden](https://docs.didit.me/de/authentication/sign-in-methods.md). |
| Branding | Ihr Logo, Ihre Farben und Texte aus [Branding](https://docs.didit.me/de/authentication/branding-and-custom-domain.md). | Vollständig frei gestaltbar. |
| Einrichtung | Redirect-URLs. | Redirect-URLs sowie Ihr Web-Origin unter **Allowed origins**. |

Passkeys gehören zum Anmelde-Origin Ihrer Anwendung.
Die Passkey-Methoden der SDKs funktionieren nur auf Seiten, die von diesem Origin ausgeliefert werden. Auf Ihren eigenen Bildschirmen auf einer anderen Domain verweisen Sie Personen für Passkeys daher auf die gehostete Seite.

## Wählen Sie Ihr SDK

| Ihre App | Paket | Speicherort der Tokens |
| - | - | - |
| Single-Page-Webanwendung | [`@didit-protocol/auth`](https://docs.didit.me/de/authentication/quickstarts/javascript) oder [`@didit-protocol/auth-react`](https://docs.didit.me/de/authentication/quickstarts/react) | Web Storage oder Arbeitsspeicher im Browser. Halten Sie eine strikte Content Security Policy ein. |
| Serverseitig gerenderte Webanwendung | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/de/authentication/quickstarts/nextjs) | HttpOnly-Cookies, die von Ihrem Server gesetzt werden. Die Seite sieht die Tokens nie. |
| iOS | [`DiditAuth`](https://docs.didit.me/de/authentication/quickstarts/ios) | Der Schlüsselbund. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/de/authentication/quickstarts/android) | Speicher, der durch den Android Keystore geschützt ist. |
| React Native oder Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/de/authentication/quickstarts/react-native) oder [`didit_auth`](https://docs.didit.me/de/authentication/quickstarts/flutter) | Der geschützte Speicher der Plattform, über die nativen Module. |
| Beliebiges Backend | [Server-SDKs](https://docs.didit.me/de/integration/server-sdks/overview.md), `verifyToken` aus `@didit-protocol/auth/server` oder eine beliebige JWT-Bibliothek | Nichts zu speichern: Es verifiziert das empfangene Token. |

Ohne SDK implementieren Sie den Authorization-Code-Flow mit PKCE selbst: Die [JavaScript-Schnellstartanleitung](https://docs.didit.me/de/authentication/quickstarts/javascript.md#ohne-das-sdk) zeigt den gesamten Vertrag.

## Ihr Backend schützen

Die Sitzungsprüfung im Frontend steuert nur, was angezeigt wird.
Ihr Backend trifft jede Entscheidung auf Basis eines verifizierten Tokens.

1. **Prüfen Sie das Zugriffstoken bei jeder Anfrage.** Prüfen Sie die ES256-Signatur anhand des JWKS Ihres Ausstellers, anschließend `iss`, `aud`, `exp` und `typ: at+jwt`. Lehnen Sie ein Token ab, dessen `act` nicht `null` ist, es sei denn, die Route akzeptiert [KI-Agenten](https://docs.didit.me/de/authentication/agent-access.md). Siehe [Token auf Ihrem Server prüfen](https://docs.didit.me/de/authentication/tokens-and-jwks.md#token-auf-ihrem-server-prüfen).
2. **Prüfen Sie die aktive Sitzung vor einer sensiblen Aktion.** Ein Zugriffstoken bleibt bis zu seinem Ablauf gültig, also höchstens 5 Minuten. `GET /session/` schlägt sofort fehl, wenn die Sitzung widerrufen wurde, inaktiv geworden oder abgelaufen ist, wenn die Person gesperrt wurde oder wenn die Sitzung Ihre MFA-Richtlinie nicht mehr erfüllt. Siehe [Sitzung prüfen](https://docs.didit.me/de/authentication/tokens-and-jwks.md#sitzung-prüfen).
3. **Fordern Sie einen Step-up an, wenn die Aktion riskant ist.** Fragen Sie vor einer Auszahlung, einem neuen Bankkonto oder einer Änderung der E-Mail-Adresse oder Telefonnummer bei Didit an, ob sich die Person erneut verifizieren muss. Handeln Sie nur auf Basis eines `approved`-Step-ups, den Ihr Backend selbst gelesen hat. Siehe [Step-up vor sensiblen Aktionen](https://docs.didit.me/de/authentication/verified-identity.md#step-up-vor-sensiblen-aktionen).
4. **Übernehmen Sie `vendor_data` aus dem verifizierten Token,** niemals aus einem Feld, das der Browser gesendet hat, und verwenden Sie es für die Verifizierungen und Transaktionen der Person.

## Sitzungen

| Ereignis | Was passiert |
| - | - |
| Anmeldung | Eine Sitzung beginnt. Ihre Dauer entspricht `session_lifetime` (standardmäßig 30 Tage). Sie endet früher, wenn nach `idle_timeout` keine Aktivität mehr erfolgt (standardmäßig 1 Tag). |
| Alle paar Minuten | Das SDK erneuert das Access-Token, das höchstens 5 Minuten gültig ist. Das Refresh-Token wechselt bei jeder Erneuerung: Jedes Refresh-Token funktioniert nur einmal. |
| Ein bereits verwendetes Refresh-Token wird erneut gesendet | Didit wertet das als Diebstahl und beendet die Sitzung. Führen Sie pro Sitzung jeweils nur einen Refresh aus. |
| Anmeldung auf einem anderen Gerät | Mit `multiple_sessions: false` enden die übrigen Sitzungen der Person. |
| Passwort zurücksetzen | Alle Sitzungen enden, wenn `revoke_on_password_change` aktiviert ist (Standardeinstellung). |
| Abmeldung | `DELETE /session/` beendet die Sitzung, und Ihre App leitet die Person an Ihre `post_logout_redirect_uri` weiter. |
| Ihr Team greift ein | Die Konsole kann eine einzelne Sitzung widerrufen, eine Person überall abmelden oder sie sperren. Siehe den [Konsolen-Leitfaden](https://docs.didit.me/de/authentication/console.md#anmeldungen-und-sitzungen). |

Die Laufzeiten ändern Sie unter **Authentication > Security and sessions** oder per API in den [Anwendungseinstellungen](https://docs.didit.me/de/authentication/overview.md#anwendungseinstellungen).

![Die Ansicht Active sessions in der Didit Business Console mit angemeldeten Sitzungen, jeweils mit Gerät, Standort, Beginn, letzter Aktivität, Ende und einer Revoke-Schaltfläche](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, mit Revoke bei jeder Sitzung.

## Native Apps

Didit leitet Benutzer nur über eine HTTPS-Weiterleitung in eine native App zurück und akzeptiert keine benutzerdefinierten URL-Schemata.

* **iOS:** Machen Sie die Weiterleitung zu einer zugehörigen Domain, mit `webcredentials` in Ihrer `apple-app-site-association`.
* **Android:** Machen Sie die Weiterleitung zu einem App Link, mit Ihrer `assetlinks.json`.
* Registrieren Sie jede Weiterleitungs-URL unter **Authentication > Security and sessions**, wie eine Web-Callback-URL.

Für Passkeys in Ihrer App registrieren Sie die Apps, die die Passkeys Ihrer Anwendung gemeinsam nutzen, mit `PUT native-apps/` über die [Authentication-Management-API](https://docs.didit.me/de/authentication/set-up-by-api.md).
Didit nimmt diese dann in die `apple-app-site-association` und die `assetlinks.json` auf, die auf Ihrem Anmelde-Origin ausgeliefert werden.
`MANAGEMENT_BASE` ist die Adresse der Management-API Ihrer Anwendung, und ein API-Schlüssel mit dem Bereich `authentication` und **write** kann den Aufruf ausführen.
Der Aufruf ersetzt beide Listen. Senden Sie daher beide mit:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Feld | Regel |
| - | - |
| `ios_app_ids` | Bis zu 10 Einträge aus Ihrer Team-ID und Ihrem Bundle-Identifier, zum Beispiel `ABCDE12345.com.example.app`. |
| `android_apps` | Bis zu 10 Apps, jeweils mit ihrem `package_name` und 1 bis 5 SHA-256-Fingerabdrücken des Signaturzertifikats. |

Die Schnellstartanleitungen für [iOS](https://docs.didit.me/de/authentication/quickstarts/ios.md) und [Android](https://docs.didit.me/de/authentication/quickstarts/android.md) zeigen die App-Seite.

## Identitätsverifizierung und Transaktionsüberwachung verbinden

Jede Person hat genau einen `vendor_data`-Wert, der in ihren Tokens und ihrer Sitzung enthalten ist.
Verwenden Sie ihn als `vendor_data`, wenn Sie [eine Verifizierungssitzung erstellen](https://docs.didit.me/de/sessions-api/create-session.md) oder [eine Transaktion übermitteln](https://docs.didit.me/de/transaction-monitoring/transactions.md). Die Konsole zeigt dann Anmeldungen, Verifizierungen und Transaktionen derselben Person an.

* Um Personen bei der Registrierung oder erneut vor einer Auszahlung zu verifizieren, ohne einen Verifizierungsablauf aufzubauen, nutzen Sie die [verifizierte Identität](https://docs.didit.me/de/authentication/verified-identity.md).
* Anmeldeereignisse gelangen automatisch zu den [Ereignisregeln](https://docs.didit.me/de/transaction-monitoring/event-rules.md) und in die Betrugsansichten. Senden Sie für dieselben Anmeldungen keine eigenen `auth.login`-Ereignisse.
* Eine erfolgreiche Anmeldung genehmigt niemals eine Verifizierung oder eine Transaktion. Behandeln Sie die Entscheidung jedes Produkts separat.

Siehe [dieselbe Person über alle Produkte hinweg beibehalten](https://docs.didit.me/de/authentication/overview.md#dieselbe-person-über-alle-produkte-hinweg-zuordnen).

## Sign-in-Ereignisse empfangen

Abonnieren Sie ein [Webhook-Ziel](https://docs.didit.me/de/integration/webhooks.md) für die `auth.*`-Typen, die Sie benötigen, zum Beispiel `auth.new_device` oder `auth.account_locked`.
Dedupizieren Sie anhand von `auth_event.event_id` und prüfen Sie die Signatur wie bei jedem Didit-Webhook.
Alle Typen und ihre Payloads finden Sie unter [Ereignisse und Webhooks](https://docs.didit.me/de/authentication/events-and-webhooks.md).

## Bestehende Benutzer migrieren

Wenn Ihre Benutzer bereits Konten bei einer anderen Identitätsplattform oder in Ihrer eigenen Datenbank haben, [importieren Sie sie](https://docs.didit.me/de/authentication/migration.md), bevor Sie die Anmeldung umstellen.
Importieren Sie die Passwort-Hashes, sofern die Quelle sie bereitstellt, behalten Sie die Social-Login-Verknüpfungen bei und speichern Sie Ihre eigenen Benutzer-IDs als `external_id`, die dann als `vendor_data` hinterlegt werden.
Für Ihre Benutzer ändert sich nichts, bis Sie Ihre App auf Didit umstellen.

## Checkliste für den Go-live

1. Die Authentifizierung ist für Ihre Live-Anwendung auf der Seite **Products** aktiviert.
2. Ihre produktiven Redirect-URLs mit `https://` und erlaubte Ursprünge sind in der Live-Anwendung registriert. Eine Live-Anwendung akzeptiert keine `http://`-Adressen.
3. Jede Social-Login-Methode verwendet Client-ID und Secret Ihrer eigenen App. Die Testzugangsdaten von Didit funktionieren nur in der Sandbox.
4. Ihre Produktionskonfiguration enthält den Live-Publishable-Key (`pk_live_`) und Ihren Live-Issuer.
5. Ihre MFA-Richtlinie, Sitzungsdauer, Inaktivitäts-Timeout, Passwortlänge und Registrierungsrichtlinie entsprechen Ihren Vorgaben. Siehe [Anwendungseinstellungen](https://docs.didit.me/de/authentication/overview.md#anwendungseinstellungen).
6. [Bot-Schutz](https://docs.didit.me/de/authentication/bot-protection.md) ist aktiviert, einschließlich der Prüfung auf kompromittierte Passwörter.
7. Ihr Backend verifiziert jedes Access-Token und ruft `GET /session/` vor sensiblen Aktionen auf.
8. Ihr Branding, Ihre Seitentexte sowie Links zu Nutzungsbedingungen und Datenschutzbestimmungen sind festgelegt. Wenn Sie eine [benutzerdefinierte Domain](https://docs.didit.me/de/authentication/branding-and-custom-domain.md#benutzerdefinierte-domain) planen, aktivieren Sie diese, bevor Nutzer Passkeys hinzufügen.
9. Ihr Webhook-Ziel hat die `auth.*`-Typen abonniert, die Sie verarbeiten.
10. Sie haben Registrierung, Anmeldung zurückkehrender Nutzer, Abbruch, Passwort vergessen, MFA, Ablauf der Sitzung, Abmeldung und eine widerrufene Sitzung auf der Live-Anwendung getestet.

## Fehlerbehebung

| Symptom | Ursache und Lösung |
| - | - |
| Jede Runtime-Route antwortet mit `404` | Die Authentifizierung ist für die Anwendung deaktiviert, oder die Adresse mischt eine Sandbox- und eine Live-Origin. Aktivieren Sie sie auf der Seite **Products**, und verwenden Sie die Origin, die Ihr Publishable Key angibt. |
| Die Anmeldeseite antwortet mit `400` und fordert Sie auf, eine Adresse zu registrieren, oder `POST /authorize/` antwortet mit `invalid_redirect_uri` | Der `redirect_uri` ist nicht exakt registriert: Schema, Host, Port, Pfad und Query müssen Zeichen für Zeichen übereinstimmen. Siehe [Weiterleitungs-URLs](https://docs.didit.me/de/authentication/overview.md#weiterleitungs-urls). |
| Ein Browseraufruf an Ihre Anmelde-Origin antwortet mit `403` und `origin_not_allowed` | Ihre Web-Origin ist nicht unter **Allowed origins** eingetragen. Fügen Sie sie ohne Pfad und ohne abschließenden Schrägstrich hinzu. |
| `POST /token/` antwortet mit `invalid_grant` | Der Code wurde bereits verwendet, ist älter als 60 Sekunden oder wurde mit einem anderen PKCE-Verifier oder `redirect_uri` gesendet. Bei einem Refresh wurde das Refresh-Token bereits verwendet, wodurch die Sitzung endet. Starten Sie die Anmeldung erneut. |
| Eine Passwortanmeldung antwortet mit `invalid_credentials`, obwohl das Passwort stimmt | Die E-Mail-Adresse ist nicht verifiziert, oder das Konto ist gesperrt oder blockiert. Didit gibt absichtlich dieselbe Antwort. Prüfen Sie die Person unter **Users**. |
| `GET /session/` antwortet mit `401` | Die Sitzung wurde widerrufen, ist inaktiv geworden oder abgelaufen, die Person wurde blockiert, das Token wurde durch ein Refresh ersetzt, oder die Sitzung entspricht nicht mehr Ihrer MFA-Richtlinie. Aktualisieren Sie das Token, oder melden Sie die Person erneut an. |
| Das Hinzufügen eines Passkeys oder Authenticators antwortet mit `403 reauthentication_required` | Dafür ist eine Sitzung erforderlich, die in den letzten 5 Minuten erstellt wurde. Melden Sie die Person zuerst erneut an. |
| Ein Telefoncode antwortet mit `503 delivery_unavailable` | Der Code konnte nicht zugestellt werden. Lassen Sie die Person es erneut versuchen, oder bieten Sie eine andere Methode an. |
| Ein Aufruf antwortet mit `429` | Sie haben ein Rate-Limit erreicht. Wiederholen Sie den Aufruf nach Ablauf der in `Retry-After` angegebenen Zeit. Siehe [Rate-Limits](https://docs.didit.me/de/authentication/bot-protection.md#rate-limits). |
| Ein Setup-Aufruf mit einem API-Schlüssel antwortet mit `409 product_disabled` | Die Authentifizierung ist für die Anwendung deaktiviert. Eine Person aktiviert sie in der Konsole. |
| Ein Aufruf antwortet mit `403 plan_required` | Die Funktion, etwa benutzerdefinierte Rollen oder Links zur SSO-Einrichtung für Unternehmen, erfordert den Tarif Scale oder Enterprise. Sandbox-Anwendungen haben sie in jedem Tarif. |
| Tokens funktionieren nicht mehr, nachdem Sie eine benutzerdefinierte Domain aktiviert haben | Der Issuer und der Publishable Key haben sich geändert. Kopieren Sie den neuen Key in Ihre App, und aktualisieren Sie den Issuer, den Ihr Backend prüft. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.