Přihlášení přes TTAR

Pokud máš web nebo aplikaci pro amatérské hráče stolního tenisu — klub, turnaje, tréninky, obchod s vybavením — připoj „Přihlášení přes TTAR“. Hráči se u tebe budou moct přihlásit svým účtem TTAR jedním kliknutím, stejně jako přes Google nebo Telegram, bez nového uživatelského jména a hesla. A ty hned zjistíš, kdo k tobě přišel a jak silně hraje.

Co to přinese tvé službě:

• Víc registrací. Není třeba vyplňovat formulář ani potvrzovat e-mail: hráč se přihlásí svými přihlašovacími údaji TTAR, takže méně lidí opustí registraci v polovině.
• Rating hráče hned. Spolu s přihlášením dostaneš rating TTAR: podle něj snadno nasadíš hráče v turnaji, rozdělíš účastníky do skupin podle síly, najdeš sparingpartnera nebo ověříš, zda se hráč smí zúčastnit soutěže.
• Vlastní přihlašování není potřeba. Ukládání hesel, obnovení přístupu, přihlášení přes Google a Telegram — to vše už v TTAR funguje. Vývojářům stačí připojit standardní protokol OpenID Connect, pro který existují hotové knihovny pro všechny populární programovací jazyky.
• Bezpečné pro hráče. Heslo k TTAR nikdy nedostaneš: hráč ho zadává jen na stránce TTAR. Předáme ti jen ta data, o která požádáš — ID hráče, jméno a avatar, e-mail a rating.

Níže je technický popis. Tuto stránku můžeš rovnou předat vývojářům.

Parametry autorizačního serveru

Většině knihoven OIDC stačí zadat Issuer: ostatní adresy si načtou z dokumentu discovery.

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

Registrace klienta

Každý partner dostane client_id. Client secret se nepoužívá — podporuje se pouze PKCE (code_challenge_method=S256). Pro registraci nám napiš na kot@ttar.app.

Při registraci nám sdělíš jednu nebo více adres redirect_uri — adres ve tvé aplikaci, kam budeme uživatele po autorizaci přesměrovávat. Zařadíme je na seznam povolených adres. V každém požadavku uvedeš konkrétní adresu a server ji s tímto seznamem porovná.

Navíc můžeš sdělit jednu nebo více adres post_logout_redirect_uri — kam vrátit uživatele po odhlášení přes náš end-session endpoint /connect/logout (viz sekce „Odhlášení“ níže). Je to samostatný seznam povolených adres: redirect_uri se jako adresa pro návrat po odhlášení nepřijímá. Potřebuješ ho, jen pokud toto odhlášení používáš.

Přihlášení: Authorization Code + PKCE

Krok 1. Pošli uživatele na autorizaci. Sestav odkaz a otevři ho v prohlížeči uživatele plným přechodem na stránku, ne v iframu:

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

Pokud uživatel v tomto prohlížeči ještě není přihlášený do TTAR, dostane se na přihlašovací stránku TTAR a přihlásí se. Pokud už má aktivní relaci TTAR, přihlašovací stránka se přeskočí a kód se vydá hned (single sign-on) — pokud sis ovšem nevyžádal opětovné přihlášení přes prompt=login. Nepovinné parametry prompt a max_age jsou popsány v sekci „Opětovné přihlášení a změna účtu“ níže.

Krok 2. Přijmi odpověď na redirect_uri. Po úspěšném přihlášení se prohlížeč uživatele automaticky přesměruje na tvůj redirect_uri se dvěma parametry:

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

• code — jednorázový autorizační kód. Platí zhruba 60 sekund, použij ho hned.
• state — stejná hodnota, jakou jsi předal v kroku 1. Nezapomeň ji porovnat s hodnotou uloženou u sebe: je to ochrana proti CSRF.

Pokud uživatel přístup odmítl nebo došlo k chybě, přijde:

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

Krok 3. Vyměň kód za tokeny. Na serveru, ne v prohlížeči, pošli POST s kódem z kroku 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

Odpověď:

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

• access_token — Bearer token pro volání API, včetně /connect/userinfo. Je to JWT podepsaný RS256.
• id_token — JWT se základními informacemi o uživateli: sub, jméno, e-mail atd. Podpis vždy ověřuj.
• refresh_token — slouží k získání nových tokenů bez opětovného přihlášení. Vydává se, jen pokud byl vyžádán scope offline_access.

Krok 4. Obnovuj tokeny. Když access token vyprší, získej nové tokeny pomocí refresh tokenu:

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

Pokud je vyžádán scope ttar:rating a hráč má rating, objeví se v access tokenu claim ttar_rating. Je to pole JSON s jedním objektem pro každou ruku — hlavní a slabší:

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

