Prijava putem TTAR-a

Ako imate web-stranicu ili aplikaciju za ljubitelje stolnog tenisa — klub, turnire, treninge, trgovinu opreme — dodajte „Prijavu putem TTAR-a“. Igrači će se kod vas moći prijaviti svojim TTAR računom jednim klikom, kao putem Googlea ili Telegrama, bez novog korisničkog imena i lozinke. A vi ćete odmah znati tko vam je došao i koliko dobro igra.

Što to donosi vašem servisu:

• Više registracija. Nema ispunjavanja obrazaca ni potvrđivanja e-adrese: igrač se prijavljuje svojim TTAR računom, pa manje ljudi odustaje od registracije na pola puta.
• Rejting igrača odmah. Zajedno s autorizacijom dobivate i TTAR rejting: na temelju njega lako je odrediti nositelje turnira, rasporediti sudionike u skupine prema jačini, pronaći sparing-partnera ili provjeriti pravo nastupa na natjecanju.
• Ne trebate vlastitu autorizaciju. Čuvanje lozinki, vraćanje pristupa, prijava putem Googlea i Telegrama — sve to već radi u TTAR-u. Vašim je programerima dovoljno povezati standardni protokol OpenID Connect, a za njega postoje gotove biblioteke za sve popularne programske jezike.
• Sigurno za igrače. TTAR lozinku nikada ne dobivate: igrač je unosi samo na stranici TTAR-a. Vama se prosljeđuju samo podaci koje ste zatražili — ID igrača, ime i avatar, e-adresa i rejting.

U nastavku je tehnički opis. Ovu stranicu možete odmah proslijediti programerima.

Parametri poslužitelja za autorizaciju

Većini OIDC biblioteka dovoljno je navesti Issuer: ostale adrese pročitat će same iz discovery dokumenta.

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 klijenta

Svaki partner dobiva client_id. Client secret se ne koristi — podržan je samo PKCE (code_challenge_method=S256). Da biste se registrirali, pišite nam na kot@ttar.app.

Pri registraciji navodite jedan ili više redirect_uri — adresa u vašoj aplikaciji na koje ćemo preusmjeravati korisnika nakon autorizacije. Mi ih dodajemo na bijelu listu. U svakom zahtjevu navodite konkretnu adresu, a poslužitelj je uspoređuje s tom listom.

Dodatno možete navesti jedan ili više post_logout_redirect_uri — adresa na koje vraćamo korisnika nakon odjave preko našeg end-session endpointa /connect/logout (pogledajte odjeljak „Odjava“ u nastavku). To je zasebna bijela lista: redirect_uri ne prihvaća se kao adresa za povratak nakon odjave. Ova vam je lista potrebna samo ako koristite takvu odjavu.

Prijava: Authorization Code + PKCE

Korak 1. Pošaljite korisnika na autorizaciju. Sastavite poveznicu i otvorite je u korisnikovu pregledniku navigacijom cijele stranice, a ne u iframeu:

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

Ako korisnik u ovom pregledniku još nije prijavljen u TTAR, otvara mu se stranica za prijavu u TTAR i on se prijavljuje. Ako aktivna TTAR sesija već postoji, stranica za prijavu se preskače i kod se izdaje odmah (single sign-on) — osim ako niste zatražili ponovnu prijavu pomoću prompt=login. Neobavezni parametri prompt i max_age opisani su u odjeljku „Ponovna prijava i promjena računa“ u nastavku.

Korak 2. Primite odgovor na redirect_uri. Nakon uspješne prijave korisnikov se preglednik automatski preusmjerava na vaš redirect_uri s dva parametra:

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

• code — jednokratni autorizacijski kod. Vrijedi oko 60 sekundi, zato ga odmah iskoristite.
• state — ista vrijednost koju ste poslali u koraku 1. Obavezno je usporedite s vrijednošću koju ste spremili kod sebe: to je zaštita od CSRF-a.

Ako je korisnik odbio pristup ili je došlo do pogreške, stiže:

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

Korak 3. Zamijenite kod za tokene. Na poslužitelju, a ne u pregledniku, pošaljite POST s kodom iz koraka 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

Odgovor:

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

• access_token — Bearer token za pozive API-ja, uključujući /connect/userinfo. To je JWT potpisan algoritmom RS256.
• id_token — JWT s osnovnim podacima o korisniku: sub, ime, e-adresa itd. Obavezno provjerite potpis.
• refresh_token — za dobivanje novih tokena bez ponovne prijave. Izdaje se samo ako je zatražen scope offline_access.

Korak 4. Osvježavajte tokene. Kada access token istekne, dobijte nove tokene pomoću refresh tokena:

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

Ako je zatražen scope ttar:rating i igrač ima rejting, u access tokenu pojavljuje se claim ttar_rating. To je JSON niz s po jednim objektom za svaku ruku — glavnu i slabiju:

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

