Web

Accedi con TTAR

Autenticazione con un account TTAR sul tuo sito o nella tua app: i giocatori accedono con un clic e tu vedi subito il loro rating.

Se hai un sito o un'app per gli appassionati di tennistavolo (un club, tornei, allenamenti, un negozio di attrezzatura), collega «Accedi con TTAR». I giocatori potranno accedere da te con il proprio account TTAR in un clic, come con Google o Telegram, senza nuovo login né nuova password. E tu scoprirai subito chi è arrivato e quanto è forte.

Cosa ottiene il tuo servizio:

Più registrazioni. Non serve compilare moduli né confermare l'e-mail: il giocatore entra con il suo login TTAR, quindi meno persone abbandonano la registrazione a metà.
Il rating del giocatore subito. Insieme all'accesso ricevi il rating TTAR: è comodo per fare il sorteggio di un torneo, dividere i partecipanti in gironi per livello, trovare un compagno di allenamento o verificare l'ammissione a una competizione.
Non serve un'autenticazione tua. Archiviazione delle password, recupero dell'accesso, accesso con Google e Telegram: tutto questo funziona già in TTAR. Agli sviluppatori basta collegare il protocollo standard OpenID Connect, per il quale esistono librerie pronte per tutti i linguaggi di programmazione più diffusi.
Sicuro per i giocatori. Non ricevi mai la password di TTAR: il giocatore la inserisce solo sulla pagina di TTAR. Ti vengono trasmessi solo i dati che hai richiesto: ID del giocatore, nome e avatar, e-mail e rating.

Come collegarsi

Diventare partner è semplice e gratuito: scrivici a kot@ttar.app e racconta del tuo servizio: ti forniremo tutto il necessario per il collegamento. I tuoi giocatori non vedranno la schermata «Consentire l'accesso?»: i partner li colleghiamo noi, quindi sono approvati in anticipo.

Di seguito c'è la descrizione tecnica. Questa pagina può essere passata subito agli sviluppatori.

Parametri del server di autorizzazione

Alla maggior parte delle librerie OIDC basta indicare l'Issuer: gli altri indirizzi li leggono dal documento di 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

Registrazione del client

A ogni partner viene assegnato un client_id. Il secret non viene usato: è supportato solo PKCE (code_challenge_method=S256). Per registrarti, scrivici a kot@ttar.app.

Al momento della registrazione comunichi uno o più redirect_uri, cioè indirizzi della tua applicazione a cui rimanderemo l'utente dopo l'autorizzazione. Li inseriamo in una lista bianca. In ogni richiesta indichi un indirizzo preciso e il server lo confronta con questa lista.

In aggiunta puoi comunicare uno o più post_logout_redirect_uri, cioè dove riportare l'utente dopo l'uscita tramite il nostro end-session endpoint /connect/logout (vedi la sezione «Uscita» più sotto). È una lista bianca separata: redirect_uri non è accettato come indirizzo di ritorno dopo l'uscita. Serve solo se usi questa uscita.

Accesso: Authorization Code + PKCE

Passo 1. Manda l'utente all'autorizzazione. Costruisci il link e aprilo nel browser dell'utente con una navigazione completa, non in un 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

Se l'utente non ha ancora effettuato l'accesso a TTAR in questo browser, arriva alla pagina di accesso di TTAR e accede. Se esiste già una sessione TTAR attiva, la pagina di accesso viene saltata e il codice viene rilasciato subito (single sign-on), a meno che tu non abbia richiesto un nuovo accesso con prompt=login. I parametri facoltativi prompt e max_age sono descritti nella sezione «Nuovo accesso e cambio di account» più sotto.

Passo 2. Ricevi la risposta su redirect_uri. Dopo l'accesso riuscito, il browser dell'utente viene reindirizzato automaticamente al tuo redirect_uri con due parametri:

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

code: codice di autorizzazione monouso. Dura circa 60 secondi, usalo subito.
state: lo stesso valore che hai passato nel passo 1. Confrontalo assolutamente con quello che hai salvato: è una protezione da CSRF.

Se l'utente ha rifiutato o si è verificato un errore, arriverà:

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

Passo 3. Scambia il codice con i token. Sul server, non nel browser, invia una POST con il codice del passo 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

Importante

redirect_uri qui deve coincidere con quello passato nel passo 1: il server lo usa come ulteriore controllo.

Risposta:

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

access_token: token Bearer per accedere all'API, incluso /connect/userinfo. È un JWT firmato con RS256.
id_token: JWT con le informazioni di base sull'utente: sub, nome, e-mail e così via. Verifica sempre la firma.
refresh_token: serve a ottenere nuovi token senza un nuovo accesso. Viene rilasciato solo se è richiesto lo scope offline_access.

Passo 4. Aggiorna i token. Quando l'access token scade, ottieni nuovi token con il refresh token:

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

