Authentifizierung

Dieses Dokument beschreibt den derzeit implementierten Ablauf für eine vertrauliche Partneranwendung, die eine Verbindung zu Parkour Design herstellt. Client-Registrierung und Produktionszugriff erfordern eine technische Freigabe und eine Sicherheitsfreigabe.

Aktueller Vertrag: Das Protokoll ist implementiert und wird für abgestimmte Integrationen verwendet. Es handelt sich nicht um einen Autorisierungsdienst zur Selbstbedienung. Parkour Design stellt Client-ID, Client Secret, registrierte Redirect URIs und zulässige Scopes über einen sicheren Kanal bereit.

Umgebungen und Discovery

Verwenden Sie OpenID Connect Discovery, anstatt Endpunkt-URLs selbst zusammenzusetzen.

Rufen Sie das Discovery Document beim Start der Anwendung ab, speichern Sie es für einen begrenzten Zeitraum im Cache und aktualisieren Sie es, wenn sich Signaturschlüssel ändern. Der zurückgegebene issuer muss exakt dem konfigurierten Issuer entsprechen.

Das aktuelle Discovery Document veröffentlicht folgende Angaben:

Verwenden Sie client_secret_basic und PKCE S256. Verwenden Sie nicht plain, obwohl der aktuelle Server diese Methode aus Kompatibilitätsgründen ausweist.

Voraussetzungen für die Registrierung

Übermitteln Sie Parkour Design vor der Implementierung folgende Angaben:

• Anwendungsname und technisch verantwortliche Person;
• Test- und Produktions-Redirect-URIs;
• angeforderte Scopes und User Journey;
• Kontakte für die Übermittlung und Rotation von Zugangsdaten;
• Anforderungen für Logout, Aufhebung von Kontoverknüpfungen und Aufbewahrung.

Redirect URIs werden exakt abgeglichen. Schema, Host, Port, Pfad, Groß- und Kleinschreibung sowie ein abschließender Schrägstrich müssen dem registrierten Wert entsprechen. Verwenden Sie einen Callback ohne vorhandenen Query-String oder Fragment.

Der aktuelle Dienst unterstützt vertrauliche Backend-Clients. Reine Browser-Clients und native öffentliche Clients werden nicht unterstützt, da jede Token-Anfrage ein Client Secret erfordert.

Autorisierungsablauf

1. Browsertransaktion erstellen

Generieren und speichern Sie serverseitig:

• einen nur einmal nutzbaren state-Wert mit hoher Entropie;
• eine OIDC-nonce mit hoher Entropie;
• einen PKCE-Verifier und die zugehörige SHA-256-Challenge;
• das vorgesehene Ziel nach der Anmeldung;
• eine kurze Ablaufzeit.

Binden Sie diese Werte an die Browsersitzung des Benutzers. Übertragen Sie weder Client Secret noch Verifier oder Tokens in einer URL.

2. Benutzer weiterleiten

Erstellen Sie die Autorisierungs-URL anhand des authorization_endpoint aus dem Discovery Document:

