Web

Inicio de sesión con TTAR

Autorización con la cuenta de TTAR en tu sitio web o aplicación: los jugadores inician sesión en un clic y tú ves su rating al instante.

Si tienes un sitio web o una aplicación para aficionados al tenis de mesa (un club, torneos, entrenamientos, una tienda de material), añade el «Inicio de sesión con TTAR». Los jugadores podrán acceder a tu servicio con su cuenta de TTAR en un solo clic, como con Google o Telegram, sin tener que crear otro usuario y contraseña. Y tú sabrás al instante quién ha llegado y qué nivel de juego tiene.

Lo que aporta a tu servicio:

Más registros. Nada de rellenar formularios ni de confirmar el correo: el jugador inicia sesión con su cuenta de TTAR, así que menos gente abandona el registro a medias.
El rating del jugador, al instante. Junto con la autorización recibes su rating de TTAR: con él es fácil establecer los cabezas de serie de un torneo, repartir a los participantes en grupos por nivel, encontrar un compañero de entrenamiento o comprobar si alguien cumple los requisitos para participar en una competición.
No necesitas tu propio sistema de autorización. Almacenar contraseñas, recuperar el acceso, iniciar sesión con Google y Telegram: todo eso ya funciona en TTAR. A tus desarrolladores les basta con integrar el protocolo estándar OpenID Connect, que tiene bibliotecas listas para usar en todos los lenguajes de programación populares.
Seguro para los jugadores. Nunca recibes la contraseña de TTAR: el jugador solo la introduce en la página de TTAR. Solo te llegan los datos que has solicitado: el ID del jugador, su nombre y avatar, su correo electrónico y su rating.

Cómo conectarse

Hacerte partner es sencillo y gratuito: escríbenos a kot@ttar.app, háblanos de tu servicio y te daremos todo lo necesario para conectarte. Tus jugadores no verán ninguna pantalla de «¿Permitir el acceso?»: somos nosotros quienes conectamos a los partners, así que están aprobados de antemano.

A continuación tienes la descripción técnica. Puedes pasar esta página directamente a tus desarrolladores.

Parámetros del servidor de autorización

A la mayoría de las bibliotecas OIDC les basta con indicar el Issuer: el resto de las direcciones las leen del discovery document.

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

Registro del cliente

Cada partner recibe un client_id. El secreto de cliente no se usa: solo se admite PKCE (code_challenge_method=S256). Para registrarte, escríbenos a kot@ttar.app.

Al registrarte, nos indicas uno o varios redirect_uri: las direcciones de tu aplicación a las que enviaremos al usuario después de la autorización. Las añadimos a una lista blanca. En cada solicitud indicas una dirección concreta, y el servidor comprueba que esté en esa lista.

Además, puedes indicarnos uno o varios post_logout_redirect_uri: adónde devolver al usuario después de cerrar sesión a través de nuestro end-session endpoint /connect/logout (consulta la sección «Cierre de sesión» más abajo). Es una lista blanca aparte: un redirect_uri no se acepta como dirección de retorno tras el cierre de sesión. Solo la necesitas si usas este cierre de sesión.

Inicio de sesión: Authorization Code + PKCE

Paso 1. Redirige al usuario a la autorización. Genera el enlace y ábrelo en el navegador del usuario con una navegación de página completa, no en 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 el usuario todavía no ha iniciado sesión en TTAR en este navegador, ve la página de inicio de sesión de TTAR e inicia sesión. Si ya tiene una sesión activa de TTAR, la página de inicio de sesión se omite y el código se emite de inmediato (single sign-on), a menos que hayas pedido volver a iniciar sesión con prompt=login. Los parámetros opcionales prompt y max_age se describen más abajo, en la sección «Reautenticación y cambio de cuenta».

Paso 2. Recibe la respuesta en el redirect_uri. Tras un inicio de sesión correcto, el navegador del usuario se redirige automáticamente a tu redirect_uri con dos parámetros:

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

code — un código de autorización de un solo uso. Es válido durante unos 60 segundos, así que úsalo de inmediato.
state — el mismo valor que enviaste en el paso 1. Compáralo siempre con el que guardaste: es la protección contra CSRF.

Si el usuario deniega el acceso o se produce un error, recibirás:

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

Paso 3. Intercambia el código por tokens. En el servidor, no en el navegador, envía un POST con el código del paso 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

Aquí el redirect_uri debe coincidir con el que se envió en el paso 1: el servidor lo usa como comprobación adicional.

Respuesta:

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

access_token — un token Bearer para llamar a la API, incluido /connect/userinfo. Es un JWT firmado con RS256.
id_token — un JWT con la información básica del usuario: sub, nombre, correo electrónico, etc. Verifica siempre su firma.
refresh_token — para obtener tokens nuevos sin volver a iniciar sesión. Solo se emite si se solicitó el scope offline_access.

Paso 4. Renueva los tokens. Cuando caduque el access token, obtén tokens nuevos con el 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	Qué devuelve
`openid`	`sub` (el ID del jugador en TTAR). Obligatorio.
`profile`	`name`, `picture` (URL del avatar)
`email`	`email`, `email_verified`
`offline_access`	Añade `refresh_token` a la respuesta del token endpoint `/connect/token`. Sin este scope no se emite ningún refresh token.
`ttar:rating`	El claim `ttar_rating` en el access token: un array con los ratings del jugador (ver más abajo).

