INTASTELLAR SOLUTIONSHelp Center
Versionv1

O fluxo authorization code é o padrão usual quando o navegador sai do seu site, o usuário entra na Intastellar e a Intastellar o devolve ao seu site com um código de uso único que você troca por tokens.

Este artigo vs o fluxo em popup React / JS puro

Se você usa @intastellar/signin-sdk-react ou o bundle HTML/JS puro, o login costuma rodar em popup e um token chega via postMessage. Nesse modo você não monta manualmente a URL GET de authorize nem o POST de token.

Use esta página quando o seu time implementar authorize + callback + token (stack própria, alguns cenários mobile ou apps web orientados a servidor). Para escolher tipos de cliente primeiro, veja Primeiros passos.

Os nomes de parâmetro abaixo seguem o uso comum de OAuth 2.0 / OIDC — confira os nomes exatos, escopos e URLs de discovery no seu registro Intastellar e na referência técnica.

O que você precisa

  • Client ID, redirect URI registrados e (para clientes confidenciais) client secret.
  • Um local seguro para guardar state e o PKCE code_verifier entre os passos do redirect.
  • URIs de redirect HTTPS em produção.

Passo 1 — Envie o usuário para authorize

Envie o navegador ao authorization endpoint com parâmetros de query:

ParâmetroFunção
response_typeUse code neste fluxo.
client_idSeu client ID registrado.
redirect_uriDeve bater exatamente com uma URI registrada.
scopeEscopos separados por espaço (muitas vezes inclui openid em OIDC).
stateValor aleatório e difícil de adivinhar; você valida no retorno.
code_challengePKCE: hash SHA-256 do code_verifier, codificado em Base64url (clientes públicos).
code_challenge_methodEm geral S256.

Exemplo (quebras de linha só para leitura):

GET AUTHORIZATION_ENDPOINT?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Guarde state e o code_verifier bruto (PKCE) no servidor ou em cookie seguro e de curta duração para validar no callback.

Passo 2 — Trate o callback

A Intastellar redireciona para o seu redirect_uri com:

Query paramSignificado
codeCódigo de autorização de uso único.
stateEco do valor que você enviou; tem que bater com o state armazenado.

Se o usuário negar acesso ou ocorrer erro, você pode receber error e error_description — trate isso sem considerar sucesso.

Passo 3 — Troque o código por tokens

POST no token endpoint (em geral application/x-www-form-urlencoded):

CampoFunção
grant_typeauthorization_code
codeO código do callback.
redirect_uriA mesma URI do passo 1.
client_idSeu client ID.
code_verifierPKCE: o verificador secreto original (clientes públicos).
client_secretSomente clientes confidenciais.

A resposta costuma incluir access_token, refresh_token opcional e id_token quando openid foi pedido. Valide o ID token (issuer, audience, expiração, assinatura) com JWKS do issuer quando você depender das claims no app.

Checklist de segurança

  • Nunca pule a verificação de state — evita CSRF no callback.
  • Use PKCE em qualquer cliente que não pode guardar client secret (SPAs, mobile).
  • Use HTTPS para todo redirect URI em produção.
  • Mantenha refresh tokens e client secrets apenas em servidores que você controla.

Perguntas frequentes

invalid_grant logo após o callback

Muitas vezes código já usado, código expirado ou incompatibilidade de redirect_uri / PKCE. Códigos costumam ser uso único. Veja Logout, erros e solução de problemas.

Precisamos de PKCE num app só servidor?

Se o navegador inicia o fluxo e não há secret no navegador, sim. Se um servidor confidencial inicia e termina tudo sem expor o secret, siga o que o registro permite — ainda use state.

Próximo

Last updated