Prihlásenie cez TTAR

Ak máš web alebo aplikáciu pre amatérskych hráčov stolného tenisu — klub, turnaje, tréningy, obchod s vybavením — pripoj „Prihlásenie cez TTAR“. Hráči sa u teba budú môcť prihlásiť svojím účtom TTAR jedným kliknutím, rovnako ako cez Google alebo Telegram, bez nového používateľského mena a hesla. A ty hneď zistíš, kto k tebe prišiel a ako silno hrá.

Čo to prinesie tvojej službe:

• Viac registrácií. Netreba vypĺňať formulár ani potvrdzovať e-mail: hráč sa prihlási svojimi prihlasovacími údajmi TTAR, takže menej ľudí opustí registráciu v polovici.
• Rating hráča hneď. Spolu s prihlásením dostaneš rating TTAR: podľa neho ľahko nasadíš hráčov v turnaji, rozdelíš účastníkov do skupín podľa sily, nájdeš sparingpartnera alebo overíš, či sa hráč smie zúčastniť súťaže.
• Vlastné prihlasovanie netreba. Ukladanie hesiel, obnovenie prístupu, prihlásenie cez Google a Telegram — to všetko už v TTAR funguje. Vývojárom stačí pripojiť štandardný protokol OpenID Connect, pre ktorý existujú hotové knižnice pre všetky populárne programovacie jazyky.
• Bezpečné pre hráčov. Heslo k TTAR nikdy nedostaneš: hráč ho zadáva iba na stránke TTAR. Odovzdáme ti len tie údaje, o ktoré požiadaš — ID hráča, meno a avatar, e-mail a rating.

Nižšie je technický popis. Túto stránku môžeš rovno odovzdať vývojárom.

Parametre autorizačného servera

Väčšine knižníc OIDC stačí zadať Issuer: ostatné adresy si načítajú 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

Registrácia klienta

Každý partner dostane client_id. Client secret sa nepoužíva — podporuje sa iba PKCE (code_challenge_method=S256). Na registráciu nám napíš na kot@ttar.app.

Pri registrácii nám oznámiš jednu alebo viac adries redirect_uri — adries v tvojej aplikácii, kam budeme používateľa po autorizácii presmerovávať. Zaradíme ich na zoznam povolených adries. V každej požiadavke uvedieš konkrétnu adresu a server ju s týmto zoznamom porovná.

Navyše môžeš oznámiť jednu alebo viac adries post_logout_redirect_uri — kam vrátiť používateľa po odhlásení cez náš end-session endpoint /connect/logout (pozri sekciu „Odhlásenie“ nižšie). Je to samostatný zoznam povolených adries: redirect_uri sa ako adresa na návrat po odhlásení neprijíma. Potrebuješ ho, len ak toto odhlásenie používaš.

Prihlásenie: Authorization Code + PKCE

Krok 1. Pošli používateľa na autorizáciu. Zostav odkaz a otvor ho v prehliadači používateľa plným prechodom na stránku, nie v 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

Ak používateľ v tomto prehliadači ešte nie je prihlásený do TTAR, dostane sa na prihlasovaciu stránku TTAR a prihlási sa. Ak už má aktívnu reláciu TTAR, prihlasovacia stránka sa preskočí a kód sa vydá hneď (single sign-on) — ibaže by si si vyžiadal opätovné prihlásenie cez prompt=login. Nepovinné parametre prompt a max_age sú opísané v sekcii „Opätovné prihlásenie a zmena účtu“ nižšie.

Krok 2. Prijmi odpoveď na redirect_uri. Po úspešnom prihlásení sa prehliadač používateľa automaticky presmeruje na tvoj redirect_uri s dvoma parametrami:

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

• code — jednorazový autorizačný kód. Platí približne 60 sekúnd, použi ho hneď.
• state — rovnaká hodnota, akú si odovzdal v kroku 1. Nezabudni ju porovnať s hodnotou uloženou u seba: je to ochrana proti CSRF.

Ak používateľ prístup odmietol alebo nastala chyba, príde:

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

Krok 3. Vymeň kód za tokeny. Na serveri, nie v prehliadači, pošli POST s kódom 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

Odpoveď:

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

• access_token — Bearer token na volanie API vrátane /connect/userinfo. Je to JWT podpísaný RS256.
• id_token — JWT so základnými informáciami o používateľovi: sub, meno, e-mail atď. Podpis vždy overuj.
• refresh_token — slúži na získanie nových tokenov bez opätovného prihlásenia. Vydáva sa, len ak bol vyžiadaný scope offline_access.

Krok 4. Obnovuj tokeny. Keď access token vyprší, získaj nové tokeny pomocou 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

Ak je vyžiadaný scope ttar:rating a hráč má rating, v access tokene sa objaví claim ttar_rating. Je to pole JSON s jedným objektom pre každú ruku — hlavnú a slabšiu:

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

Ostatné údaje (meno, avatar, e-mail) sú dostupné cez UserInfo endpoint /connect/userinfo alebo v id_token.

