Web

Bejelentkezés TTAR-fiókkal

Bejelentkezés TTAR-fiókkal a weboldaladon vagy az alkalmazásodban: a játékosok egy kattintással lépnek be, te pedig azonnal látod az értékszámukat.

Ha asztaliteniszezőknek szóló weboldalad vagy alkalmazásod van — klub, versenyek, edzések, felszerelésbolt —, kapcsold be a „Bejelentkezés TTAR-fiókkal” lehetőséget. A játékosok egyetlen kattintással beléphetnek nálad a TTAR-fiókjukkal, ahogy a Google-lel vagy a Telegrammal, új felhasználónév és jelszó nélkül. Te pedig rögtön tudod, ki érkezett hozzád, és milyen erősen játszik.

Mit nyer vele a szolgáltatásod:

Több regisztráció. Nem kell űrlapot kitölteni és e-mail-címet megerősíteni: a játékos a TTAR-fiókjával lép be, így kevesebben hagyják félbe a regisztrációt.
Azonnal megvan a játékos értékszáma. A bejelentkezéssel együtt megkapod a TTAR-értékszámot: ez alapján kényelmesen elkészítheted a verseny kiemelését, erősség szerint csoportokba sorolhatod a résztvevőket, edzőpartnert kereshetsz, vagy ellenőrizheted, hogy valaki indulhat-e egy versenyen.
Nem kell saját bejelentkezési rendszer. Jelszavak tárolása, hozzáférés visszaállítása, bejelentkezés Google-lel és Telegrammal — mindez már működik a TTAR-rendszerben. A fejlesztőidnek elég a szabványos OpenID Connect protokollt bekötniük, ehhez minden népszerű programozási nyelvhez van kész könyvtár.
Biztonságos a játékosoknak. A TTAR-jelszót soha nem kapod meg: a játékos csak a TTAR oldalán adja meg. Csak azokat az adatokat kapod meg, amelyeket kértél — a játékos azonosítóját, nevét és avatárját, e-mail-címét és értékszámát.

Csatlakozás

Partnerré válni egyszerű és ingyenes: írj nekünk a kot@ttar.app címre, és mesélj a szolgáltatásodról — mindent megadunk, ami a csatlakozáshoz kell. A játékosaid nem fognak „Engedélyezed a hozzáférést?” képernyőt látni: a partnereket mi magunk kapcsoljuk be, ezért eleve jóvá vannak hagyva.

Alább a műszaki leírás következik. Ezt az oldalt egyből továbbadhatod a fejlesztőidnek.

Az authorization szerver paraméterei

A legtöbb OIDC-könyvtárnak elég az Issuer megadása: a többi címet kiolvassák a discovery-dokumentumból.

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

Kliens regisztrálása

Minden partner kap egy client_id azonosítót. Client secretet nem használunk — csak a PKCE támogatott (code_challenge_method=S256). A regisztrációhoz írj nekünk a kot@ttar.app címre.

A regisztrációkor megadsz egy vagy több redirect_uri címet — azokat a címeket az alkalmazásodban, ahová a bejelentkezés után visszaküldjük a felhasználót. Ezeket felvesszük a fehérlistára. Minden kérésben megadod a konkrét címet, a szerver pedig összeveti ezzel a listával.

Emellett megadhatsz egy vagy több post_logout_redirect_uri címet is — ahová a felhasználót visszaküldjük, miután a /connect/logout end-session endpointunkon keresztül kijelentkezett (lásd lent a „Kijelentkezés” részt). Ez egy külön fehérlista: a redirect_uri nem fogadható el kijelentkezés utáni visszatérési címként. Csak akkor van rá szükség, ha ezt a kijelentkezést használod.

Bejelentkezés: Authorization Code + PKCE

1. lépés. Irányítsd át a felhasználót bejelentkezésre. Állítsd össze a linket, és nyisd meg a felhasználó böngészőjében teljes oldalnavigációval, ne iframe-ben:

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

Ha a felhasználó ebben a böngészőben még nem lépett be a TTAR-fiókjába, a TTAR bejelentkezési oldalára kerül, és belép. Ha már van aktív TTAR-munkamenete, a bejelentkezési oldal kimarad, és a kódot azonnal megkapod (single sign-on) — kivéve, ha a prompt=login paraméterrel újbóli bejelentkezést kértél. A nem kötelező prompt és max_age paramétereket lent, az „Újbóli bejelentkezés és fiókváltás” részben írjuk le.

