Web

Login com o TTAR

Autorização com a conta TTAR no seu site ou aplicativo: os jogadores entram com um clique, e você vê o rating deles na hora.

Se você tem um site ou aplicativo para os fãs de tênis de mesa — um clube, torneios, treinos, uma loja de equipamentos —, adicione o «Login com o TTAR». Os jogadores poderão entrar no seu serviço com a conta TTAR em um clique, assim como fazem com o Google ou o Telegram, sem precisar criar mais um usuário e senha. E você descobre na hora quem chegou e qual é o nível de jogo de cada um.

O que o seu serviço ganha com isso:

Mais cadastros. Nada de preencher formulário nem confirmar e-mail: o jogador entra com o login do TTAR, então menos gente desiste do cadastro no meio do caminho.
O rating do jogador na hora. Junto com a autorização, você recebe o rating TTAR: com ele fica fácil definir os cabeças de chave de um torneio, dividir os participantes em grupos por nível, encontrar um parceiro de treino ou verificar se o jogador pode disputar uma competição.
Sem precisar de um sistema de autorização próprio. Armazenamento de senhas, recuperação de acesso, login com o Google e o Telegram — tudo isso já funciona no TTAR. Aos desenvolvedores basta integrar o protocolo padrão OpenID Connect, que já tem bibliotecas prontas para todas as linguagens de programação populares.
Seguro para os jogadores. Você nunca recebe a senha do TTAR: o jogador a digita apenas na página do TTAR. Você recebe só os dados que solicitou — o ID do jogador, nome e avatar, e-mail e rating.

Como se conectar

Tornar-se parceiro é simples e gratuito: mande um e-mail para kot@ttar.app contando sobre o seu serviço, e nós enviaremos tudo o que você precisa para se conectar. Seus jogadores não verão a tela «Permitir acesso?»: somos nós que conectamos cada parceiro, então todos já vêm pré-aprovados.

A seguir, a descrição técnica. Você pode encaminhar esta página diretamente aos desenvolvedores.

Parâmetros do servidor de autorização

Para a maioria das bibliotecas OIDC, basta informar o Issuer: os demais endereços elas obtêm do 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 do cliente

Cada parceiro recebe um client_id. O client secret não é usado — só há suporte a PKCE (code_challenge_method=S256). Para se registrar, envie um e-mail para kot@ttar.app.

No registro, você informa um ou mais redirect_uri — endereços na sua aplicação para onde enviaremos o usuário após a autorização. Nós os incluímos em uma lista de permissões. Em cada requisição, você indica o endereço específico, e o servidor o confere com essa lista.

Opcionalmente, você também pode informar um ou mais post_logout_redirect_uri — para onde devolver o usuário após o logout pelo nosso end-session endpoint /connect/logout (veja a seção «Logout» abaixo). É uma lista de permissões separada: um redirect_uri não é aceito como endereço de retorno após o logout. Ela só é necessária se você usar esse logout.

Login: Authorization Code + PKCE

Passo 1. Envie o usuário para a autorização. Monte o link e abra-o no navegador do usuário com uma navegação de página inteira, não em um 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 o usuário ainda não entrou no TTAR neste navegador, ele é levado à página de login do TTAR e entra. Se já houver uma sessão ativa do TTAR, a página de login é pulada e o código é emitido na hora (single sign-on) — a menos que você tenha pedido um novo login com prompt=login. Os parâmetros opcionais prompt e max_age estão descritos na seção «Novo login e troca de conta» abaixo.

Passo 2. Receba a resposta no redirect_uri. Após o login bem-sucedido, o navegador do usuário é redirecionado automaticamente para o seu redirect_uri com dois parâmetros:

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

code — código de autorização de uso único. Ele vale por cerca de 60 segundos, então use-o imediatamente.
state — o mesmo valor que você enviou no passo 1. Confira-o sempre com o valor que você guardou: isso protege contra CSRF.

Se o usuário recusar ou ocorrer um erro, você receberá:

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

Passo 3. Troque o código por tokens. No servidor, não no navegador, envie um POST com o código do 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

Aqui, o redirect_uri deve ser o mesmo enviado no passo 1: o servidor o usa como verificação adicional.

Resposta:

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

access_token — Bearer token para chamadas à API, incluindo /connect/userinfo. É um JWT assinado com RS256.
id_token — JWT com as informações básicas do usuário: sub, nome, e-mail etc. Sempre verifique a assinatura.
refresh_token — para obter novos tokens sem que o usuário precise fazer login de novo. É emitido somente se o scope offline_access for solicitado.

Passo 4. Renove os tokens. Quando o access token expirar, obtenha novos tokens usando o 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	O que retorna
`openid`	`sub` (ID do jogador no TTAR). Obrigatório.
`profile`	`name`, `picture` (URL do avatar)
`email`	`email`, `email_verified`
`offline_access`	Adiciona o `refresh_token` à resposta do token endpoint `/connect/token`. Sem esse scope, o refresh token não é emitido.
`ttar:rating`	Claim `ttar_rating` no access token — array com os ratings do jogador (veja abaixo).