El claim ttar_rating

Si se solicita el scope ttar:rating y el jugador tiene rating, el access token incluye el claim ttar_rating. Es un array JSON con un objeto por cada mano (principal y no principal):

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

El resto de los datos (nombre, avatar, correo electrónico) están disponibles en el UserInfo endpoint /connect/userinfo o en el id_token.

Reautenticación y cambio de cuenta

TTAR mantiene en el navegador del usuario una sesión de single sign-on (SSO): una cookie en el dominio de la API de TTAR. Mientras está activa, /connect/authorize emite un código para el mismo usuario de TTAR sin mostrar la página de inicio de sesión. Esta sesión es independiente de la de tu aplicación: si el usuario cierra sesión en tu aplicación, la de TTAR no se cierra.

prompt=login — siempre muestra la página de inicio de sesión de TTAR y obliga a iniciar sesión de nuevo, incluso con una sesión activa: la sesión de TTAR existente no se reutiliza. El usuario puede iniciar sesión con otra cuenta de TTAR. Recomendado para vincular cuentas.
prompt=select_account — igual que prompt=login. TTAR no tiene selector de cuentas: el usuario elige la cuenta al iniciar sesión con ella.
prompt=none — nunca muestra ninguna interfaz. Si no hay una sesión activa o es más antigua que max_age, el usuario vuelve a tu redirect_uri con error=login_required.
prompt=consent — se acepta, pero no tiene ningún efecto: los partners registrados están aprobados de antemano y TTAR no tiene pantalla de consentimiento.
max_age=N — si el usuario inició sesión hace más de N segundos, tendrá que volver a iniciarla. max_age=0 equivale a prompt=login.

Si el prompt no es válido (un valor desconocido o none junto con otro valor), TTAR rechaza la solicitud con HTTP 400 y el navegador no vuelve a tu redirect_uri.

El claim auth_time. El id_token contiene auth_time: la marca de tiempo Unix, en segundos, del último inicio de sesión interactivo del usuario en TTAR, ya sea con correo electrónico y contraseña, con Google o con Telegram. No cambia al renovar los tokens. Solo puede faltar en sesiones de TTAR iniciadas antes de que existiera esta función. Una sesión así nunca satisface prompt=login ni max_age y siempre se vuelve a establecer, por lo que con cualquiera de estos parámetros el id_token contiene siempre auth_time.

Vincular una cuenta de TTAR:

Añade prompt=login a la solicitud de autorización y guarda el momento en que la iniciaste.
Después de intercambiar el código, comprueba que auth_time no sea anterior a ese momento, con un margen de unos segundos por posibles desfases de reloj. Así te aseguras de que el usuario ha iniciado sesión realmente durante esta solicitud y de que no se ha reutilizado una sesión existente.
Vincula la cuenta por su sub, el ID del jugador en TTAR.

Nota

Al iniciar sesión con Google, puede que el propio Google no pida la contraseña si el usuario ya ha iniciado sesión en Google en este navegador. Para TTAR sigue siendo un inicio de sesión interactivo nuevo, y auth_time lo refleja.

Para que el usuario pueda vincular otra cuenta de TTAR no hace falta cerrar sesión: basta con prompt=login.

Cierre de sesión

Cuando el usuario cierra sesión en tu aplicación, su sesión de TTAR no se cierra. Si también necesitas cerrarla en este navegador (por ejemplo, para «cerrar sesión en todas partes» o en un ordenador compartido), envía el navegador del usuario al end-session endpoint /connect/logout con una navegación de página completa. Un XHR o un iframe no sirven: la cookie de sesión pertenece al dominio 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 elimina su cookie de sesión y redirige el navegador a post_logout_redirect_uri, añadiéndole state.
El post_logout_redirect_uri debe estar registrado de antemano. La coincidencia debe ser exacta, y es una lista distinta de la de redirect_uri (ver «Registro del cliente»). Si la dirección no está registrada, TTAR rechaza toda la solicitud con HTTP 400 y la sesión no se cierra.
Sin post_logout_redirect_uri, la sesión se cierra, pero el usuario no vuelve a tu aplicación.
El id_token_hint es opcional. Si lo envías, debe ser un id_token emitido para tu client_id. También sirve uno caducado.
El cierre de sesión termina la sesión de TTAR del usuario en este navegador en todos los servicios que han integrado el «Inicio de sesión con TTAR», no solo en el tuyo.

Validación de tokens

Los tokens están firmados con RS256. Las claves públicas están en la dirección JWKS estándar:

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

Cualquier biblioteca OIDC estándar las obtendrá automáticamente a través del discovery endpoint. Comprueba:

la firma: alg=RS256, con la clave del JWKS;
iss = https://stage.api.ttar.app;
aud = tu client_id;
exp: el token no ha caducado;
auth_time, si usas prompt=login o max_age (ver «El claim auth_time» más arriba).

Importante sobre staging

Staging es un entorno de pruebas para tus experimentos.
La cuenta de prueba se proporciona por separado.
Al pasar a producción, el client_id seguirá siendo el mismo; solo cambiará el Issuer, que pasará a ser https://api.ttar.app.