Connexion avec TTAR

Si vous avez un site ou une application pour les amateurs de tennis de table (club, tournois, entraînements, boutique de matériel), connectez « Connexion via TTAR ». Les joueurs pourront s'authentifier chez vous avec leur compte TTAR en un clic, comme avec Google ou Telegram, sans nouvel identifiant ni mot de passe. Et vous saurez tout de suite qui vient chez vous et quel est son niveau de jeu.

Ce que cela apporte à votre service :

• Plus d'inscriptions. Pas besoin de remplir un formulaire ni de confirmer un e-mail : le joueur se connecte avec son identifiant TTAR, si bien que moins de gens abandonnent l'inscription en cours de route.
• Le rating du joueur tout de suite. Avec l'authentification, vous obtenez le rating TTAR : il permet de classer facilement les têtes de série d'un tournoi, de répartir les participants en poules par niveau, de trouver un partenaire d'entraînement ou de vérifier l'admission à une compétition.
• Pas besoin de votre propre authentification. Stockage des mots de passe, récupération d'accès, connexion via Google et Telegram : tout cela fonctionne déjà dans TTAR. Les développeurs n'ont qu'à brancher le protocole standard OpenID Connect, pour lequel il existe des bibliothèques toutes prêtes dans tous les langages de programmation courants.
• Sûr pour les joueurs. Vous ne recevez jamais le mot de passe TTAR : le joueur ne le saisit que sur la page de TTAR. Vous ne recevez que les données que vous avez demandées : ID du joueur, nom et avatar, e-mail et rating.

Ci-dessous, la description technique. Vous pouvez transmettre cette page directement aux développeurs.

Paramètres du serveur d'autorisation