GET {authorization_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={url_encoded_registered_redirect_uri}
  &scope={url_encoded_approved_scopes}
  &state={state}
  &nonce={nonce}
  &code_challenge={base64url_sha256_verifier}
  &code_challenge_method=S256

Verwenden Sie ausschließlich die bei der Client-Registrierung genehmigten Scopes. openid email profile ist ein Beispiel, wenn alle drei Scopes genehmigt wurden; die Anforderung eines nicht genehmigten Scopes gibt invalid_scope zurück.

Parkour Design authentifiziert den Benutzer und bittet um seine Zustimmung. Eine erfolgreiche Antwort gibt Folgendes zurück:

{redirect_uri}?code={authorization_code}&state={state}

Eine abgelehnte Anfrage gibt Folgendes zurück:

{redirect_uri}?error=access_denied&state={state}

3. Callback validieren

Bevor Sie den Code austauschen:

1. lehnen Sie einen fehlenden oder unerwarteten state ab;
2. lehnen Sie eine abgelaufene oder bereits verwendete Browsertransaktion ab;
3. verbrauchen Sie die Transaktion, damit der Callback nicht erneut ausgeführt werden kann;
4. behandeln Sie einen OAuth-error, ohne einen Token-Austausch zu versuchen.

Autorisierungscodes laufen nach fünf Minuten ab und können nur einmal verwendet werden.

4. Code serverseitig austauschen

Senden Sie eine formularcodierte Anfrage vom Backend des Partners:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

Der redirect_uri muss mit dem in der Autorisierungsanfrage verwendeten Wert identisch sein.

Eine erfolgreiche Antwort hat derzeit folgende Struktur:

{
  "access_token": "<signed JWT>",
  "refresh_token": "<opaque token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "email openid profile",
  "id_token": "<signed JWT>"
}

Token-Antworten verwenden Cache-Control: no-store und Pragma: no-cache. Das id_token wird nur zurückgegeben, wenn openid gewährt wurde.

Identität validieren

Validieren Sie das ID-Token, bevor Sie eine Partnersitzung einrichten:

1. rufen Sie Schlüssel vom jwks_uri aus dem Discovery Document ab;
2. wählen Sie den durch den JWT-kid angegebenen Schlüssel aus;
3. verlangen Sie eine RS256-Signatur;
4. verlangen Sie die exakte Übereinstimmung des Issuers;
5. verlangen Sie die Client-ID als Audience;
6. validieren Sie Ablauf- und Ausstellungszeit mit einer geringen Toleranz für Zeitabweichungen;
7. verlangen Sie die ursprüngliche nonce;
8. verwenden Sie sub als stabilen Benutzeridentifikator von Parkour Design.

Aktuelle Claims des ID-Tokens:

{
  "iss": "https://app.parkour.design",
  "sub": "<opaque Parkour Design user ID>",
  "aud": "<client ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User",
  "token_use": "id_token",
  "iat": 0,
  "exp": 0,
  "nonce": "<authorization nonce>"
}

Verknüpfen Sie Konten nicht allein anhand der E-Mail-Adresse. Speichern Sie iss und sub als externen Identitätsschlüssel. Behandeln Sie E-Mail-Adresse und Name als veränderliche Profilattribute.

UserInfo ist verfügbar, wenn das Zugriffstoken openid enthält:

curl "${USERINFO_ENDPOINT}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

{
  "sub": "<opaque Parkour Design user ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User"
}

Zugriffs- und Refresh-Tokens

Refresh-Tokens rotieren bei jeder erfolgreichen Verwendung:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

Die Antwort enthält ein neues Zugriffstoken und ein Ersatz-Refresh-Token. Sie enthält kein neues ID-Token. Serialisieren Sie Refresh-Vorgänge für jede Benutzer- und Client-Sitzung und ersetzen Sie anschließend das gespeicherte Refresh-Token atomar. Die Wiederverwendung eines alten Tokens gibt invalid_grant zurück.

Parkour Design verbraucht das alte Refresh-Token, bevor dessen Ersatz zurückgegeben wird. Wenn nach einem Timeout oder einer verlorenen Antwort das Ergebnis unbekannt ist, versuchen Sie es nicht unkontrolliert mit dem alten Token erneut. Löschen Sie den lokalen Token-Zustand und starten Sie einen neuen Autorisierungsablauf. Gleichzeitige Refresh-Anfragen für dieselbe Sitzung verursachen dasselbe Wiederherstellungsrisiko.

Die aktuelle Gültigkeitsdauer von Refresh-Tokens ist gleitend: Jede erfolgreiche Rotation startet eine neue Gültigkeitsdauer von 30 Tagen. Parkour Design stellt derzeit keine Endpunkte für Token-Widerruf oder -Introspektion bereit. Beim Trennen der Verbindung in der Partneranwendung müssen die dort gespeicherten Tokens gelöscht werden. Ein Zugriffstoken kann bis zum Ende seiner 15-minütigen Gültigkeitsdauer gültig bleiben.

API-Zugriffstokens verwenden

Zugriffstokens von Parkour Design haben immer die Audience parkour-api. Sie sind ausschließlich Zugangsdaten für die unter Datenaustausch beschriebenen Ressourcen-APIs von Parkour Design. Leiten Sie sie niemals an eine Partner-API oder einen anderen Dritten weiter; vom Partner betriebene Ressourcen müssen einen eigenen Autorisierungsmechanismus verwenden.

ID-Tokens dienen zum Feststellen der Identität und zum Einrichten einer Partnersitzung. Verwenden Sie ein ID-Token nicht zum Aufruf einer API.

Aktuelles Scope-Verhalten

Die aktuellen Identitäts-Scopes sind openid, email und profile. Die abgestimmte Ressourcen-API autorisiert derzeit mit openid den Zugriff auf Veranstaltungen und Entwurfszusammenfassungen; sie stellt noch keine dedizierten Lese-Scopes bereit.

Dies ist eine Einschränkung der aktuellen Implementierung und kein Muster für neue APIs. Angeforderte Scopes und zugängliche Ressourcen werden bei der Client-Registrierung bestätigt. Künftige Ressourcenverträge können dedizierte Scopes einführen.

Aktuelle Tokens und UserInfo enthalten E-Mail-Adresse und Name in größerem Umfang, als die einzelnen Scopes email und profile erwarten lassen. Clients sollten weiterhin ausschließlich genehmigte Scopes anfordern und dürfen sich nicht darauf verlassen, dass dieses weiter gefasste Verhalten unverändert bleibt.

Fehlerbehandlung

Der Autorisierungsendpunkt übermittelt Fehler auf zwei Wegen:

• nachdem eine Redirect URI validiert wurde, führen die Ablehnung der Zustimmung und einige invalid_request-Fehler bei der Zustimmungsverarbeitung zu einer Weiterleitung an diesen Callback mit error und dem ursprünglichen state;
• Validierungsfehler, die auftreten, bevor ein vertrauenswürdiger Callback feststeht, einschließlich Fehlern bei Client, Redirect URI, Scope, Antworttyp und PKCE, geben direkt eine HTTP-400-Antwort im JSON-Format zurück.

Fehler des Token-Endpunkts und der Ressourcen-API verwenden ebenfalls einen kompakten JSON-Body:

{"error": "invalid_grant"}

Legen Sie unbearbeitete Token-Antworten oder Protokolldiagnosen nicht gegenüber dem Endbenutzer offen. Protokollieren Sie Korrelations-ID, Endpunkt, Status und sicheren Fehlercode, jedoch keine Autorisierungscodes, Tokens, Geheimnisse, Nonce-Werte oder personenbezogenen Daten.

Aktuelle Einschränkungen

• Client-Registrierung und Widerruf der Zustimmung werden manuell abgestimmt.
• PKCE, state und nonce werden akzeptiert, aber vom Server nicht erzwungen; Partner-Clients müssen sie erzwingen.
• Discovery weist PKCE plain aus; Partner-Clients müssen S256 verwenden.
• Es gibt keinen Endpunkt für Token-Widerruf, Introspektion, dynamische Registrierung oder standardmäßige Sitzungsbeendigung.
• Die erneute Verwendung eines Refresh-Tokens widerruft nicht die gesamte Token-Familie.
• Zugriffstokens bleiben nach einem lokalen Logout bis zu ihrem Ablauf gültig.
• Die aktuelle Ressourcenautorisierung verwendet openid anstelle dedizierter Ressourcen-Scopes.

Prüfen Sie diese Einschränkungen während des Onboardings und ersetzen Sie sie nicht stillschweigend durch Annahmen, die auf einem anderen OAuth-Provider beruhen.