2. lépés. Fogadd a választ a redirect_uri címen. Sikeres bejelentkezés után a felhasználó böngészőjét automatikusan átirányítjuk a redirect_uri címedre, két paraméterrel:

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

code — egyszer használatos authorization code. Körülbelül 60 másodpercig érvényes, ezért azonnal használd fel.
state — ugyanaz az érték, amelyet az 1. lépésben küldtél. Mindenképp vesd össze a nálad eltárolttal: ez véd a CSRF ellen.

Ha a felhasználó megtagadta a hozzáférést, vagy hiba történt, ez érkezik:

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

3. lépés. Cseréld be a kódot tokenekre. A szerveren, ne a böngészőben, küldj egy POST kérést a 2. lépésben kapott kóddal:

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

Fontos

A redirect_uri értékének itt meg kell egyeznie az 1. lépésben küldöttel: a szerver kiegészítő ellenőrzésként használja.

Válasz:

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

access_token — Bearer token az API-hívásokhoz, a /connect/userinfo endpointot is beleértve. RS256-os aláírású JWT.
id_token — JWT a felhasználó alapadataival: sub, név, e-mail stb. Az aláírását mindenképp ellenőrizd.
refresh_token — új tokenek szerzéséhez újbóli bejelentkezés nélkül. Csak akkor kapod meg, ha az offline_access scope-ot is kérted.

4. lépés. Frissítsd a tokeneket. Amikor az access token lejár, kérj új tokeneket a refresh tokennel:

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

Scope-ok

Scope	Mit ad vissza
`openid`	`sub` (a játékos TTAR-azonosítója). Kötelező.
`profile`	`name`, `picture` (az avatár URL-je)
`email`	`email`, `email_verified`
`offline_access`	Hozzáadja a `refresh_token` mezőt a `/connect/token` token endpoint válaszához. E scope nélkül nem kapsz refresh tokent.
`ttar:rating`	A `ttar_rating` claim az access tokenben — a játékos értékszámainak tömbje (lásd lent).

A ttar_rating claim

Ha kérted a ttar:rating scope-ot, és a játékosnak van értékszáma, az access tokenben megjelenik a ttar_rating claim. Ez egy JSON-tömb, kezenként egy objektummal — a fő és a gyengébb kézre:

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

A többi adat (név, avatár, e-mail) a /connect/userinfo UserInfo endpointon vagy az id_token részeként érhető el.

Újbóli bejelentkezés és fiókváltás

A TTAR single sign-on (SSO) munkamenetet tart fenn a felhasználó böngészőjében — ez egy cookie a TTAR API domainjén. Amíg aktív, a /connect/authorize ugyanannak a TTAR-felhasználónak ad ki kódot, a bejelentkezési oldal megjelenítése nélkül. Ez a munkamenet független az alkalmazásod munkamenetétől: ha a felhasználó kijelentkezik az alkalmazásodból, az nem zárja le.

prompt=login — mindig megjeleníti a TTAR bejelentkezési oldalát, és újbóli belépést kér, még aktív munkamenet mellett is: a meglévő TTAR-munkamenetet nem használja fel újra. A felhasználó másik TTAR-fiókkal is beléphet. Fiókösszekapcsoláshoz ajánlott.
prompt=select_account — ugyanaz, mint a prompt=login. A TTAR-rendszerben nincs fiókválasztó: a felhasználó úgy választ fiókot, hogy belép vele.
prompt=none — soha nem jelenít meg felületet. Ha nincs aktív munkamenet, vagy régebbi a max_age értékénél, a felhasználó a redirect_uri címedre tér vissza error=login_required paraméterrel.
prompt=consent — elfogadjuk, de nincs hatása: a regisztrált partnerek eleve jóvá vannak hagyva, a TTAR-rendszerben nincs hozzájárulási képernyő.
max_age=N — ha a felhasználó több mint N másodperce lépett be, újra be kell lépnie. A max_age=0 ugyanaz, mint a prompt=login.

