Adicionar o início de sessão com GitHub

Passo a passo para iniciantes

Pré-requisitos: a app web a correr em local e um banco de dados migrado para contas reais. Precisa de uma conta GitHub — a que possui o repositório serve. Gratuito, cerca de 5 minutos por ambiente.

Terminologia rápida: uma OAuth App do GitHub é o registo que permite ao GitHub iniciar a sessão dos utilizadores por si. Ao contrário da maioria dos provedores, uma OAuth App permite exatamente uma Authorization callback URL — logo, local (http://localhost:3000/…) e produção (https://yourdomain.com/…) precisam cada uma da sua própria app. Reutilizar uma app alternando o callback entre ambientes parte um lado de cada vez.

1. Crie uma OAuth App local nas Developer settings da sua conta. 2. Copie o Client ID e gere um Client Secret. 3. Defina os três valores de ambiente e reinicie. 4. Repita uma vez com o seu domínio real antes de ir para o ar.

• Colocar a app web online em 5 minutos
• Configurar a base de dados

Criar a OAuth App local

1. Abra github.com e inicie sessão. Clique na sua foto de perfil no canto superior direito → Settings.

2. Desça até ao fim da barra lateral esquerda e abra Developer settings → OAuth Apps → New OAuth App.

3. Application name: algo como supastack local — os utilizadores veem este nome na página de autorização do GitHub. Homepage URL: http://localhost:3000. Authorization callback URL: http://localhost:3000/api/auth/callback/github. Clique em Register application.

4. Na página da app, copie o Client ID, clique em Generate a new client secret e copie o segredo de imediato — o GitHub só o mostra uma vez, embora possa sempre gerar outro.

Criar a OAuth App de produção

Repita os mesmos passos de New OAuth App com o nome do produto, Homepage URL https://yourdomain.com e Authorization callback URL https://yourdomain.com/api/auth/callback/github.

Guarde as credenciais de cada app no seu próprio ambiente: o par da app local vive em apps/web/.env.local, o par da app de produção no cofre de segredos do seu host. O segredo local nunca deve chegar à configuração de produção nem vice-versa.

Adicionar os valores à app

Preencha as três linhas abaixo em apps/web/.env.local usando as credenciais da app local. AUTH_GITHUB_ENABLED=true ativa o botão; o par identifica a OAuth App.

O client secret fica apenas no servidor — nunca em variáveis NEXT_PUBLIC_/EXPO_PUBLIC_ e nunca no Git. Reinicie o servidor de desenvolvimento depois de editar.

Não reutilize valores GITHUB_APP_* que possa ver noutro lado — pertencem a uma integração de GitHub App sem relação, não ao início de sessão de utilizadores. O docs/github-auth-setup.md do kit percorre todo o fluxo de ponta a ponta se quiser uma segunda referência.

# apps/web/.env.local — from the LOCAL OAuth App
AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-oauth-app-secret

Verificar e resolver problemas

Abra http://localhost:3000/auth e clique no botão do GitHub. Autorize a app em github.com e confirme que regressa com sessão iniciada.

Enquanto AUTH_GITHUB_ENABLED=true não estiver definido, a opção GitHub em /auth permanece visível mas desativada — verifique os nomes do ficheiro env e reinicie. Definir a flag sem GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET faz o arranque falhar e nomeia a variável em falta.

Um callback mal correspondido é a falha habitual: a Authorization callback URL da app deve ser exatamente {APP_URL}/api/auth/callback/github — protocolo, host, porta e caminho. Um erro redirect_uri após a implementação geralmente significa que o pedido atingiu as credenciais da app local enquanto APP_URL diz produção, ou o contrário.

Reinicie o servidor de desenvolvimento após cada edição do env; os valores só são lidos no arranque.

• Configurar a seguir o banco de dados
• Visão geral dos provedores OAuth