Ostali podaci (ime, avatar, e-adresa) dostupni su preko UserInfo endpointa /connect/userinfo ili u tokenu id_token.

Ponovna prijava i promjena računa

TTAR u korisnikovu pregledniku održava single sign-on (SSO) sesiju — kolačić na domeni TTAR API-ja. Dok je ona aktivna, /connect/authorize izdaje kod za istog TTAR korisnika bez prikazivanja stranice za prijavu. Ta sesija ne ovisi o sesiji vaše aplikacije: odjava korisnika iz vaše aplikacije ne završava je.

• prompt=login — uvijek prikazuje stranicu za prijavu u TTAR i zahtijeva ponovnu prijavu, čak i kada postoji aktivna sesija: postojeća TTAR sesija ne koristi se ponovno. Korisnik se može prijaviti drugim TTAR računom. Preporučuje se za povezivanje računa.
• prompt=select_account — isto što i prompt=login. TTAR nema odabir računa: korisnik bira račun tako da se njime prijavi.
• prompt=none — nikada ne prikazuje sučelje. Ako aktivna sesija ne postoji ili je starija od max_age, korisnik se vraća na vaš redirect_uri s error=login_required.
• prompt=consent — prihvaća se, ali ni na što ne utječe: registrirani partneri unaprijed su odobreni, a zaslona za privolu u TTAR-u nema.
• max_age=N — ako se korisnik prijavio prije više od N sekundi, morat će se ponovno prijaviti. max_age=0 isto je što i prompt=login.

Neispravan prompt (nepoznata vrijednost ili none zajedno s nekom drugom vrijednošću) TTAR odbija s HTTP 400 — preglednik se ne vraća na vaš redirect_uri.

Claim auth_time. Token id_token sadrži auth_time — Unix vrijeme u sekundama posljednje interaktivne prijave korisnika u TTAR: e-adresom i lozinkom, putem Googlea ili Telegrama. Pri osvježavanju tokena ne mijenja se. Može nedostajati samo kod TTAR sesija započetih prije uvođenja ove funkcije. Takva sesija nikada ne zadovoljava ni prompt=login ni max_age i uvijek se uspostavlja iznova, pa uz bilo koji od tih parametara id_token obavezno sadrži auth_time.

Povezivanje TTAR računa:

1. Dodajte prompt=login u zahtjev za autorizaciju i zapamtite trenutak kada ste ga započeli.
2. Nakon zamjene koda provjerite da auth_time nije raniji od tog trenutka, uz rezervu od nekoliko sekundi zbog odstupanja satova. Tako ćete biti sigurni da se korisnik zaista prijavio u okviru ovog zahtjeva, a da nije ponovno iskorištena postojeća sesija.
3. Povezujte prema sub — ID-u igrača u TTAR-u.

Da bi korisnik mogao povezati drugi TTAR račun, odjava nije potrebna — dovoljan je prompt=login.

Odjava

Odjava korisnika iz vaše aplikacije ne završava njegovu TTAR sesiju. Ako i nju treba završiti u ovom pregledniku (na primjer, „odjavi se svugdje“ ili zajedničko računalo), pošaljite korisnikov preglednik na end-session endpoint /connect/logout navigacijom cijele stranice. XHR i iframe neće raditi: kolačić sesije pripada domeni TTAR-a.

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 briše svoj kolačić sesije i preusmjerava preglednik na post_logout_redirect_uri, dodajući mu state.
• post_logout_redirect_uri mora biti unaprijed registriran. Podudaranje mora biti točno, a to je zasebna lista, ne redirect_uri (pogledajte „Registracija klijenta“). Ako adresa nije registrirana, TTAR odbija cijeli zahtjev s HTTP 400 — i sesija se ne završava.
• Bez post_logout_redirect_uri sesija se završava, ali se korisnik ne vraća u vašu aplikaciju.
• id_token_hint nije obavezan. Ako ga šaljete, to mora biti id_token izdan za vaš client_id. Prihvaća se i onaj koji je istekao.
• Odjava završava korisnikovu TTAR sesiju u ovom pregledniku za sve servise na kojima je omogućena „Prijava putem TTAR-a“, a ne samo za vaš.

Provjera tokena

Tokeni su potpisani algoritmom RS256. Javni ključevi nalaze se na standardnoj JWKS adresi:

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

Svaka standardna OIDC biblioteka automatski će ih preuzeti preko discovery endpointa. Provjerite:

• potpis: alg=RS256, ključ iz JWKS-a;
• iss = https://stage.api.ttar.app;
• aud = vaš client_id;
• exp: token nije istekao;
• auth_time, ako koristite prompt=login ili max_age (pogledajte „Claim auth_time“ iznad).

Važno za staging

• Staging je testno okruženje za vaše eksperimente.
• Račun za testiranje osiguravamo zasebno.
• Nakon prelaska na produkciju client_id ostaje isti, mijenja se samo Issuer, koji postaje https://api.ttar.app.