MOTOKO BASE

Documentação

Configuração OAuth

Configuração passo a passo de OAuth do Google e GitHub para o Motoko Base — crie apps de provedor, configure callback URLs e preencha o .env.

Abrir emChatGPT (abre em uma nova aba)Claude (abre em uma nova aba)Cursor (abre em uma nova aba)Configuração passo a passo de OAuth do Google e GitHub para o Motoko Base — crie apps de provedor, configure callback URLs e preencha o .env.

O login com Google e GitHub é opcional. Deixe as variáveis OAuth indefinidas e o app inicia normalmente — os botões sociais em /sign-in e /sign-up permanecem desabilitados.

Depois de configurado, o Better Auth gerencia o fluxo OAuth e armazena contas vinculadas na tabela account. As callback URLs devem coincidir exatamente com o seu BETTER_AUTH_URL.

Antes de começar

Certifique-se de que estas variáveis de auth já estão definidas:

# .env or .env.local
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-generated-secret
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Para desenvolvimento local, use http://localhost:3000 para ambas as variáveis de URL. Em produção, defina-as com a sua origem HTTPS pública (ex.: https://app.example.com).

Gere BETTER_AUTH_SECRET se ainda não o fez:

openssl rand -base64 32

Reinicie o servidor de desenvolvimento após alterar qualquer variável de ambiente:

pnpm dev

Google OAuth

Passo 1 — Criar um projeto no Google Cloud

  1. Abra o Google Cloud Console
  2. Crie um novo projeto (ou selecione um existente)
  3. Vá em APIs & Services → OAuth consent screen
  4. Escolha External (ou Internal para apps só de Workspace)
  5. Preencha o nome do app, e-mail de suporte e contato do desenvolvedor
  6. Adicione scopes: email, profile e openid (os defaults costumam bastar)
  7. Adicione usuários de teste se o app estiver no modo Testing

Passo 2 — Criar credenciais OAuth

  1. Vá em APIs & Services → Credentials
  2. Clique em Create Credentials → OAuth client ID
  3. Tipo de aplicação: Web application
  4. Dê um nome (ex.: Motoko Base local)

Passo 3 — Definir o redirect URI

Em Authorized redirect URIs, adicione:

{BETTER_AUTH_URL}/api/auth/callback/google

Exemplos:

EnvironmentRedirect URI
Localhttp://localhost:3000/api/auth/callback/google
Productionhttps://app.example.com/api/auth/callback/google

O caminho deve ser exatamente /api/auth/callback/google — o Better Auth registra esta rota automaticamente.

Opcionalmente adicione Authorized JavaScript origins para desenvolvimento local:

http://localhost:3000

Passo 4 — Copiar credenciais para .env

Após criar o client, o Google mostra um Client ID e um Client secret. Adicione-os ao .env:

GOOGLE_CLIENT_ID=123456789-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx

Ambos os valores são somente de servidor — nunca os coloque em NEXT_PUBLIC_*.

Passo 5 — Verificar localmente

  1. Reinicie o servidor de desenvolvimento: pnpm dev
  2. Abra http://localhost:3000/sign-in
  3. O botão Sign in with Google deve estar habilitado (não acinzentado)
  4. Clique — você deve ir ao Google e voltar para /dashboard

Se o botão continuar desabilitado, verifique se ambas GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET estão definidas e não vazias.

Solução de problemas do Google

ProblemFix
redirect_uri_mismatchRedirect URI in Google Console must match {BETTER_AUTH_URL}/api/auth/callback/google exactly (scheme, host, port, path)
Button disabledBoth GOOGLE_* vars must be set; restart dev server
access_denied in Testing modeAdd your Google account as a test user on the consent screen
Works locally, fails in productionAdd production redirect URI and set BETTER_AUTH_URL to your live domain

GitHub OAuth

Passo 1 — Criar uma GitHub OAuth App

  1. Abra GitHub Developer Settings → OAuth Apps
  2. Clique em New OAuth App
  3. Preencha:
    • Application name — ex.: Motoko Base
    • Homepage URL — a URL do seu app (local: http://localhost:3000)
    • Authorization callback URL — veja o Passo 2

Passo 2 — Definir o callback URL

O Authorization callback URL deve ser:

{BETTER_AUTH_URL}/api/auth/callback/github

Exemplos:

EnvironmentCallback URL
Localhttp://localhost:3000/api/auth/callback/github
Productionhttps://app.example.com/api/auth/callback/github

Clique em Register application.

Passo 3 — Gerar um client secret

  1. Na página da OAuth app, clique em Generate a new client secret
  2. Copie o Client ID e o Client secret imediatamente — o secret é mostrado só uma vez

Passo 4 — Copiar credenciais para .env

GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ambos os valores são somente de servidor.

Passo 5 — Verificar localmente

  1. Reinicie o servidor de desenvolvimento: pnpm dev
  2. Abra http://localhost:3000/sign-in
  3. O botão Sign in with GitHub deve estar habilitado
  4. Clique — autorize o app e chegue em /dashboard

GitHub Apps vs OAuth Apps

O Motoko Base usa uma OAuth App padrão (não uma GitHub App). Se você usar uma GitHub App em vez disso, garanta que Account permissions → Email addresses esteja em Read-only para que o Better Auth possa ler o e-mail verificado do usuário.

Solução de problemas do GitHub

ProblemFix
redirect_uri mismatchCallback URL must be {BETTER_AUTH_URL}/api/auth/callback/github exactly
Button disabledBoth GITHUB_* vars must be set; restart dev server
Missing email / sign-in failsFor GitHub Apps, enable Email addresses read permission; OAuth Apps include email by default
Works locally, fails in productionUpdate callback URL in GitHub settings and set production BETTER_AUTH_URL

Checklist de produção

Use esta checklist ao implantar OAuth em staging ou produção:

  1. Definir URLs canônicas

    BETTER_AUTH_URL=https://app.example.com
NEXT_PUBLIC_APP_URL=https://app.example.com

  2. Adicionar callback URLs de produção no Google Console e nas configurações da GitHub OAuth app (mantenha as URIs locais se ainda desenvolver localmente)

  3. Opcional — origens extras para deploys de preview:

    BETTER_AUTH_TRUSTED_ORIGINS=https://staging.example.com,https://*.vercel.app

  4. Reiniciar / redesployar após mudanças de env

  5. Testar ambos os provedores na URL ao vivo — entrar, sair e confirmar que a sessão persiste

Onde o OAuth está conectado no código

Em geral você só precisa das variáveis de ambiente. Para personalizar o comportamento, edite estes arquivos:

FilePurpose
src/lib/auth/auth.tsRegisters socialProviders.google and socialProviders.github
src/lib/auth/social.tsisGoogleAuthConfigured() / isGitHubAuthConfigured()
src/app/sign-in/sign-in-form.tsxGoogle/GitHub sign-in handlers
src/app/sign-up/sign-up-form.tsxGoogle/GitHub sign-up handlers
src/app/sign-in/page.tsxPasses enabled flags to the form

Segredos OAuth nunca pertencem a arquivos TypeScript de config — só ao .env.

Próximos passos

Better Auth — Visão geral completa de auth, sessões, rotas protegidas e mapa de arquivos.

Variáveis de ambiente — Todas as variáveis de auth em um só lugar.