Scope	Cosa restituisce
`openid`	`sub` (ID del giocatore in TTAR). Obbligatorio.
`profile`	`name`, `picture` (URL dell'avatar)
`email`	`email`, `email_verified`
`offline_access`	Aggiunge `refresh_token` alla risposta del token endpoint `/connect/token`. Senza questo scope il refresh token non viene rilasciato.
`ttar:rating`	Claim `ttar_rating` nell'access token: un array dei rating del giocatore (vedi sotto).

Claim ttar_rating

Se è richiesto lo scope ttar:rating e il giocatore ha un rating, nell'access token compare il claim ttar_rating. È un array JSON, con un oggetto per ciascuna mano: principale e secondaria:

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

Gli altri dati (nome, avatar, e-mail) sono disponibili tramite lo UserInfo endpoint /connect/userinfo o nell'id_token.

Nuovo accesso e cambio di account

TTAR mantiene nel browser dell'utente una sessione single sign-on (SSO): un cookie sul dominio dell'API di TTAR. Finché è attiva, /connect/authorize rilascia il codice per lo stesso utente TTAR senza mostrare la pagina di accesso. Questa sessione non dipende dalla sessione della tua applicazione: l'uscita dell'utente dalla tua applicazione non la termina.

prompt=login: mostra sempre la pagina di accesso di TTAR e richiede di accedere di nuovo, anche con una sessione attiva: la sessione TTAR esistente non viene riutilizzata. L'utente può accedere con un altro account TTAR. Consigliato per il collegamento dell'account.
prompt=select_account: equivale a prompt=login. In TTAR non c'è una scelta dell'account: l'utente sceglie l'account effettuando l'accesso.
prompt=none: non mostra mai l'interfaccia. Se non c'è una sessione attiva o è più vecchia di max_age, l'utente torna al tuo redirect_uri con error=login_required.
prompt=consent: viene accettato e non ha alcun effetto: i partner registrati sono approvati in anticipo, in TTAR non esiste la schermata di consenso.
max_age=N: se l'utente ha effettuato l'accesso più di N secondi fa, dovrà accedere di nuovo. max_age=0 equivale a prompt=login.

Un prompt non valido (valore sconosciuto o none insieme a un altro valore) viene rifiutato da TTAR con HTTP 400: il browser non torna al tuo redirect_uri.

Claim auth_time. Nell'id_token c'è auth_time: il tempo Unix in secondi dell'ultimo accesso interattivo dell'utente a TTAR, con e-mail e password, tramite Google o Telegram. Non cambia quando i token vengono aggiornati. Può mancare solo nelle sessioni TTAR iniziate prima dell'introduzione di questa funzione. Una sessione simile non soddisfa mai prompt=login e max_age e viene sempre stabilita da capo, perciò con uno qualsiasi di questi parametri l'id_token contiene sempre auth_time.

Collegamento dell'account TTAR:

Aggiungi prompt=login alla richiesta di autorizzazione e annota il momento in cui l'hai avviata.
Dopo lo scambio del codice, verifica che auth_time non sia anteriore a quel momento, con un margine di qualche secondo per lo scarto degli orologi. In questo modo ti assicuri che l'utente abbia davvero effettuato l'accesso nell'ambito di questa richiesta e che non sia stata riutilizzata una sessione esistente.
Collega usando sub, l'ID del giocatore in TTAR.

Nota

Con l'accesso tramite Google, Google stesso può non chiedere la password se l'utente ha già effettuato l'accesso a Google in questo browser. Per TTAR resta comunque un accesso interattivo recente, e auth_time lo riflette.

Perché l'utente possa collegare un altro account TTAR non serve uscire: basta prompt=login.

Uscita

L'uscita dell'utente dalla tua applicazione non termina la sua sessione TTAR. Se serve terminare anche quella in questo browser (per esempio «esci ovunque» o un computer condiviso), manda il browser dell'utente all'end-session endpoint /connect/logout con una navigazione completa della pagina. XHR e iframe non vanno bene: il cookie di sessione appartiene al dominio di 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 elimina il proprio cookie di sessione e reindirizza il browser a post_logout_redirect_uri, aggiungendo state.
post_logout_redirect_uri deve essere registrato in anticipo. La corrispondenza è esatta, ed è una lista separata, non redirect_uri (vedi «Registrazione del client»). Con un indirizzo non registrato TTAR rifiuta l'intera richiesta con HTTP 400, e la sessione non viene terminata.
Senza post_logout_redirect_uri la sessione viene terminata, ma l'utente non torna nella tua applicazione.
id_token_hint è facoltativo. Se lo passi, deve essere l'id_token rilasciato al tuo client_id. Va bene anche uno scaduto.
L'uscita termina la sessione TTAR dell'utente in questo browser per tutti i servizi che hanno «Accedi con TTAR», non solo per il tuo.

Verifica dei token

I token sono firmati con RS256. Le chiavi pubbliche si trovano all'indirizzo JWKS standard:

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

Qualsiasi libreria OIDC standard le preleva automaticamente tramite il discovery endpoint. Verifica:

la firma: alg=RS256, chiave da JWKS;
iss = https://stage.api.ttar.app;
aud = il tuo client_id;
exp: il token non è scaduto;
auth_time, se usi prompt=login o max_age (vedi «Claim auth_time» sopra).

Importante per lo staging

Lo staging è un ambiente di test, per i tuoi esperimenti.
L'account per i test viene fornito separatamente.
Dopo il passaggio alla produzione il client_id resterà lo stesso, cambierà solo l'Issuer, che diventerà https://api.ttar.app.