Pour la plupart des bibliothèques OIDC, il suffit d'indiquer l'Issuer : elles liront les autres adresses dans le document de découverte (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

Enregistrement du client

Chaque partenaire reçoit un client_id. Le secret n'est pas utilisé : seul PKCE est pris en charge (code_challenge_method=S256). Pour vous enregistrer, écrivez-nous à kot@ttar.app.

Lors de l'enregistrement, vous nous communiquez un ou plusieurs redirect_uri, c'est-à-dire des adresses de votre application vers lesquelles nous redirigerons l'utilisateur après l'authentification. Nous les ajoutons à la liste blanche. Dans chaque requête, vous indiquez une adresse précise, et le serveur la compare à cette liste.

Vous pouvez en plus communiquer un ou plusieurs post_logout_redirect_uri, c'est-à-dire l'adresse où ramener l'utilisateur après la déconnexion via notre end-session endpoint /connect/logout (voir la section « Déconnexion » ci-dessous). C'est une liste blanche distincte : un redirect_uri n'est pas accepté comme adresse de retour après la déconnexion. Elle n'est nécessaire que si vous utilisez cette déconnexion.

Connexion : Authorization Code + PKCE

Étape 1. Envoyez l'utilisateur s'authentifier. Construisez le lien et ouvrez-le dans le navigateur de l'utilisateur par une navigation complète, pas dans 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

Si l'utilisateur n'est pas encore connecté à TTAR dans ce navigateur, il arrive sur la page de connexion de TTAR et s'y connecte. Si une session TTAR active existe déjà, la page de connexion est ignorée et le code est délivré immédiatement (single sign-on), sauf si vous avez demandé une nouvelle connexion via prompt=login. Les paramètres facultatifs prompt et max_age sont décrits dans la section « Nouvelle connexion et changement de compte » ci-dessous.

Étape 2. Recevez la réponse sur redirect_uri. Après une connexion réussie, le navigateur de l'utilisateur est automatiquement redirigé vers votre redirect_uri avec deux paramètres :

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

• code : code d'autorisation à usage unique. Il est valable environ 60 secondes, utilisez-le immédiatement.
• state : la même valeur que celle transmise à l'étape 1. Comparez-la impérativement à celle que vous avez conservée : c'est une protection contre le CSRF.

Si l'utilisateur a refusé ou si une erreur s'est produite, vous recevrez :

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

Étape 3. Échangez le code contre des tokens. Sur le serveur, pas dans le navigateur, envoyez un POST avec le code de l'étape 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

Réponse :

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

• access_token : token Bearer pour appeler l'API, y compris /connect/userinfo. C'est un JWT signé en RS256.
• id_token : JWT contenant les informations de base sur l'utilisateur : sub, nom, e-mail, etc. Vérifiez impérativement la signature.
• refresh_token : permet d'obtenir de nouveaux tokens sans nouvelle connexion. Il n'est délivré que si le scope offline_access a été demandé.

Étape 4. Renouvelez les tokens. Lorsque l'access token expire, obtenez de nouveaux tokens à l'aide du 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

Claim ttar_rating

Si le scope ttar:rating est demandé et que le joueur a un rating, l'access token contient le claim ttar_rating. C'est un tableau JSON, avec un objet par main, principale et faible :

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

Les autres données (nom, avatar, e-mail) sont disponibles via le UserInfo endpoint /connect/userinfo ou dans l'id_token.

Nouvelle connexion et changement de compte

TTAR conserve dans le navigateur de l'utilisateur une session single sign-on (SSO), un cookie sur le domaine de l'API TTAR. Tant qu'elle est active, /connect/authorize délivre un code pour le même utilisateur TTAR sans afficher la page de connexion. Cette session est indépendante de la session de votre application : la déconnexion de l'utilisateur de votre application ne la termine pas.

• prompt=login : affiche toujours la page de connexion de TTAR et exige de se reconnecter, même si une session est active ; la session TTAR existante n'est pas réutilisée. L'utilisateur peut se connecter avec un autre compte TTAR. Recommandé pour le rattachement d'un compte.
• prompt=select_account : identique à prompt=login. TTAR n'a pas de sélecteur de compte : l'utilisateur choisit un compte en s'y connectant.
• prompt=none : n'affiche jamais d'interface. S'il n'y a pas de session active ou si elle est plus ancienne que max_age, l'utilisateur est renvoyé vers votre redirect_uri avec error=login_required.
• prompt=consent : accepté mais sans aucun effet : les partenaires enregistrés sont approuvés à l'avance, il n'y a pas d'écran de consentement dans TTAR.
• max_age=N : si l'utilisateur s'est connecté il y a plus de N secondes, il devra se reconnecter. max_age=0 équivaut à prompt=login.

Un prompt incorrect (valeur inconnue, ou none combiné à une autre valeur) est rejeté par TTAR avec un HTTP 400 : le navigateur n'est pas renvoyé vers votre redirect_uri.

Claim auth_time. L'id_token contient auth_time : l'heure Unix, en secondes, de la dernière connexion interactive de l'utilisateur à TTAR : par e-mail et mot de passe, via Google ou Telegram. Il ne change pas lors du renouvellement des tokens. Il ne peut être absent que pour les sessions TTAR ouvertes avant l'apparition de cette fonctionnalité. Une telle session ne satisfait jamais prompt=login ni max_age et est toujours rétablie, c'est pourquoi, avec l'un de ces paramètres, l'id_token contient obligatoirement auth_time.

Rattachement d'un compte TTAR :

1. Ajoutez prompt=login à la requête d'autorisation et notez le moment où vous l'avez démarrée.
2. Après l'échange du code, vérifiez que auth_time n'est pas antérieur à ce moment, avec une marge de quelques secondes pour le décalage des horloges. Vous vous assurez ainsi que l'utilisateur s'est bien connecté dans le cadre de cette requête, et non qu'une session existante a été réutilisée.
3. Rattachez par sub, l'ID du joueur dans TTAR.

Pour que l'utilisateur puisse rattacher un autre compte TTAR, nul besoin de déconnexion : prompt=login suffit.

Déconnexion

La déconnexion de l'utilisateur de votre application ne termine pas sa session TTAR. Si vous devez aussi la terminer dans ce navigateur (par exemple « se déconnecter partout » ou ordinateur partagé), envoyez le navigateur de l'utilisateur vers l'end-session endpoint /connect/logout par une navigation complète de la page. XHR et iframe ne conviennent pas : le cookie de session appartient au domaine de 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 supprime son cookie de session et redirige le navigateur vers post_logout_redirect_uri, en lui ajoutant state.
• post_logout_redirect_uri doit être enregistré à l'avance. La correspondance est exacte, et c'est une liste distincte de celle de redirect_uri (voir « Enregistrement du client »). Avec une adresse non enregistrée, TTAR rejette toute la requête avec un HTTP 400 : et la session n'est pas terminée.
• Sans post_logout_redirect_uri, la session est terminée, mais l'utilisateur ne revient pas dans votre application.
• id_token_hint est facultatif. Si vous le transmettez, ce doit être l'id_token délivré à votre client_id. Un token expiré convient aussi.
• La déconnexion termine la session TTAR de l'utilisateur dans ce navigateur pour tous les services où « Connexion via TTAR » est branchée, et pas seulement pour le vôtre.

Vérification des tokens

Les tokens sont signés en RS256. Les clés publiques se trouvent à l'adresse JWKS standard :

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

Toute bibliothèque OIDC standard les récupérera automatiquement via le discovery endpoint. Vérifiez :

• la signature : alg=RS256, clé issue de JWKS ;
• iss = https://stage.api.ttar.app ;
• aud = votre client_id ;
• exp : le token n'a pas expiré ;
• auth_time, si vous utilisez prompt=login ou max_age (voir « Claim auth_time » ci-dessus).

À savoir pour staging

• Staging est un environnement de test, pour vos expérimentations.
• Un compte de test est fourni séparément.
• Après le passage en production, le client_id restera le même, seul l'Issuer changera : https://api.ttar.app.