For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/tanstack/google-sign-in.md (or send Accept: text/markdown).
Adicionar o início de sessão com Google
Crie um cliente OAuth do Google Cloud gratuito e ligue «Continuar com Google» à app.
Passo a passo para iniciantes
Pré-requisitos: a app web a correr em local (Online em 5 minutos) e um banco de dados migrado para contas reais (Configurar a base de dados). Precisa de uma conta Google normal; tudo aqui é gratuito e leva cerca de 10 minutos.
Terminologia rápida: OAuth é o padrão em que a Google inicia a sessão do utilizador na página da Google e entrega uma prova à sua app. Um projeto Google Cloud é um contentor na consola da Google que guarda as credenciais da app. O ecrã de consentimento OAuth é a página que a Google mostra aos utilizadores antes de os devolver. Um client ID identifica a sua app perante a Google; o client secret é a sua palavra-passe e fica no servidor.
1. Crie um projeto Google Cloud. 2. Configure o ecrã de consentimento. 3. Crie um cliente OAuth Web e copie o ID e o segredo. 4. Cole três valores em apps/web-tanstack/.env.local e reinicie o servidor de desenvolvimento.
Um único projeto chega para todo o produto: o mesmo projeto Google Cloud irá depois alojar a sua implementação no Cloud Run, e o início de sessão mobile passa pelo mesmo backend web — não cria um cliente separado por plataforma ou recurso.
Criar o projeto Google Cloud
1. Abra console.cloud.google.com e inicie sessão com a sua conta Google.
2. Clique no menu de projeto na barra superior (junto ao logótipo do Google Cloud) e escolha New Project.
3. Dê-lhe um nome — o nome do produto serve — e clique em Create. Não é necessária organização, cartão nem conta de faturação para credenciais de início de sessão.
Esperado: a consola recarrega para o novo projeto e o nome aparece na barra superior. Reutilize este projeto quando chegar ao guia de implementação em vez de criar outro.
Configurar o ecrã de consentimento OAuth
1. Na navegação à esquerda, abra APIs & Services → OAuth consent screen e clique em Get started.
2. Introduza o nome da app que os utilizadores verão (o nome do produto), escolha um e-mail de apoio ao utilizador, selecione External como audiência, preencha o e-mail de contacto do programador e clique até Create.
3. Mais nada é necessário neste ecrã: a app apenas pede os scopes predefinidos openid, email e profile, que não exigem scopes extra nem verificação.
O estado de publicação permanece em Testing enquanto desenvolve. Nesse modo, apenas as contas listadas conseguem iniciar sessão — adicione o seu próprio endereço Gmail em Audience → Test users, senão a Google bloqueia até a si. Quando o produto estiver no ar, clique em Publish app; como não são pedidos scopes sensíveis, publicar não inicia uma revisão de verificação da Google.
Criar o cliente OAuth
1. Abra APIs & Services → Credentials → + Create Credentials → OAuth client ID.
2. Defina Application type como Web application e dê-lhe um nome como supastack local.
3. Em Authorized JavaScript origins adicione http://localhost:3000. Em Authorized redirect URIs adicione http://localhost:3000/api/auth/callback/google — esse caminho de callback pertence ao Better Auth, o motor de autenticação predefinido do kit: {APP_URL}/api/auth/callback/google.
4. Clique em Create e copie o Client ID e o Client Secret da caixa de diálogo. Pode reabrí-los na página do cliente mais tarde, mas copiá-los agora poupa um passo.
Para produção, crie um segundo cliente Web (recomendado) ou adicione a este: origem JavaScript https://yourdomain.com e URI de redirecionamento https://yourdomain.com/api/auth/callback/google. Manter clientes separados por ambiente significa que um segredo local comprometido não consegue chegar à produção.
Adicionar os valores à app
Abra apps/web-tanstack/.env.local — o TanStack Start lê este ficheiro, não o .env da raiz — e preencha as três linhas abaixo. AUTH_GOOGLE_ENABLED=true ativa o botão; o par de cliente identifica o seu cliente Google Cloud.
O client secret é apenas do servidor: nunca deve aparecer numa variável NEXT_PUBLIC_ ou EXPO_PUBLIC_ nem ser enviado para o Git. Em produção, defina os mesmos três nomes no cofre de segredos do seu host em vez de um ficheiro env.
Reinicie o servidor de desenvolvimento depois de editar — as alterações de ambiente só são lidas no arranque.
# apps/web-tanstack/.env.local
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secretVerificar e resolver problemas
Abra http://localhost:3000/auth, clique no botão da Google, conclua o ecrã de consentimento da Google e confirme que a app regressa com sessão iniciada.
redirect_uri_mismatch significa que o URI de redirecionamento registado na Google não corresponde exatamente — verifique o protocolo (http vs https), a porta e o caminho: deve terminar em /api/auth/callback/google, não em /callback/google/ nem numa variante com barra final.
Access blocked / has not completed the Google verification process significa que o ecrã de consentimento ainda está em Testing e a conta que inicia sessão não está listada em Test users — adicione-a na secção Audience.
Se o botão da Google faltar ou o início de sessão continuar a falhar depois de editar .env.local, reinicie o servidor de desenvolvimento. Se o arranque falhar nomeando uma variável, a flag está ativa sem o seu par de cliente completo.
Para continuar a configuração, leia Adicionar o início de sessão com GitHub.