Fluxos OAuth 2.0: Qual Você Precisa?

OAuth 2.0: Deixe Usuários Logarem Sem Armazenar Senhas

OAuth 2.0 é um protocolo de delegação. Em vez do seu app coletar e armazenar senhas de usuários, você os redireciona para Google/GitHub/etc., eles autenticam lá, e voltam com um token. Seu app nunca vê a senha.

Termos Chave

Termo	Significado
Resource Owner	O usuário
Client	Sua aplicação
Authorization Server	Google, GitHub, Auth0 — quem autentica o usuário
Resource Server	A API que tem os dados do usuário
Access Token	Token de curta duração para acessar APIs
Refresh Token	Token de longa duração para obter novos access tokens
Scope	Que permissões o token concede (ex: `read:email`)

Fluxo 1: Authorization Code + PKCE (Recomendado)

Para web apps, SPAs, apps mobile. O fluxo mais seguro para aplicações voltadas ao usuário.

1. Seu app redireciona o usuário ao authorization server:
   GET https://auth.example.com/authorize?
     response_type=code&
     client_id=SEU_CLIENT_ID&
     redirect_uri=https://seuapp.com/callback&
     scope=openid email profile&
     state=token_csrf_aleatorio&
     code_challenge=SHA256(code_verifier)&
     code_challenge_method=S256

2. Usuário faz login e consente

3. Auth server redireciona de volta com um código:
   https://seuapp.com/callback?code=AUTH_CODE&state=token_csrf_aleatorio

4. Seu servidor troca o código por tokens:
   POST https://auth.example.com/token
   grant_type=authorization_code&
   code=AUTH_CODE&
   redirect_uri=https://seuapp.com/callback&
   client_id=SEU_CLIENT_ID&
   code_verifier=CODE_VERIFIER_ORIGINAL

5. Resposta:
   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "abc..."
   }

Fluxo 2: Client Credentials

Para comunicação server-to-server. Sem usuário envolvido.

POST https://auth.example.com/token
grant_type=client_credentials&
client_id=SEU_CLIENT_ID&
client_secret=SEU_CLIENT_SECRET&
scope=read:data

Use quando seu backend precisa chamar outra API sem contexto de usuário.

Qual Fluxo Usar

Tipo de Aplicação	Fluxo	Notas
Web app (server-rendered)	Authorization Code + PKCE	Servidor pode guardar client_secret
SPA (React, Vue)	Authorization Code + PKCE	Sem client_secret (cliente público)
App mobile	Authorization Code + PKCE	Use deep links para redirect
Server-to-server	Client Credentials	Sem interação do usuário
Ferramenta CLI	Device Code	Usuário autoriza em outro dispositivo

Fluxos Depreciados (Não Use)

Implicit Flow: Tokens no fragmento da URL. Depreciado — use Authorization Code + PKCE.
Resource Owner Password Credentials: App coleta username/password diretamente. Derrota o propósito do OAuth.

Implementação Comum (Next.js + NextAuth)

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth';
import GitHubProvider from 'next-auth/providers/github';
import GoogleProvider from 'next-auth/providers/google';

export const { handlers, auth } = NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
});

Decodifique seus tokens: Decodificador JWT — inspecione access tokens e ID tokens OAuth.