Prijava putem TTAR-a

Ako imate sajt ili aplikaciju za ljubitelje stonog tenisa — klub, turnire, treninge, prodavnicu opreme — dodajte „Prijavu putem TTAR-a“. Igrači će moći da se kod vas prijave svojim TTAR nalogom jednim klikom, kao putem Google-a ili Telegram-a, bez novog korisničkog imena i lozinke. A vi ćete odmah znati ko vam je došao i koliko dobro igra.

Šta to donosi vašem servisu:

• Više registracija. Nema popunjavanja formulara ni potvrđivanja email adrese: igrač se prijavljuje svojim TTAR nalogom, pa manje ljudi odustaje od registracije na pola puta.
• Rejting igrača odmah. Zajedno sa autorizacijom dobijate i TTAR rejting: na osnovu njega lako je odrediti nosioce turnira, podeliti učesnike u grupe po jačini, pronaći sparing-partnera ili proveriti pravo nastupa na takmičenju.
• Ne morate da pravite sopstvenu autorizaciju. Čuvanje lozinki, vraćanje pristupa, prijava putem Google-a i Telegram-a — sve to već radi u TTAR-u. Vašim programerima dovoljno je da povežu standardni protokol OpenID Connect, a za njega postoje gotove biblioteke za sve popularne programske jezike.
• Bezbedno za igrače. TTAR lozinku nikada ne dobijate: igrač je unosi samo na stranici TTAR-a. Vama se prosleđuju samo podaci koje ste zatražili — ID igrača, ime i avatar, email i rejting.

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

Parametri servera za autorizaciju

Većini OIDC biblioteka dovoljno je navesti Issuer: ostale adrese pročitać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 dobija client_id. Client secret se ne koristi — podržan je samo PKCE (code_challenge_method=S256). Da biste se registrovali, pišite nam na kot@ttar.app.

Prilikom registracije navodite jedan ili više redirect_uri — to su adrese u vašoj aplikaciji na koje ćemo preusmeravati korisnika posle autorizacije. Mi ih dodajemo na belu listu. U svakom zahtevu navodite konkretnu adresu, a server je upoređuje sa tom listom.

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

Prijava: Authorization Code + PKCE

Korak 1. Pošaljite korisnika na autorizaciju. Sastavite link i otvorite ga u pregledaču korisnika navigacijom cele stranice, a ne u iframe-u:

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 pregledaču još nije prijavljen na TTAR, otvara mu se stranica za prijavu na 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. Opcioni parametri prompt i max_age opisani su u odeljku „Ponovna prijava i promena naloga“ u nastavku.

Korak 2. Primite odgovor na redirect_uri. Posle uspešne prijave pregledač korisnika se automatski preusmerava na vaš redirect_uri sa dva parametra:

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

• code — jednokratni autorizacioni kod. Važi oko 60 sekundi, zato ga odmah iskoristite.
• state — ista vrednost koju ste poslali u koraku 1. Obavezno je uporedite sa vrednošću koju ste sačuvali kod sebe: to je zaštita od CSRF-a.

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

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

Korak 3. Zamenite kod za tokene. Na serveru, a ne u pregledaču, pošaljite POST sa 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 sa osnovnim podacima o korisniku: sub, ime, email itd. Obavezno proverite potpis.
• refresh_token — za dobijanje novih tokena bez ponovne prijave. Izdaje se samo ako je zatražen scope offline_access.

Korak 4. Osvež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 se pojavljuje claim ttar_rating. To je JSON niz sa po jednim objektom za svaku ruku — glavnu i neglavnu:

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

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

Ponovna prijava i promena naloga

TTAR u pregledaču korisnika održava single sign-on (SSO) sesiju — cookie na domenu TTAR API-ja. Dok je ona aktivna, /connect/authorize izdaje kod za istog TTAR korisnika bez prikazivanja stranice za prijavu. Ova sesija ne zavisi od sesije vaše aplikacije: odjava korisnika iz vaše aplikacije ne završava je.

• prompt=login — uvek prikazuje stranicu za prijavu na TTAR i zahteva ponovnu prijavu, čak i kada postoji aktivna sesija: postojeća TTAR sesija se ne koristi ponovo. Korisnik može da se prijavi drugim TTAR nalogom. Preporučuje se za povezivanje naloga.
• prompt=select_account — isto što i prompt=login. TTAR nema izbor naloga: korisnik bira nalog tako što se njime prijavi.
• prompt=none — nikada ne prikazuje interfejs. Ako aktivna sesija ne postoji ili je starija od max_age, korisnik se vraća na vaš redirect_uri sa error=login_required.
• prompt=consent — prihvata se, ali ni na šta ne utiče: registrovani partneri su unapred odobreni, a ekrana za saglasnost u TTAR-u nema.
• max_age=N — ako se korisnik prijavio pre više od N sekundi, moraće ponovo da se prijavi. max_age=0 je isto što i prompt=login.

Neispravan prompt (nepoznata vrednost ili none zajedno sa nekom drugom vrednošću) TTAR odbija sa HTTP 400 — pregledač se ne vraća na vaš redirect_uri.

Claim auth_time. Token id_token sadrži auth_time — Unix vreme u sekundama poslednje interaktivne prijave korisnika na TTAR: emailom i lozinkom, putem Google-a ili Telegram-a. Pri osvežavanju tokena ne menja se. Može da nedostaje samo kod TTAR sesija započetih pre uvođenja ove funkcije. Takva sesija nikada ne zadovoljava ni prompt=login ni max_age i uvek se uspostavlja iznova, pa uz bilo koji od ovih parametara id_token obavezno sadrži auth_time.

Povezivanje TTAR naloga:

1. Dodajte prompt=login u zahtev za autorizaciju i zapamtite trenutak kada ste ga započeli.
2. Posle zamene koda proverite 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 zahteva, a da nije ponovo iskorišćena postojeća sesija.
3. Povezujte prema sub — ID-ju igrača u TTAR-u.

Da bi korisnik mogao da poveže drugi TTAR nalog, 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 pregledaču (na primer, „odjavi se svuda“ ili zajednički računar), pošaljite pregledač korisnika na end-session endpoint /connect/logout navigacijom cele stranice. XHR i iframe neće raditi: cookie sesije pripada domenu 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 cookie sesije i preusmerava pregledač na post_logout_redirect_uri, dodajući mu state.
• post_logout_redirect_uri mora biti unapred registrovan. Poklapanje mora biti tačno, a to je posebna lista, ne redirect_uri (pogledajte „Registracija klijenta“). Ako adresa nije registrovana, TTAR odbija ceo zahtev sa 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 izdat za vaš client_id. Prihvata se i onaj koji je istekao.
• Odjava završava korisnikovu TTAR sesiju u ovom pregledaču za sve servise na kojima je omogućena „Prijava putem TTAR-a“, a ne samo za vaš.

Provera 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. Proverite:

• 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.
• Nalog za testiranje obezbeđujemo posebno.
• Posle prelaska na produkciju client_id ostaje isti, menja se samo Issuer, koji postaje https://api.ttar.app.