Vpis s TTAR

Če imate spletno stran ali aplikacijo za ljubitelje namiznega tenisa — klub, turnirje, treninge, trgovino z opremo —, dodajte „Vpis s TTAR“. Igralci se bodo pri vas lahko z enim klikom vpisali s svojim računom TTAR, tako kot z Googlom ali Telegramom, brez novega uporabniškega imena in gesla. Vi pa takoj izveste, kdo je prišel k vam in kako dobro igra.

Kaj to prinese vaši storitvi:

• Več registracij. Ni treba izpolnjevati obrazcev in potrjevati e-naslova: igralec se vpiše s svojim računom TTAR, zato manj ljudi registracijo opusti na pol poti.
• Rating igralca takoj. Skupaj z avtorizacijo dobite rating TTAR: z njim lahko preprosto določite nosilce turnirja, razdelite udeležence v skupine po moči, poiščete partnerja za sparing ali preverite pravico do nastopa na tekmovanju.
• Lastne avtorizacije ne potrebujete. Shranjevanje gesel, obnovitev dostopa, vpis z Googlom in Telegramom — vse to v TTAR že deluje. Vaši razvijalci morajo le povezati standardni protokol OpenID Connect, za katerega obstajajo že pripravljene knjižnice za vse priljubljene programske jezike.
• Varno za igralce. Gesla za TTAR nikoli ne dobite: igralec ga vnese samo na strani TTAR. Posredujemo vam samo podatke, ki ste jih zahtevali — ID igralca, ime in avatar, e-naslov in rating.

Spodaj je tehnični opis. To stran lahko takoj posredujete razvijalcem.

Parametri strežnika za avtorizacijo

Večini knjižnic OIDC zadošča, da navedete Issuer: ostale naslove preberejo iz dokumenta 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

Registracija odjemalca

Vsak partner dobi client_id. Client secret se ne uporablja — podprt je samo PKCE (code_challenge_method=S256). Za registracijo nam pišite na kot@ttar.app.

Ob registraciji nam sporočite enega ali več redirect_uri — naslovov v vaši aplikaciji, na katere bomo uporabnika preusmerili po avtorizaciji. Dodamo jih na seznam dovoljenih naslovov. V vsaki zahtevi navedete točno določen naslov, strežnik pa ga preveri glede na ta seznam.

Dodatno lahko sporočite enega ali več post_logout_redirect_uri — naslovov, na katere uporabnika vrnemo po izpisu prek našega end-session endpointa /connect/logout (glejte razdelek „Izpis“ spodaj). To je ločen seznam dovoljenih naslovov: redirect_uri kot povratni naslov po izpisu ni sprejet. Potrebujete ga samo, če uporabljate ta izpis.

Vpis: Authorization Code + PKCE

1. korak. Uporabnika pošljite na avtorizacijo. Sestavite povezavo in jo odprite v uporabnikovem brskalniku s polnim prehodom na stran, 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

Če uporabnik v tem brskalniku še ni vpisan v TTAR, se mu odpre stran za vpis v TTAR in se vpiše. Če aktivna seja TTAR že obstaja, se stran za vpis preskoči in koda se izda takoj (single sign-on) — razen če ste s prompt=login zahtevali ponovni vpis. Neobvezna parametra prompt in max_age sta opisana v razdelku „Ponovni vpis in menjava računa“ spodaj.

2. korak. Sprejmite odgovor na redirect_uri. Po uspešnem vpisu se uporabnikov brskalnik samodejno preusmeri na vaš redirect_uri z dvema parametroma:

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

• code — enkratna avtorizacijska koda. Velja približno 60 sekund, zato jo uporabite takoj.
• state — ista vrednost, ki ste jo poslali v 1. koraku. Obvezno jo primerjajte s tisto, ki ste jo shranili pri sebi: to je zaščita pred CSRF.

Če je uporabnik zavrnil dostop ali je prišlo do napake, prejmete:

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

3. korak. Zamenjajte kodo za tokene. Na strežniku, ne v brskalniku, pošljite POST s kodo iz 2. koraka:

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

Odgovor:

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

• access_token — Bearer token za klice API, vključno z /connect/userinfo. To je JWT, podpisan z RS256.
• id_token — JWT z osnovnimi podatki o uporabniku: sub, ime, e-naslov itd. Podpis obvezno preverite.
• refresh_token — za pridobivanje novih tokenov brez ponovnega vpisa. Izda se samo, če ste zahtevali scope offline_access.

4. korak. Osvežujte tokene. Ko access token poteče, pridobite nove tokene z refresh tokenom:

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

Če je zahtevan scope ttar:rating in ima igralec rating, se v access tokenu pojavi claim ttar_rating. To je polje JSON z enim objektom za vsako roko — glavno in šibkejšo:

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

