OAuth 2.0 e OpenID Connect: O Guia Definitivo para Desenvolvedores

Sempre que você utiliza botões como "Entrar com Google" ou "Login com GitHub", você está interagindo com o protocolo OAuth 2.0. Ele se tornou o padrão absoluto da indústria para autorização moderna. Quando adicionamos a camada OpenID Connect (OIDC), passamos a lidar também com a autenticação de identidade. Entender esses fluxos é um requisito obrigatório para qualquer desenvolvedor que constrói aplicações web seguras e integrações com APIs de terceiros.

Autenticação vs. Autorização: Qual a diferença?

• Autenticação (AuthN): Responde à pergunta "Quem é você?". Trata da verificação da identidade do usuário. É o papel principal do OpenID Connect.
• Autorização (AuthZ): Responde à pergunta "O que você pode fazer?". Trata da concessão de permissões para acessar recursos. Este é o domínio do OAuth 2.0.

O OAuth 2.0 foi criado para permitir que um aplicativo acesse, por exemplo, seus arquivos no Google Drive sem que você precise fornecer sua senha do Google para ele. O OpenID Connect estende esse protocolo, fornecendo um formato padronizado (JWT) para compartilhar informações do perfil do usuário.

Os Quatro Pilares do OAuth

• Resource Owner (Dono do Recurso): O usuário final que possui os dados e concede o acesso.
• Client (Cliente): A aplicação (web, mobile ou desktop) que solicita o acesso aos dados.
• Authorization Server (Servidor de Autorização): O servidor que autentica o usuário e emite os tokens (ex: Google, Auth0, Keycloak).
• Resource Server (Servidor de Recurso): A API que hospeda os dados protegidos (ex: API do Gmail, API do Twitter).

Fluxo Authorization Code (com PKCE)

Este é o fluxo mais seguro e recomendado para quase todas as aplicações modernas. O PKCE (Proof Key for Code Exchange) é uma extensão que impede ataques de interceptação de código, sendo vital para Single Page Applications (SPAs) e apps mobile.

1. O usuário clica em "Login com Google" na sua App.
2. Sua App redireciona o usuário para o endpoint de autorização:
   GET https://accounts.google.com/o/oauth2/v2/auth?
     response_type=code
     &client_id=SEU_CLIENT_ID
     &redirect_uri=https://suaapp.com/callback
     &scope=openid email profile
     &state=token_csrf_aleatorio
     &code_challenge=HASH_SHA256
     &code_challenge_method=S256

3. O usuário faz login no Google e autoriza as permissões.
4. O Google redireciona de volta para sua App com um código:
   GET https://suaapp.com/callback?code=CODIGO_AUTORIZACAO&state=token_csrf_aleatorio

5. Seu servidor troca o código pelos tokens finais:
   POST https://oauth2.googleapis.com/token
   Body: {
     code: CODIGO_AUTORIZACAO,
     client_id: SEU_CLIENT_ID,
     client_secret: SEU_CLIENT_SECRET,
     redirect_uri: https://suaapp.com/callback,
     grant_type: authorization_code,
     code_verifier: STRING_ORIGINAL_DO_PKCE
   }

6. O Google retorna o payload:
   {
     "access_token": "ya29.a0...",
     "id_token": "eyJhbGci...",       // Especifico do OIDC
     "refresh_token": "1//0e...",
     "expires_in": 3600,
     "token_type": "Bearer"
   }

Entendendo os Tipos de Tokens

• Access Token: Possui vida curta (geralmente 1 hora). É usado em cada requisição de API através do header Authorization: Bearer <token>.
• Refresh Token: Possui vida longa. Permite obter novos Access Tokens sem que o usuário precise logar novamente. Deve ser armazenado com segurança máxima (apenas no lado do servidor).
• ID Token: Um JSON Web Token (JWT) que contém os dados de identidade (email, nome, foto). É a peça central do OpenID Connect.

O que são Scopes (Escopos)?

Os escopos definem exatamente quais dados sua aplicação está solicitando. Eles aparecem na tela de consentimento para o usuário.

// Escopos do OpenID Connect
openid        // Obrigatório para identificar OIDC
email         // Acesso ao endereço de e-mail
profile       // Nome, foto e fuso horário

// Escopos específicos do Google
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/calendar

// Escopos do GitHub
read:user     // Ler perfil do usuário
repo          // Acesso total a repositórios
read:org      // Ler participação em organizações

Boas Práticas de Segurança

• Utilize PKCE sempre — Não apenas em apps mobile, mas também em aplicações server-side.
• Valide o parâmetro state — Essencial para prevenir ataques de Cross-Site Request Forgery (CSRF).
• Não use localStorage para tokens — Em aplicações web, prefira cookies HTTP-only, Secure e SameSite para mitigar ataques XSS.
• Verifique a assinatura do ID Token — Sempre valide o emissor (iss), a audiência (aud) e a expiração (exp) do JWT.
• Princípio do Privilégio Mínimo — Solicite apenas os escopos estritamente necessários para o funcionamento da sua app.

Qual fluxo escolher?

• Authorization Code + PKCE: A escolha padrão para aplicações Web, SPAs e Mobile.
• Client Credentials: Para comunicação entre servidores (M2M) onde não há um usuário humano envolvido.
• Device Code: Para dispositivos com entrada limitada, como Smart TVs ou ferramentas de linha de comando (CLI).
• ⚠️ Implicit Flow: Considerado inseguro e depreciado. Evite utilizá-lo em novos projetos.