Ir para o conteúdo

Autenticação Google OAuth para Mobile

Este guia resume as responsabilidades do backend e os passos para seguir para autorizar usuários com o Google, seguindo o fluxo OAuth/OIDC já implementado.

1. Fluxo geral

  1. Pedir URL de autorização
  2. Chamar GET /api/auth/oauth/google e incluir o parâmetro redirect_url com o valor de EXPO_PUBLIC_OAUTH_REDIRECT_URL (ex: billings-ease://auth/oauth/callback/google).
  3. O backend devolve auth_url, state e code_verifier (PKCE). O handler está em billings-ease-backend/internal/handlers/auth/oauth.go (StartLogin) e usa internal/services/oauth/provider.go para gerar o state/PKCE. O serviço aceita redirect_url apenas quando ele corresponde a MOBILE_FRONTEND_URL, garantindo a escolha correta entre web e mobile.
  4. Abrir o auth_url
  5. Abrir o link em um browser externo (AuthSession, Chrome Custom Tabs, etc.).
  6. O Google pede permissão e, quando aprovado, redireciona para /api/auth/oauth/callback/google com code e state.
  7. Callback do backend
  8. internal/handlers/auth/oauth.go valida state, troca o code por tokens em internal/services/oauth/provider.go, valida o ID Token e cria/atualiza o usuário (UserAuthProvider).
  9. Os JWTs são enviados para o frontend/mobile via redirectToFrontendWithTokens, que faz um 302 para FRONTEND_URL/auth/oauth/callback/google com token e refresh_token no fragment (#token=...&refresh_token=...).
  10. Receber os tokens no mobile
  11. No mobile, registre o deep link FRONTEND_URL (ex: billings-ease://auth/oauth/callback/google) para interceptar a navegação e extrair o fragmento.
  12. Guarde os tokens em armazenamento seguro (SecureStore, etc.) e configure o interceptor HTTP para injetar Authorization: Bearer <token>.
  13. Em caso de 401, limpe os tokens e force o usuário ao login.

O fluxo completo, incluindo a troca do código, validações e criação de usuários, está documentado em billings-ease-documentation/docs/02-backend/integracoes.md e em billings-ease-documentation/docs/02-backend/api.md.

2. Endpoints e campos importantes

  • GET /api/auth/oauth/google
  • Resposta: { auth_url, state, code_verifier }
  • Documento: billings-ease-documentation/docs/02-backend/api.md e integracoes.md.
  • GET /api/auth/oauth/callback/google
  • Recebe code + state.
  • Redireciona para FRONTEND_URL/auth/oauth/callback/google com tokens no fragment.
  • POST /api/auth/refresh
  • Usa o refresh_token para gerar novo JWT de acesso.

3. Arquivos-chave no backend

  • internal/handlers/auth/oauth.go: handlers StartLogin, Callback, validadores de state/CSRF e redirecionamento para o frontend.
  • internal/services/oauth/provider.go: registra os providers, gera state + PKCE, armazena temporariamente no stateStore (substituível por Redis em produção) e executa HandleCallback.
  • internal/services/oauth/google_provider.go: define os endpoints do Google, troca de código e validação de id_token/claims (sub, email, name, picture).
  • internal/models/user_auth_provider.go e repositórios relacionados: armazenam associações entre usuários e provedores externos.
  • billings-ease-documentation/docs/02-backend/auth.md: explica armazenamento seguro e interceptors específicos mobile (SecureStore + interceptors de 401).

4. Variáveis de ambiente necessárias

  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
  • GOOGLE_REDIRECT_URL (ex: https://api.billings-ease.com/api/auth/oauth/callback/google)
  • FRONTEND_URL define para onde o backend manda os tokens para o frontend web
  • MOBILE_FRONTEND_URL deve ser o deep link usado pelo app (ex: billings-ease://auth/oauth/callback/google)
  • EXPO_PUBLIC_OAUTH_REDIRECT_URL (no .env do mobile) precisa bater com MOBILE_FRONTEND_URL para que o mobile informe o deep link ao backend

Para desenvolvimento local use os valores descritos em billings-ease-documentation/docs/07-guides/desenvolvimento-local.md.

5. PKCE / Segurança

  • O backend gera code_verifier e code_challenge em internal/services/oauth/provider.go.
  • O code_verifier retornado no início deve ser guardado no mobile até o callback, mas o backend também armazena no stateStore (PKCE server-side). Isso garante que apenas o app que pediu o login possa completar o fluxo.
  • state deve ser validado (CSRF). Se for inválido, o handler redirecionará o usuário com erro consultando redirectToFrontendWithError.
  1. Configure o valor de FRONTEND_URL para o esquema usado pelo app (ex: billings-ease://auth/oauth/callback/google).
  2. Após o redirecionamento, o app lê o fragmento (#token=...&refresh_token=...) e armazena os tokens.
  3. Opcionalmente, extraia state do backend para validar no mobile (a mesma string pode ser usada para emparelhar requests, mas o backend já verifica o recebido do Google).

7. Referências

  • billings-ease-documentation/docs/02-backend/api.md (endpoints OAuth)
  • billings-ease-documentation/docs/02-backend/integracoes.md (fluxo completo)
  • billings-ease-documentation/docs/02-backend/auth.md (armazenamento seguro no mobile)
  • billings-ease-backend/internal/handlers/auth/oauth.go
  • billings-ease-backend/internal/services/oauth/provider.go