Anmelden mit TTAR

Wenn du eine Website oder App für Tischtennis-Fans betreibst — einen Club, Turniere, Training, einen Shop für Ausrüstung —, binde „Anmelden mit TTAR“ ein. Spieler können sich dann mit ihrem TTAR-Account mit einem Klick bei dir anmelden, wie mit Google oder Telegram, ohne neuen Login und neues Passwort. Und du weißt sofort, wer zu dir gekommen ist und wie stark er spielt.

Das bringt es deinem Dienst:

• Mehr Registrierungen. Kein Formular und keine E-Mail-Bestätigung nötig: Der Spieler meldet sich mit seinem TTAR-Login an, deshalb brechen weniger Leute die Registrierung auf halbem Weg ab.
• Das Rating des Spielers sofort. Zusammen mit der Anmeldung erhältst du das TTAR-Rating: Damit lassen sich Turniere bequem setzen, Teilnehmende nach Stärke in Gruppen einteilen, ein Sparringspartner finden oder die Zulassung zu einem Wettbewerb prüfen.
• Eine eigene Anmeldung ist nicht nötig. Passwortspeicherung, Zugangswiederherstellung, Anmeldung über Google und Telegram — das alles funktioniert in TTAR bereits. Entwickler müssen nur das Standardprotokoll OpenID Connect anbinden, dafür gibt es fertige Bibliotheken für alle gängigen Programmiersprachen.
• Sicher für Spieler. Das TTAR-Passwort bekommst du nie: Der Spieler gibt es nur auf der TTAR-Seite ein. Du erhältst nur die Daten, die du angefordert hast — Spieler-ID, Name und Avatar, E-Mail und Rating.

Unten folgt die technische Beschreibung. Diese Seite kannst du direkt an Entwickler weitergeben.

Parameter des Autorisierungsservers

Den meisten OIDC-Bibliotheken genügt die Angabe des Issuers: Die übrigen Adressen lesen sie aus dem Discovery-Dokument.

Issuer          https://stage.api.ttar.app
Discovery       https://stage.api.ttar.app/.well-known/openid-configuration
Authorization   https://stage.api.ttar.app/connect/authorize
Token           https://stage.api.ttar.app/connect/token
UserInfo        https://stage.api.ttar.app/connect/userinfo
End session     https://stage.api.ttar.app/connect/logout
JWKS            https://stage.api.ttar.app/.well-known/jwks

Client-Registrierung

Jeder Partner erhält eine client_id. Ein Secret wird nicht verwendet — unterstützt wird nur PKCE (code_challenge_method=S256). Zur Registrierung schreib uns an kot@ttar.app.

Bei der Registrierung teilst du uns eine oder mehrere redirect_uri mit — Adressen in deiner Anwendung, an die wir den Nutzer nach der Anmeldung weiterleiten. Wir tragen sie in eine Whitelist ein. In jeder Anfrage gibst du eine konkrete Adresse an, und der Server gleicht sie mit dieser Liste ab.

Zusätzlich kannst du eine oder mehrere post_logout_redirect_uri angeben — wohin der Nutzer nach der Abmeldung über unseren End-Session-Endpoint /connect/logout zurückgeleitet wird (siehe Abschnitt „Abmeldung“ unten). Das ist eine separate Whitelist: Eine redirect_uri wird als Rücksprungadresse nach der Abmeldung nicht akzeptiert. Sie wird nur gebraucht, wenn du diese Abmeldung verwendest.

Anmeldung: Authorization Code + PKCE

Schritt 1: Schick den Nutzer zur Anmeldung. Erzeuge den Link und öffne ihn im Browser des Nutzers als vollständigen Seitenwechsel, nicht in einem iframe:

GET https://stage.api.ttar.app/connect/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email ttar:rating
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
  &state=RANDOM_OPAQUE_VALUE

Ist der Nutzer in diesem Browser noch nicht bei TTAR angemeldet, landet er auf der TTAR-Anmeldeseite und meldet sich an. Gibt es bereits eine aktive TTAR-Sitzung, wird die Anmeldeseite übersprungen und der Code sofort ausgestellt (Single Sign-on) — es sei denn, du hast über prompt=login eine erneute Anmeldung verlangt. Die optionalen Parameter prompt und max_age sind unten im Abschnitt „Erneute Anmeldung und Accountwechsel“ beschrieben.