Ostali podatki (ime, avatar, e-naslov) so na voljo prek UserInfo endpointa /connect/userinfo ali v id_token.

Ponovni vpis in menjava računa

TTAR v uporabnikovem brskalniku hrani sejo single sign-on (SSO) — piškotek na domeni TTAR API. Dokler je aktivna, /connect/authorize izda kodo za istega uporabnika TTAR, ne da bi prikazal stran za vpis. Ta seja je neodvisna od seje vaše aplikacije: izpis uporabnika iz vaše aplikacije je ne konča.

• prompt=login — vedno prikaže stran za vpis v TTAR in zahteva ponovni vpis, tudi ko je seja aktivna: obstoječa seja TTAR se ne uporabi znova. Uporabnik se lahko vpiše z drugim računom TTAR. Priporočeno za povezovanje računa.
• prompt=select_account — enako kot prompt=login. Izbire računa v TTAR ni: uporabnik izbere račun tako, da se vanj vpiše.
• prompt=none — nikoli ne prikaže vmesnika. Če aktivne seje ni ali je starejša od max_age, se uporabnik vrne na vaš redirect_uri z error=login_required.
• prompt=consent — je sprejet, a ne vpliva na nič: registrirani partnerji so vnaprej odobreni, zaslona za privolitev v TTAR ni.
• max_age=N — če se je uporabnik vpisal pred več kot N sekundami, se bo moral vpisati znova. max_age=0 je enako kot prompt=login.

Neveljaven prompt (neznano vrednost ali none skupaj z drugo vrednostjo) TTAR zavrne s HTTP 400 — brskalnik se ne vrne na vaš redirect_uri.

Claim auth_time. id_token vsebuje auth_time — Unixov čas v sekundah zadnjega interaktivnega vpisa uporabnika v TTAR: z e-naslovom in geslom, z Googlom ali Telegramom. Pri osveževanju tokenov se ne spremeni. Manjka lahko samo pri sejah TTAR, ki so se začele pred uvedbo te funkcije. Taka seja nikoli ne zadosti prompt=login in max_age ter se vedno vzpostavi na novo, zato pri katerem koli od teh parametrov id_token obvezno vsebuje auth_time.

Povezovanje računa TTAR:

1. Zahtevi za avtorizacijo dodajte prompt=login in si zapomnite trenutek, ko ste jo začeli.
2. Po zamenjavi kode preverite, da auth_time ni zgodnejši od tega trenutka, z rezervo nekaj sekund za razhajanje ur. Tako se prepričate, da se je uporabnik res vpisal v okviru te zahteve in da ni bila znova uporabljena obstoječa seja.
3. Povezujte po sub — ID-ju igralca v TTAR.

Da bi uporabnik lahko povezal drug račun TTAR, izpis ni potreben — zadošča prompt=login.

Izpis

Izpis uporabnika iz vaše aplikacije ne konča njegove seje TTAR. Če želite v tem brskalniku končati tudi njo (na primer „izpiši me povsod“ ali skupni računalnik), pošljite uporabnikov brskalnik na end-session endpoint /connect/logout s polnim prehodom na stran. XHR in iframe ne bosta delovala: piškotek seje pripada domeni 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 izbriše svoj piškotek seje in preusmeri brskalnik na post_logout_redirect_uri, ki mu doda state.
• post_logout_redirect_uri mora biti registriran vnaprej. Ujemanje mora biti natančno, in to je ločen seznam, ne redirect_uri (glejte „Registracija odjemalca“). Z neregistriranim naslovom TTAR zavrne celotno zahtevo s HTTP 400 — in seja se ne konča.
• Brez post_logout_redirect_uri se seja konča, vendar se uporabnik ne vrne v vašo aplikacijo.
• id_token_hint ni obvezen. Če ga pošljete, mora biti to id_token, izdan vašemu client_id. Ustreza tudi potečen.
• Izpis konča uporabnikovo sejo TTAR v tem brskalniku za vse storitve, kjer je vklopljen „Vpis s TTAR“, ne samo za vašo.

Preverjanje tokenov

Tokeni so podpisani z RS256. Javni ključi so na standardnem naslovu JWKS:

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

Vsaka standardna knjižnica OIDC jih bo samodejno prevzela prek discovery endpointa. Preverite:

• podpis: alg=RS256, ključ iz JWKS;
• iss = https://stage.api.ttar.app;
• aud = vaš client_id;
• exp: token ni potekel;
• auth_time, če uporabljate prompt=login ali max_age (glejte „Claim auth_time“ zgoraj).

Pomembno za staging

• Staging je testno okolje za vaše preizkuse.
• Testni račun dobite posebej.
• Po prehodu na produkcijo ostane client_id enak, spremeni se samo Issuer — v https://api.ttar.app.