Érvénytelen prompt értéket (ismeretlen értéket, vagy a none értéket egy másikkal együtt) a TTAR HTTP 400 hibakóddal utasít el — a böngésző nem tér vissza a redirect_uri címedre.

Az auth_time claim. Az id_token tartalmazza az auth_time claimet — a felhasználó legutóbbi interaktív TTAR-bejelentkezésének időpontját Unix-időben, másodpercben: e-mail-címmel és jelszóval, Google-lel vagy Telegrammal. Tokenfrissítéskor nem változik. Csak azoknál a TTAR-munkameneteknél hiányozhat, amelyek e funkció megjelenése előtt indultak. Az ilyen munkamenet soha nem elégíti ki a prompt=login és a max_age feltételét, és mindig újra létrejön, ezért ha bármelyik paramétert használod, az id_token biztosan tartalmazza az auth_time értéket.

TTAR-fiók összekapcsolása:

Add hozzá az authorization kéréshez a prompt=login paramétert, és jegyezd fel, mikor indítottad.
A kódcsere után ellenőrizd, hogy az auth_time nem korábbi ennél az időpontnál, néhány másodperces ráhagyással az órák eltérése miatt. Így meggyőződhetsz róla, hogy a felhasználó valóban ebben a kérésben lépett be, és nem egy meglévő munkamenetet használtak fel újra.
Az összekapcsolás alapja a sub — a játékos TTAR-azonosítója.

Megjegyzés

Google-bejelentkezésnél előfordulhat, hogy maga a Google nem kér jelszót, ha a felhasználó ebben a böngészőben már be van jelentkezve a Google-ba. A TTAR számára ez akkor is friss interaktív bejelentkezés, és az auth_time ezt tükrözi.

Ahhoz, hogy a felhasználó egy másik TTAR-fiókot kapcsoljon össze, nem kell kijelentkeznie — elég a prompt=login.

Kijelentkezés

Ha a felhasználó kijelentkezik az alkalmazásodból, a TTAR-munkamenete nem zárul le. Ha ebben a böngészőben azt is le kell zárni (például „kijelentkezés mindenhonnan” vagy közös számítógép esetén), küldd a felhasználó böngészőjét a /connect/logout end-session endpointra teljes oldalnavigációval. XHR vagy iframe nem megfelelő: a munkamenet-cookie a TTAR domainjéhez tartozik.

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

A TTAR törli a munkamenet-cookie-ját, és átirányítja a böngészőt a post_logout_redirect_uri címre, hozzáfűzve a state paramétert.
A post_logout_redirect_uri címet előre regisztrálni kell. Pontos egyezés szükséges, és ez külön lista, nem a redirect_uri (lásd „Kliens regisztrálása”). Nem regisztrált cím esetén a TTAR az egész kérést HTTP 400 hibakóddal elutasítja — és a munkamenet nem zárul le.
post_logout_redirect_uri nélkül a munkamenet lezárul, de a felhasználó nem tér vissza az alkalmazásodba.
Az id_token_hint nem kötelező. Ha elküldöd, olyan id_token legyen, amelyet a client_id értékedhez adtak ki. Lejárt is megfelel.
A kijelentkezés ebben a böngészőben a felhasználó TTAR-munkamenetét minden olyan szolgáltatásban lezárja, ahol be van kapcsolva a „Bejelentkezés TTAR-fiókkal”, nem csak a tiédben.

Tokenek ellenőrzése

A tokenek RS256-os aláírásúak. A nyilvános kulcsok a szabványos JWKS címen érhetők el:

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

Bármely szabványos OIDC-könyvtár automatikusan betölti őket a discovery endpointon keresztül. Ellenőrizd:

az aláírást: alg=RS256, a kulcs a JWKS-ből;
iss = https://stage.api.ttar.app;
aud = a te client_id értéked;
exp: a token nem járt le;
az auth_time értéket, ha prompt=login vagy max_age paramétert használsz (lásd fent: „Az auth_time claim”).

Tudnivalók a staging környezetről

A staging tesztkörnyezet a kísérleteidhez.
A tesztfiókot külön biztosítjuk.
Az éles környezetre való átálláskor a client_id ugyanaz marad, csak az Issuer változik: az új érték https://api.ttar.app.