Schritt 2: Nimm die Antwort an der redirect_uri entgegen. Nach erfolgreicher Anmeldung wird der Browser des Nutzers automatisch auf deine redirect_uri weitergeleitet, mit zwei Parametern:

GET https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_OPAQUE_VALUE

• code — ein einmaliger Autorisierungscode. Er gilt etwa 60 Sekunden, verwende ihn sofort.
• state — derselbe Wert, den du in Schritt 1 übergeben hast. Gleiche ihn unbedingt mit dem bei dir gespeicherten ab: Das ist der Schutz vor CSRF.

Wenn der Nutzer abgelehnt hat oder ein Fehler aufgetreten ist, kommt Folgendes:

GET https://yourapp.com/callback?error=access_denied&error_description=...&state=...

Schritt 3: Tausche den Code gegen Tokens. Sende auf dem Server, nicht im Browser, einen POST mit dem Code aus Schritt 2:

POST https://stage.api.ttar.app/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&code_verifier=YOUR_CODE_VERIFIER

Antwort:

{
  "access_token": "...",
  "id_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

• access_token — Bearer-Token für Aufrufe der API, einschließlich /connect/userinfo. Es ist ein JWT, signiert mit RS256.
• id_token — ein JWT mit Basisinformationen über den Nutzer: sub, Name, E-Mail usw. Prüfe unbedingt die Signatur.
• refresh_token — um neue Tokens ohne erneute Anmeldung zu erhalten. Wird nur ausgestellt, wenn der Scope offline_access angefordert wurde.

Schritt 4: Erneuere die Tokens. Wenn das Access Token abläuft, hole dir mit dem Refresh Token neue Tokens:

POST https://stage.api.ttar.app/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&refresh_token=REFRESH_TOKEN

Scopes

Claim ttar_rating

Wenn der Scope ttar:rating angefordert wurde und der Spieler ein Rating hat, erscheint im Access Token der Claim ttar_rating. Das ist ein JSON-Array mit einem Objekt pro Hand — Schlaghand und andere Hand:

[
  {
    "handType": "Main",
    "rating": 1456,
    "games": 120,
    "qualificationPoints": 85,
    "isRated": true
  },
  {
    "handType": "Weak",
    "rating": 1102,
    "games": 15,
    "qualificationPoints": 10,
    "isRated": false
  }
]

Die übrigen Daten (Name, Avatar, E-Mail) sind über den UserInfo-Endpoint /connect/userinfo oder im id_token verfügbar.

Erneute Anmeldung und Accountwechsel

TTAR hält im Browser des Nutzers eine Single-Sign-on-Sitzung (SSO) — ein Cookie auf der Domain der TTAR-API. Solange sie aktiv ist, stellt /connect/authorize einen Code für denselben TTAR-Nutzer aus, ohne die Anmeldeseite zu zeigen. Diese Sitzung ist unabhängig von der Sitzung deiner Anwendung: Die Abmeldung des Nutzers aus deiner Anwendung beendet sie nicht.

• prompt=login — zeigt immer die TTAR-Anmeldeseite und verlangt eine erneute Anmeldung, auch bei aktiver Sitzung: Die bestehende TTAR-Sitzung wird nicht wiederverwendet. Der Nutzer kann sich mit einem anderen TTAR-Account anmelden. Empfohlen für das Verknüpfen von Accounts.
• prompt=select_account — dasselbe wie prompt=login. In TTAR gibt es keine Account-Auswahl: Der Nutzer wählt den Account, indem er sich damit anmeldet.
• prompt=none — zeigt nie eine Oberfläche. Gibt es keine aktive Sitzung oder ist sie älter als max_age, kehrt der Nutzer mit error=login_required zu deiner redirect_uri zurück.
• prompt=consent — wird akzeptiert und hat keine Wirkung: Registrierte Partner sind vorab genehmigt, in TTAR gibt es keinen Zustimmungsbildschirm.
• max_age=N — hat sich der Nutzer vor mehr als N Sekunden angemeldet, muss er sich erneut anmelden. max_age=0 — dasselbe wie prompt=login.

Einen ungültigen prompt (unbekannter Wert oder none zusammen mit einem anderen Wert) lehnt TTAR mit HTTP 400 ab — der Browser kehrt nicht zu deiner redirect_uri zurück.

Claim auth_time. Im id_token steht auth_time — die Unix-Zeit in Sekunden der letzten interaktiven Anmeldung des Nutzers bei TTAR: mit E-Mail und Passwort, über Google oder Telegram. Beim Erneuern der Tokens ändert er sich nicht. Fehlen kann er nur bei TTAR-Sitzungen, die vor Einführung dieser Funktion begonnen wurden. Eine solche Sitzung erfüllt prompt=login und max_age nie und wird immer neu aufgebaut, deshalb enthält das id_token mit einem dieser Parameter garantiert auth_time.

TTAR-Account verknüpfen:

1. Füge der Autorisierungsanfrage prompt=login hinzu und merke dir den Zeitpunkt, an dem du sie gestartet hast.
2. Prüfe nach dem Code-Austausch, dass auth_time nicht früher als dieser Zeitpunkt liegt, mit einigen Sekunden Spielraum für Uhrenabweichungen. So stellst du sicher, dass sich der Nutzer wirklich im Rahmen dieser Anfrage angemeldet hat und nicht eine bestehende Sitzung wiederverwendet wurde.
3. Verknüpfe über sub — die Spieler-ID in TTAR.

Damit der Nutzer einen anderen TTAR-Account verknüpfen kann, ist keine Abmeldung nötig — prompt=login genügt.

Abmeldung

Die Abmeldung des Nutzers aus deiner Anwendung beendet seine TTAR-Sitzung nicht. Soll auch sie in diesem Browser beendet werden (zum Beispiel „überall abmelden“ oder ein gemeinsam genutzter Computer), schick den Browser des Nutzers als vollständigen Seitenwechsel zum End-Session-Endpoint /connect/logout. XHR und iframe funktionieren nicht: Das Sitzungs-Cookie gehört zur TTAR-Domain.

GET https://stage.api.ttar.app/connect/logout
  ?client_id=YOUR_CLIENT_ID
  &post_logout_redirect_uri=https://yourapp.com/logged-out
  &state=RANDOM_OPAQUE_VALUE
  &id_token_hint=ID_TOKEN

• TTAR löscht sein Sitzungs-Cookie und leitet den Browser auf die post_logout_redirect_uri weiter, wobei state angehängt wird.
• Die post_logout_redirect_uri muss vorab registriert sein. Sie muss exakt übereinstimmen, und das ist eine separate Liste, nicht die der redirect_uri (siehe „Client-Registrierung“). Bei einer nicht registrierten Adresse lehnt TTAR die gesamte Anfrage mit HTTP 400 ab — und die Sitzung wird nicht beendet.
• Ohne post_logout_redirect_uri wird die Sitzung beendet, aber der Nutzer kehrt nicht in deine Anwendung zurück.
• id_token_hint ist optional. Wenn du es übergibst, muss es ein für deine client_id ausgestelltes id_token sein. Ein abgelaufenes passt ebenfalls.
• Die Abmeldung beendet die TTAR-Sitzung des Nutzers in diesem Browser für alle Dienste, die „Anmelden mit TTAR“ eingebunden haben, nicht nur für deinen.

Tokens prüfen

Die Tokens sind mit RS256 signiert. Die öffentlichen Schlüssel liegen unter der Standard-JWKS-Adresse:

https://stage.api.ttar.app/.well-known/jwks

Jede Standard-OIDC-Bibliothek übernimmt sie automatisch über den Discovery-Endpoint. Prüfe:

• die Signatur: alg=RS256, Schlüssel aus dem JWKS;
• iss = https://stage.api.ttar.app;
• aud = deine client_id;
• exp: das Token ist nicht abgelaufen;
• auth_time, wenn du prompt=login oder max_age verwendest (siehe „Claim auth_time“ oben).

Wichtig für Staging

• Staging ist eine Testumgebung für deine Experimente.
• Ein Account zum Testen wird separat bereitgestellt.
• Nach dem Wechsel auf Produktion bleibt die client_id dieselbe, nur der Issuer ändert sich — auf https://api.ttar.app.