Opätovné prihlásenie a zmena účtu

TTAR udržiava v prehliadači používateľa reláciu single sign-on (SSO) — cookie na doméne TTAR API. Kým je aktívna, /connect/authorize vydáva kód pre toho istého používateľa TTAR bez zobrazenia prihlasovacej stránky. Táto relácia nezávisí od relácie tvojej aplikácie: odhlásenie používateľa z tvojej aplikácie ju neukončí.

• prompt=login — vždy zobrazí prihlasovaciu stránku TTAR a vyžaduje nové prihlásenie, aj pri aktívnej relácii: existujúca relácia TTAR sa znova nepoužije. Používateľ sa môže prihlásiť do iného účtu TTAR. Odporúčané na prepojenie účtu.
• prompt=select_account — to isté čo prompt=login. Výber účtu v TTAR nie je: používateľ si účet vyberie tým, že sa doň prihlási.
• prompt=none — nikdy nezobrazí žiadne rozhranie. Ak aktívna relácia neexistuje alebo je staršia ako max_age, používateľ sa vráti na tvoj redirect_uri s error=login_required.
• prompt=consent — prijíma sa a nemá žiadny vplyv: registrovaní partneri sú schválení vopred, obrazovka súhlasu v TTAR nie je.
• max_age=N — ak sa používateľ prihlásil pred viac ako N sekundami, bude sa musieť prihlásiť znova. max_age=0 je to isté čo prompt=login.

Neplatný prompt (neznámu hodnotu alebo none spolu s inou hodnotou) TTAR odmietne s HTTP 400 — prehliadač nie je presmerovaný späť na tvoj redirect_uri.

Claim auth_time. V id_token je auth_time — unixový čas v sekundách posledného interaktívneho prihlásenia používateľa do TTAR: e-mailom a heslom, cez Google alebo Telegram. Pri obnove tokenov sa nemení. Chýbať môže len pri reláciách TTAR začatých pred zavedením tejto funkcie. Taká relácia nikdy nespĺňa prompt=login ani max_age a vždy sa zakladá znova, preto s ktorýmkoľvek z týchto parametrov id_token vždy obsahuje auth_time.

Prepojenie účtu TTAR:

1. Pridaj do autorizačnej požiadavky prompt=login a zapamätaj si okamih, keď si ju začal.
2. Po výmene kódu over, že auth_time nie je skorší ako tento okamih, s rezervou niekoľkých sekúnd na rozdiel hodín. Tak sa uistíš, že sa používateľ naozaj prihlásil v rámci tejto požiadavky a nebola znova použitá existujúca relácia.
3. Prepájaj podľa sub — ID hráča v TTAR.

Aby používateľ mohol prepojiť iný účet TTAR, odhlásenie netreba — stačí prompt=login.

Odhlásenie

Odhlásenie používateľa z tvojej aplikácie neukončí jeho reláciu TTAR. Ak ju chceš v tomto prehliadači ukončiť tiež (napríklad „odhlásiť sa všade“ alebo zdieľaný počítač), pošli prehliadač používateľa na end-session endpoint /connect/logout plným prechodom na stránku. XHR ani iframe nefungujú: cookie relácie patrí doméne 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 zmaže svoju cookie relácie a presmeruje prehliadač na post_logout_redirect_uri, ku ktorému pripojí state.
• post_logout_redirect_uri musí byť zaregistrovaný vopred. Zhoda musí byť presná a ide o samostatný zoznam, nie redirect_uri (pozri „Registrácia klienta“). S nezaregistrovanou adresou TTAR odmietne celú požiadavku s HTTP 400 — a relácia sa neukončí.
• Bez post_logout_redirect_uri sa relácia ukončí, ale používateľ sa do tvojej aplikácie nevráti.
• id_token_hint je nepovinný. Ak ho odovzdávaš, musí to byť id_token vydaný pre tvoj client_id. Hodí sa aj taký, ktorého platnosť už vypršala.
• Odhlásenie ukončí reláciu TTAR používateľa v tomto prehliadači pre všetky služby, kde je pripojené „Prihlásenie cez TTAR“, nielen pre tú tvoju.

Overenie tokenov

Tokeny sú podpísané RS256. Verejné kľúče sú na štandardnej adrese JWKS:

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

Každá štandardná knižnica OIDC si ich automaticky načíta cez discovery endpoint. Overuj:

• podpis: alg=RS256, kľúč z JWKS;
• iss = https://stage.api.ttar.app;
• aud = tvoj client_id;
• exp: platnosť tokenu nevypršala;
• auth_time, ak používaš prompt=login alebo max_age (pozri „Claim auth_time“ vyššie).

Dôležité pre staging

• Staging je testovacie prostredie pre tvoje experimenty.
• Testovací účet poskytujeme zvlášť.
• Po prechode na produkciu zostane client_id rovnaký, zmení sa len Issuer — na https://api.ttar.app.