Claim ttar_rating

Se o scope ttar:rating for solicitado e o jogador tiver rating, a claim ttar_rating aparece no access token. É um array JSON com um objeto para cada mão — a principal e a não principal:

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

Os demais dados (nome, avatar, e-mail) estão disponíveis pelo UserInfo endpoint /connect/userinfo ou no id_token.

Novo login e troca de conta

O TTAR mantém no navegador do usuário uma sessão de single sign-on (SSO) — um cookie no domínio da API do TTAR. Enquanto ela estiver ativa, o /connect/authorize emite um código para o mesmo usuário do TTAR sem mostrar a página de login. Essa sessão é independente da sessão da sua aplicação: o logout do usuário na sua aplicação não a encerra.

prompt=login — sempre mostra a página de login do TTAR e exige um novo login, mesmo com uma sessão ativa: a sessão existente do TTAR não é reutilizada. O usuário pode entrar com outra conta TTAR. Recomendado para vincular contas.
prompt=select_account — o mesmo que prompt=login. O TTAR não tem seletor de contas: o usuário escolhe a conta ao entrar nela.
prompt=none — nunca mostra nenhuma interface. Se não houver sessão ativa ou se ela for mais antiga que max_age, o usuário volta para o seu redirect_uri com error=login_required.
prompt=consent — é aceito, mas não tem efeito: os parceiros registrados já são pré-aprovados e o TTAR não tem tela de consentimento.
max_age=N — se o último login do usuário foi há mais de N segundos, ele terá que entrar novamente. max_age=0 equivale a prompt=login.

Um prompt inválido (valor desconhecido ou none combinado com outro valor) é rejeitado pelo TTAR com HTTP 400 — o navegador não volta para o seu redirect_uri.

Claim auth_time. O id_token contém auth_time — o timestamp Unix, em segundos, do último login interativo do usuário no TTAR: com e-mail e senha, pelo Google ou pelo Telegram. Esse valor não muda quando os tokens são renovados. Ele só pode faltar em sessões do TTAR iniciadas antes de esse recurso existir. Uma sessão assim nunca satisfaz prompt=login nem max_age e é sempre restabelecida; por isso, com qualquer um desses parâmetros, o id_token sempre contém auth_time.

Vinculação da conta TTAR:

Adicione prompt=login à requisição de autorização e guarde o momento em que você a iniciou.
Depois de trocar o código, verifique se o auth_time não é anterior a esse momento, com uma margem de alguns segundos para a diferença entre relógios. Assim você garante que o usuário realmente fez login dentro dessa requisição, e não que uma sessão existente foi reutilizada.
Faça a vinculação pelo sub — o ID do jogador no TTAR.

Observação

No login com o Google, o próprio Google pode não pedir a senha se o usuário já estiver conectado ao Google neste navegador. Para o TTAR, isso continua sendo um novo login interativo, e o auth_time reflete isso.

Para que o usuário possa vincular outra conta TTAR, não é preciso fazer logout — basta prompt=login.

Logout

O logout do usuário na sua aplicação não encerra a sessão dele no TTAR. Se você também precisar encerrá-la neste navegador (por exemplo, «sair de todos os lugares» ou um computador compartilhado), envie o navegador do usuário para o end-session endpoint /connect/logout com uma navegação de página inteira. XHR e iframe não funcionam: o cookie de sessão pertence ao domínio do 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

O TTAR apaga o seu cookie de sessão e redireciona o navegador para o post_logout_redirect_uri, acrescentando o state.
O post_logout_redirect_uri precisa ser registrado com antecedência. A correspondência é exata, e essa é uma lista separada da de redirect_uri (veja «Registro do cliente»). Com um endereço não registrado, o TTAR rejeita a requisição inteira com HTTP 400 — e a sessão não é encerrada.
Sem post_logout_redirect_uri, a sessão é encerrada, mas o usuário não volta para a sua aplicação.
O id_token_hint é opcional. Se você enviá-lo, ele deve ser um id_token emitido para o seu client_id. Um token expirado também serve.
O logout encerra a sessão TTAR do usuário neste navegador em todos os serviços que usam o «Login com o TTAR», não só no seu.

Validação de tokens

Os tokens são assinados com RS256. As chaves públicas ficam no endereço JWKS padrão:

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

Qualquer biblioteca OIDC padrão as obtém automaticamente pelo discovery endpoint. Verifique:

a assinatura: alg=RS256, chave do JWKS;
iss = https://stage.api.ttar.app;
aud = o seu client_id;
exp: o token não expirou;
auth_time, se você usa prompt=login ou max_age (veja «Claim auth_time» acima).

Importante sobre o staging

O staging é um ambiente de testes para os seus experimentos.
A conta de teste é fornecida separadamente.
Na passagem para produção, o client_id continua o mesmo; muda apenas o Issuer, que passa a ser https://api.ttar.app.