Guia de integração
Adicione «Entrar com Tutu» ao seu produto em quatro passos, com OAuth2 + PKCE.
Quatro passos para integrar
O frontend inicia o login
Crie uma instância com createTutuId({ baseUrl, clientId }) do @tutu/id-sdk e chame idSdk.startLogin() no clique. O SDK gera um par PKCE e redireciona para a página de autorização do TutuId.
O usuário autoriza no TutuId
Na tela de consentimento /oauth/authorize o usuário clica em «Permitir» (pulado se já autorizou). Após validar client_id e a lista de permissões de redirect_uri, o TutuId retorna ao seu /auth/callback com um código de autorização.
A página de callback obtém o code
Em /auth/callback, chame idSdk.completeCallback() para obter { code, codeVerifier }. Entregue esses dois valores ao seu backend; nunca troque o token direto no navegador.
O backend troca o token → cria a conta
Seu backend troca code + codeVerifier por um access_token, chama /userinfo para obter { sub, email, emailVerified, ... }, mapeia ou cria uma conta local por sub e então emite sua própria sessão.
★ Defesa contra tomada de conta (obrigatório)
Seu backend só pode vincular ou criar uma conta local por sub (o ID único da conta). Somente quando emailVerified === true você pode vincular uma conta local existente por e-mail; caso contrário, crie uma conta separada e deixe o e-mail vazio.
Por quê: um atacante poderia pré-registrar uma conta Tutu com o e-mail da vítima; mesclar por e-mail não verificado entregaria a conta local da vítima. É uma linha vermelha de nível CVE.
Referência da API do SDK
@tutu/id-sdk · puramente no cliente, sem dependências (requer Web Crypto + sessionStorage).
createTutuId({ baseUrl, clientId, redirectUri? }) Cria uma instância do SDK. redirectUri padrão é ${location.origin}/auth/callback, adaptando-se a dev/prod.
startLogin(scope?) Gera um par PKCE e redireciona à página de autorização, iniciando «Entrar com Tutu».
trySilentLogin(scope?) Login silencioso: havendo sessão central e autorização prévia, troca um código sem fricção; caso contrário, volta ao estado deslogado na hora (sem interromper o usuário).
completeCallback() Analisa o resultado na página de callback: em sucesso retorna { code, codeVerifier }, em falha/cancelamento retorna { error }.
logoutEverywhere(returnTo?) Encerra a sessão central, propagando o logout a todos os produtos da suíte, e depois volta a returnTo.
Quer ver funcionando primeiro?