Tokens und JWKS: Didit-Authentifizierungs-JWTs prüfen

• https://<name>.auth.didit.me für eine Live-Anwendung,
• https://<name>.sandbox.auth.didit.me für eine Sandbox-Anwendung,
• oder Ihre eigene benutzerdefinierte Domain, sobald sie aktiv ist.

​

Discovery und Schlüssel

• Response-Type code und Response-Mode query.
• Grant-Types authorization_code und refresh_token.
• Ausschließlich die PKCE-Methode S256. Es handelt sich um öffentliche Clients: Es gibt kein Client-Secret, und client_id ist Ihre Anwendungs-ID.
• Signaturalgorithmus ES256 (P-256-Schlüssel).
• Scopes openid, email, phone, profile und offline_access.

​

Caching und Rotation

• Jeder Schlüssel hat eine kid; neue Schlüssel-IDs beginnen mit k_. Jedes Token nennt seinen Schlüssel im kid-Header.
• Schlüssel rotieren alle 30 Tage. Didit veröffentlicht den nächsten Schlüssel einen Tag, bevor er mit dem Signieren beginnt, und hält den vorherigen Schlüssel einen Tag lang veröffentlicht, nachdem er nicht mehr signiert. Ein 5 Minuten lang gecachtes JWKS ermöglicht daher auch während einer Rotation weiterhin eine erfolgreiche Verifizierung.
• Cachen Sie Schlüssel nach kid. Nennt ein Token eine kid, die Sie nicht haben, laden Sie das JWKS erneut, höchstens einmal pro Minute, und weisen Sie das Token zurück, wenn der Schlüssel weiterhin fehlt.
• Wenn Didit einen kompromittierten Schlüssel widerruft, entfernt es den Schlüssel sofort aus dem JWKS, und GET /session/ weist jedes Token zurück, das mit diesem Schlüssel signiert wurde. Ein Ersatzschlüssel beginnt sofort mit dem Signieren, ohne die eintägige Vorabveröffentlichung. Ein bis zu 5 Minuten früher gecachtes JWKS akzeptiert den widerrufenen Schlüssel noch und kennt den Ersatzschlüssel noch nicht. Neue Tokens können deshalb bei der Offline-Verifizierung fehlschlagen, bis der Cache aktualisiert wird.

​

Anmeldung starten

{issuer}/sign-in?redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256

​

Code einlösen

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "CODE_FROM_CALLBACK",
    "code_verifier": "YOUR_PKCE_VERIFIER",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "refresh_token": "N4yZTl6y24YKYq77X_SO...",
  "token_type": "Bearer",
  "expires_in": 299,
  "session_id": "c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1"
}

​

Access-Token-Claims

​

Token auf Ihrem Server prüfen

1. alg ist ES256 und typ ist at+jwt. Lehnen Sie jeden anderen Algorithmus ab, auch none.
2. Der kid-Wert ist im JWKS Ihrer Anwendung enthalten, und die Signatur wird verifiziert.
3. iss entspricht Ihrem konfigurierten Aussteller, und aud entspricht Ihrer Anwendungs-ID.
4. exp und iat sind gültig, mit einer Uhrzeitabweichung von bis zu 60 Sekunden, und sub, sid und jti sind vorhanden.
5. act ist null. Das Access-Token eines KI-Agenten wird mit demselben Schlüssel signiert und trägt denselben typ, iss und aud; nur act unterscheidet es. Lehnen Sie es ab, sofern der Endpoint keine Agenten akzeptiert. Ist das der Fall, erlauben Sie nur, was act.scopes gewährt. GET /session/ lehnt das Token eines Agenten immer ab.

// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.DIDIT_AUTH_ISSUER; // https://<name>.auth.didit.me
const AUDIENCE = process.env.DIDIT_APPLICATION_ID;
// Cache keys for 5 minutes; refetch an unknown kid at most once a minute.
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`), {
  cacheMaxAge: 5 * 60 * 1000,
  cooldownDuration: 60 * 1000,
});

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["ES256"],
    typ: "at+jwt",
    clockTolerance: 60,
    maxTokenAge: "5m", // also rejects an iat in the future
    requiredClaims: ["sub", "sid", "jti", "exp", "iat"],
  });
  if (payload.act !== null) throw new Error("agent tokens are not accepted");
  return payload; // payload.vendor_data is the person across Didit products
}

# pip install "pyjwt[crypto]"
import os
import threading
import time

import jwt

ISSUER = os.environ["DIDIT_AUTH_ISSUER"]  # https://<name>.auth.didit.me
AUDIENCE = os.environ["DIDIT_APPLICATION_ID"]
jwks = jwt.PyJWKClient(f"{ISSUER}/.well-known/jwks.json", lifespan=300)
refresh_lock = threading.Lock()
last_refresh = 0.0


def signing_key(kid: str | None) -> jwt.PyJWK:
    # PyJWKClient refetches for every unknown kid: limit it to once a minute.
    global last_refresh
    keys = {key.key_id: key for key in jwks.get_signing_keys()}
    if kid not in keys:
        with refresh_lock:
            if time.monotonic() - last_refresh >= 60:
                last_refresh = time.monotonic()
                fresh = jwks.get_signing_keys(refresh=True)
                keys = {key.key_id: key for key in fresh}
    if kid not in keys:
        raise jwt.InvalidTokenError("unknown signing key")
    return keys[kid]


def verify_access_token(token: str) -> dict:
    header = jwt.get_unverified_header(token)
    if header.get("typ") != "at+jwt":
        raise jwt.InvalidTokenError("not an access token")
    claims = jwt.decode(
        token,
        signing_key(header.get("kid")).key,
        algorithms=["ES256"],
        audience=AUDIENCE,
        issuer=ISSUER,
        leeway=60,
        options={"require": ["iss", "aud", "sub", "sid", "jti", "exp", "iat"]},
    )
    if "act" not in claims or claims["act"] is not None:
        raise jwt.InvalidTokenError("agent tokens are not accepted")
    return claims

​

Sitzung prüfen

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/session/" \
  -H "Authorization: Bearer $DIDIT_ACCESS_TOKEN"

​

Refresh-Tokens

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{"grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN"}'

• Das Refresh-Token ist eine zufällige Zeichenfolge, die bis zum Ende der Sitzung gültig ist.
• Eine Wiederverwendung beendet die Sitzung. Wenn ein bereits verwendetes Refresh-Token erneut eingeht, wertet Didit das als Hinweis auf Diebstahl: Es widerruft die Sitzung und liefert 400 {"error": "invalid_grant"}. Auch die Tokens der Sitzung funktionieren nicht mehr, einschließlich derer aus dem früheren Refresh: Deren Refresh-Token schlägt fehl, und deren Access-Token schlägt sofort bei GET /session/ fehl. Offline lässt es sich noch bis zu seinem Ablauf verifizieren, also innerhalb von 5 Minuten.
• Führen Sie für eine Sitzung jeweils nur einen Refresh aus, über Tabs, Geräte und Serverinstanzen hinweg, und ersetzen Sie alle drei Tokens gemeinsam.
• Schlägt ein Refresh mit 400 fehl oder bleibt eine Antwort aus, starten Sie die Anmeldung neu. Versuchen Sie es nicht blind erneut: Ein Wiederholungsversuch nach einem erfolgreichen Refresh ist eine Wiederverwendung.
• Ein 503 {"error": "temporarily_unavailable"} bedeutet, dass der Refresh nicht stattgefunden hat und Ihr Refresh-Token weiterhin funktioniert. Versuchen Sie es mit Backoff erneut.
• Didit antwortet mit 429, bevor der Refresh ausgeführt wird. Wiederholen Sie ihn daher nach Retry-After. Der Token-Endpoint erlaubt 30 Anfragen pro Minute und 300 pro Stunde und IP-Adresse. Zusätzlich teilen sich alle POST- und DELETE-Anfragen Ihrer Anwendung Bot-Schutz-Kontingente: 60 Anfragen pro Minute und IP-Adresse über diese Endpoints hinweg und 30 pro Minute und Gerät. Für die gesamte Anwendung gibt es für Refreshes ein Kontingent von 6.000 pro Minute, und jedes andere POST und DELETE (einschließlich Browser und Anmeldeschritte) ein Kontingent von 3.000 pro Minute. So verbrauchen Refreshes nie Ihr Kontingent für Anmeldungen.
• Bei 5-Minuten-Access-Tokens decken 300 Refreshes pro Stunde etwa 25 Personen ab, die aktiv bleiben. Wenn Ihr Server für viele Personen von einer Adresse aus refresht, refreshen Sie nur, wenn eine Anfrage ein neues Token benötigt, und führen Sie Refreshes möglichst im Browser oder in der App durch.

​

Abmelden

• sie session_lifetime (Standard 30 Tage) oder idle_timeout (Standard 1 Tag) überschreitet,
• sich die Person erneut anmeldet, während die Option für mehrere Sitzungen deaktiviert ist,
• die Person ihr Passwort zurücksetzt, während revoke_on_password_change aktiviert ist,
• Ihr Team die Sitzung in der Konsole widerruft oder die Person dort sperrt,
• ein bereits verwendetes Refresh-Token erneut gesendet wird.

​

Lebensdauer

​

Zugangsdaten je nach Zweck speichern

• Bewahren Sie Verifizierungs-API-Schlüssel und Console-Tokens auf Ihrem Server auf.
• Bewahren Sie Access-Tokens für den Browser nach Möglichkeit im Arbeitsspeicher auf. Bei serverseitig gerenderten Anwendungen verwenden Sie sichere Cookies mit HttpOnly-Flag und schützen Anfragen mit Cookie-Authentifizierung vor CSRF.
• Speichern Sie Refresh-Tokens für mobile Apps in einem plattformgeschützten Speicher. Löschen Sie den lokalen Zustand nach der Abmeldung.
• Setzen Sie Tokens niemals in URLs oder Logs.