Ostatní údaje (jméno, avatar, e-mail) jsou dostupné přes UserInfo endpoint /connect/userinfo nebo v id_token.

Opětovné přihlášení a změna účtu

TTAR udržuje v prohlížeči uživatele relaci single sign-on (SSO) — cookie na doméně TTAR API. Dokud je aktivní, /connect/authorize vydává kód pro stejného uživatele TTAR, aniž by zobrazil přihlašovací stránku. Tato relace nezávisí na relaci tvé aplikace: odhlášení uživatele z tvé aplikace ji neukončí.

• prompt=login — vždy zobrazí přihlašovací stránku TTAR a vyžaduje nové přihlášení, i při aktivní relaci: existující relace TTAR se znovu nepoužije. Uživatel se může přihlásit k jinému účtu TTAR. Doporučeno pro propojení účtu.
• prompt=select_account — totéž co prompt=login. Výběr účtu v TTAR není: uživatel si účet vybere tím, že se k němu přihlásí.
• prompt=none — nikdy nezobrazí žádné rozhraní. Pokud aktivní relace neexistuje nebo je starší než max_age, uživatel se vrátí na tvůj redirect_uri s error=login_required.
• prompt=consent — přijímá se a nemá žádný vliv: registrovaní partneři jsou schválení předem, obrazovka souhlasu v TTAR není.
• max_age=N — pokud se uživatel přihlásil před více než N sekundami, bude se muset přihlásit znovu. max_age=0 je totéž co prompt=login.

Neplatný prompt (neznámou hodnotu nebo none spolu s jinou hodnotou) TTAR odmítne s HTTP 400 — prohlížeč není přesměrován zpět na tvůj redirect_uri.

Claim auth_time. V id_token je auth_time — unixový čas v sekundách posledního interaktivního přihlášení uživatele do TTAR: e-mailem a heslem, přes Google nebo Telegram. Při obnově tokenů se nemění. Chybět může jen u relací TTAR zahájených před zavedením této funkce. Taková relace nikdy nesplňuje prompt=login ani max_age a vždy se zakládá znovu, proto s kterýmkoli z těchto parametrů id_token vždy obsahuje auth_time.

Propojení účtu TTAR:

1. Přidej do autorizačního požadavku prompt=login a zapamatuj si okamžik, kdy jsi ho zahájil.
2. Po výměně kódu ověř, že auth_time není dřívější než tento okamžik, s rezervou několika sekund na rozdíl hodin. Tak se ujistíš, že se uživatel opravdu přihlásil v rámci tohoto požadavku a nebyla znovu použita existující relace.
3. Propojuj podle sub — ID hráče v TTAR.

Aby uživatel mohl propojit jiný účet TTAR, odhlášení není potřeba — stačí prompt=login.

Odhlášení

Odhlášení uživatele z tvé aplikace neukončí jeho relaci TTAR. Pokud ji chceš v tomto prohlížeči ukončit také (například „odhlásit se všude“ nebo sdílený počítač), pošli prohlížeč uživatele na end-session endpoint /connect/logout plným přechodem na stránku. XHR ani iframe nefungují: cookie relace patří doméně TTAR.

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 smaže svou cookie relace a přesměruje prohlížeč na post_logout_redirect_uri, ke kterému připojí state.
• post_logout_redirect_uri musí být zaregistrován předem. Shoda musí být přesná a jde o samostatný seznam, ne redirect_uri (viz „Registrace klienta“). S nezaregistrovanou adresou TTAR odmítne celý požadavek s HTTP 400 — a relace se neukončí.
• Bez post_logout_redirect_uri se relace ukončí, ale uživatel se do tvé aplikace nevrátí.
• id_token_hint je nepovinný. Pokud ho předáváš, musí to být id_token vydaný pro tvůj client_id. Vypršený se hodí také.
• Odhlášení ukončí relaci TTAR uživatele v tomto prohlížeči pro všechny služby, kde je připojeno „Přihlášení přes TTAR“, nejen pro tu tvou.

Ověření tokenů

Tokeny jsou podepsány RS256. Veřejné klíče jsou na standardní adrese JWKS:

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

Každá standardní knihovna OIDC si je automaticky načte přes discovery endpoint. Ověřuj:

• podpis: alg=RS256, klíč z JWKS;
• iss = https://stage.api.ttar.app;
• aud = tvůj client_id;
• exp: token nevypršel;
• auth_time, pokud používáš prompt=login nebo max_age (viz „Claim auth_time“ výše).

Důležité pro staging

• Staging je testovací prostředí pro tvoje experimenty.
• Testovací účet poskytujeme zvlášť.
• Po přechodu na produkci zůstane client_id stejný, změní se jen Issuer — na https://api.ttar.app.