Uma URL de redirecionamento (redirect URI) é o endereço para onde o Google devolve o usuário depois que ele aprova o acesso. Ela precisa bater exatamente com o que está cadastrado no app OAuth: mesmo esquema (https), mesmo host, mesmo caminho e, se houver, mesma porta. Se qualquer pedaço divergir, o Google recusa a autorização. Antes de dar a uma ferramenta de IA acesso a Gmail, Drive, Calendar ou Planilhas, vale abrir o app no Google Cloud Console, conferir quem é o dono, ver se ele é interno ou externo, olhar a URL cadastrada e, principalmente, ler a tela de consentimento e os escopos que ele pede.
Este guia traz o método de revisão em passos e uma checklist. As regras técnicas citadas vêm da documentação oficial do Google para OAuth 2.0; onde a documentação não fecha um ponto, o texto manda conferir no Console em vez de afirmar como certeza.
Resumo rápido
- A URL de redirecionamento precisa coincidir caractere por caractere com a cadastrada: esquema, host, caminho, porta e sem fragmento.
- https é obrigatório; http://localhost é exceção aceita apenas para desenvolvimento na máquina local.
- Curinga é recusado pela validação do Google: a URL tem que ser literal.
- Antes de autorizar, confira dono do app, se ele é interno ou publicado, a tela de consentimento e os escopos.
- URL que você não reconhece ou domínio de terceiro desconhecido: não cadastre. Pergunte ao fornecedor e confira no Console.
O que é uma URL de redirecionamento e por que ela precisa casar exatamente
No fluxo OAuth, o usuário é mandado ao Google, aprova o acesso e volta para a aplicação com um código de autorização. A redirect URI é o endereço desse retorno, por onde o código chega ao sistema que quer os dados.
A documentação do Google para aplicações web diz que o valor enviado precisa corresponder exatamente a uma das URIs autorizadas e que, se não bater, o retorno é um erro de incompatibilidade. Não é comparação aproximada: https://app.suaempresa.com.br/oauth/callback não aceita barra a mais no fim, nem http: no lugar de https:, nem www. na frente, nem porta diferente.
A rigidez é de segurança: com qualquer variação aceita, um atacante poderia apontar o retorno para um endereço sob o seu controle e capturar o código. A validação do Google também recusa:
- Esquema: deve ser HTTPS; localhost é isento.
- Host: não pode ser endereço IP puro; localhost é isento.
- Domínio: o TLD precisa constar da lista de sufixos públicos, e o host não pode ser
googleusercontent.com. - Caminho: não pode conter travessia de diretório.
- Consulta e fragmento: sem redirecionamento aberto na query e sem componente de fragmento.
- Caracteres: sem curinga, sem ASCII não imprimível, sem codificação percentual inválida, sem caractere nulo.
O curinga não é uma conveniência que o Google ignora: é explicitamente listado como caractere proibido. Se uma ferramenta ficou anos com curinga cadastrado e funcionou, o valor lá é outro. Confira no Console.
Por que http://localhost só serve para desenvolvimento
A documentação do Google é clara: URIs de localhost são isentas da regra de HTTPS. A página de web server usa http://localhost:8080 nos exemplos e diz que, para testes, você pode apontar URIs para a máquina local.
Isso é uma exceção de teste, não um caminho de produção. localhost é o próprio computador de quem está logado. Se você cadastra um retorno local em um app usado por clientes, o navegador tenta abrir uma porta da máquina do usuário, e não o seu servidor. Não há como o sistema receber o código por lá.
O desenho comum é ter duas configurações: uma de desenvolvimento, com localhost, e uma de produção, com o domínio real em HTTPS. O risco aparece quando o time esquece de remover o localhost do app publicado. Se o app é de produção e a lista tem localhost, trate como pendência de limpeza.
Por que curinga e domínio raiz amplo são recusados
Um curinga diz “aceite qualquer coisa”. Em OAuth, isso anula a garantia de que o código volta para um endereço conhecido. A validação do Google proíbe o asterisco nos caracteres da URI, e vale a mesma lógica para as origens JavaScript.
Não há regra publicada que permita “qualquer subdomínio da empresa” em uma linha. Cada URI é uma entrada separada, conferida literalmente. Cadastre o caminho exato que a ferramenta usa e nada além.
App interno e app externo: a diferença que pesa mais que a URL
No Google Auth Platform, o app tem um tipo de público. A distinção prática para quem vai autorizar é esta:
- Interno: o app é de um projeto de Google Workspace e só aceita usuários da organização. Não é para o mundo, e as exigências de tela de consentimento tendem a ser menores.
- Externo: o app pode ser autorizado por qualquer conta Google, inclusive de fora da empresa. Conforme a página de verificação de apps OAuth, apps que pedem escopos sensíveis ou restritos precisam concluir o processo de verificação. Escopos não sensíveis normalmente não exigem a verificação completa, mas a marca e o logo só aparecem na tela de consentimento após verificação.
A consequência é concreta: se a ferramenta diz ser “só para uso interno” mas o app no Console está como externo, ou ela usa um app próprio e externo, ou usa um de terceiro. Nos dois casos, o acesso não fica restrito ao Workspace.
O ponto sensível é o estado de publicação. Em teste, o Google limita os usuários e exige que estejam cadastrados; publicado, o acesso se abre para o público escolhido. Confirme no Console o estado atual, porque as exigências mudam.
A verificação não é só burocracia: apps não verificados que pedem escopos sensíveis mostram aviso ao usuário. Se a ferramenta exibe esse alerta para acesso amplo ao Gmail, você está autorizando algo fora do fluxo revisado.
Tela de consentimento e escopos importam mais do que a URL
O usuário não vê a URL: ele vê a tela de consentimento. É ali que aparecem o nome do app, o logo, o e-mail de suporte e os links, segundo a página de gestão de marca do OAuth. A documentação afirma que nome e logo só aparecem se o app tiver sido verificado.
Por isso a revisão quase sempre começa pela tela:
- Nome: deve representar a empresa de forma reconhecível. A documentação lista como inaceitáveis nomes que combinam marcas do Google com termos genéricos. Um app chamado “Gmail Drive Helper” pedindo acesso ao Gmail merece desconfiança, mesmo com URL correta.
- E-mail de suporte: tem que ser um endereço que sua empresa reconheça. Domínio desconhecido é sinal de origem suspeita.
- Escopos: são o que realmente importa. Pedir leitura de e-mails para um assistente que só lê faz sentido; pedir o escopo total do Drive para quem só lê uma pasta é excesso.
Uma ferramenta que diz “preciso de acesso ao Drive” e pede o escopo amplo enxerga tudo o que a conta vê. Se ela só precisa de arquivos que ela mesma cria, há escopos estreitos, como os do tipo drive.file.
Para revisar permissões de forma sistemática, o guia de permissões de agentes de IA mostra como separar leitura de escrita e onde exigir aprovação humana. Para entender o que se ganha e o que se abre ao ligar um assistente ao ambiente Google, veja o panorama de integrações com o Google Gemini.
O risco real de phishing por redirecionamento
Aqui está o ataque que a URL ajuda a prevenir, mas não resolve sozinho. O golpista não falsifica a tela do Google. Ele registra um app OAuth legítimo, com nome convincente, e pede escopos amplos. Depois envia um link como “conecte sua conta para ganhar X” ou “autorize a integração do seu CRM”. O usuário é levado ao domínio verdadeiro do Google, vê uma tela de consentimento real, aprova, e o app do golpista recebe o código e os tokens.
O detalhe grave: depois do consentimento, o app pode continuar acessando os dados por meio do refresh token, e revogar exige ação na conta. A URL nesse golpe está tecnicamente correta, porque o app é do atacante. Por isso verificar a URL sozinha não basta; o que pega o golpe é conferir dono, e-mail, nome e escopos.
Quando uma ferramenta pede para cadastrar uma URL que você não reconhece, a resposta padrão é não. Pode ser um serviço real com documentação confusa, mas também é a forma de inserir um endereço de captura no seu app. Pause e confirme com o fornecedor por canal oficial.
Comparação de cenários: risco e recomendação
| Cenário | Configuração típica | Risco principal | Recomendação |
|---|---|---|---|
| Desenvolvimento local | localhost com porta, app em teste | Resíduo esquecido em app de produção | Aceitável para testar. Separar do app de produção e remover do publicado. |
| App interno de produção | Domínio da empresa em https, público interno | Escopos amplos demais | Preferir este tipo para uso corporativo. Conferir escopos e dono. |
| App publicado externo | Domínio do fornecedor, público externo, verificado | Phishing por consentimento | Exigir verificação, ler a tela e limitar a conta usada. |
| App de terceiro não verificado | URL qualquer, aviso de app não confiável | Captura de tokens e leitura contínua | Não autorizar. Buscar alternativa oficial ou app interno. |
| URL pedida na hora | Domínio desconhecido, cadastro manual | Redirecionamento para servidor do atacante | Não cadastrar sem confirmação no canal oficial. |
Exemplo: agência de marketing em Recife ligando assistente ao Drive do cliente
Uma agência de marketing em Recife gerencia conteúdo para clientes locais. A equipe quer um assistente de IA que leia pastas compartilhadas de fotos e briefings no Drive de cada cliente, resuma reuniões e prepare rascunhos de calendário editorial.
A revisão, antes de ligar a ferramenta, segue esta ordem:
- Dono do projeto Google Cloud. Se é a agência, o app é dela e o controle está em casa.
- Interno ou externo. Como os clientes têm contas Google próprias, um app interno do Workspace da agência não alcança o Drive do cliente. Ou a agência usa um app externo, com o cuidado que isso exige, ou cada cliente autoriza um app dentro do próprio tenant.
- A URL. Se a ferramenta é hospedada pela agência, a URL deve apontar para um domínio da agência, em HTTPS, com caminho exato. Sem http, sem domínio raiz, sem curinga.
- Os escopos. O assistente lê pastas específicas. Se o consentimento pede o Drive de ponta a ponta, revise. O escopo restrito ao que a ferramenta cria é bem mais defensável.
- A tela de consentimento. O nome deve ser o da ferramenta que o cliente reconhece, com e-mail de suporte da agência.
O ponto mais delicado não é a URL. É que a agência acessa dados de terceiros, e isso deve estar coberto no contrato e no consentimento, como trata o guia de segurança e LGPD na implantação de IA. A URL faz a conexão funcionar; a governança faz ela ser aceitável.
Método de revisão em passos
- Abra o app no Google Cloud Console. Localize o projeto e a tela de cliente OAuth. Confira o público e se o app está em teste ou publicado.
- Anote o dono e o e-mail de suporte. Se não for da sua empresa ou de um fornecedor conhecido, pare.
- Verifique as URIs autorizadas. Compare esquema, host, caminho e porta com o que a ferramenta informa. Procure resíduo de localhost e curinga.
- Leia os escopos. Liste o que cada um permite e se há versão mais estreita que atenderia.
- Veja a tela de consentimento como o usuário veria. Nome, logo, e-mail e links devem fazer sentido.
- Teste com uma conta restrita. Antes da conta principal, conecte uma conta de teste e observe o que a ferramenta faz.
- Registre a decisão. Quem autorizou, data, app, escopos e URL. Isso ajuda a revogar rápido se algo der errado.
Checklist rápida
- O dono do app é a minha empresa ou um fornecedor que eu identifico?
- O app é interno do Workspace ou externo publicado? Isso bate com o uso?
- A URL usa https, é de domínio conhecido e tem caminho específico?
- Há localhost ou curinga cadastrado em app de produção?
- Os escopos pedidos são os mínimos para a tarefa?
- A tela de consentimento mostra nome e e-mail que eu reconheço?
- Eu sei como revogar o acesso depois?
Erros comuns
- Focar na URL e ignorar o escopo. URL perfeita com escopo total do Gmail pode ser pior que URL estranha com leitura de uma pasta.
- Aceitar que “o fornecedor pediu para cadastrar” sem conferir. É o vetor do phishing por consentimento. Confirme por canal oficial.
- Deixar localhost no app de produção. Resíduo de teste é risco sem benefício.
- Assumir que app “só interno” é interno. Confira o público no Console. A etiqueta comercial não vale como configuração.
- Usar conta pessoal para dados da empresa. Se a conta é pessoal, revogar e auditar depois fica mais difícil.
Perguntas frequentes
A URL de redirecionamento pode ter parâmetros na query?
Pode haver query, mas ela não pode configurar redirecionamento aberto, segundo a validação do Google. A prática segura é evitar parâmetros variáveis no retorno e manter o caminho fixo. Se a ferramenta exige query, confirme com o fornecedor.
Por que meu app retorna erro de incompatibilidade de redirect URI?
Porque o valor enviado não confere exatamente com uma das URIs cadastradas. Revise barra final, http contra https, presença de www e porta. A documentação trata esse erro como falha de comparação exata.
Posso usar localhost em produção para testes internos?
A documentação permite localhost como exceção de esquema para desenvolvimento. Em produção, os usuários não acessam a máquina onde o servidor roda, então o retorno não chega. Use um domínio próprio em HTTPS para ambientes compartilhados.
O que fazer se a ferramenta pedir uma URL que não reconheço?
Não cadastre enquanto não confirmar. Pergunte ao fornecedor por canal oficial, verifique se o domínio pertence a ele e prefira um app da própria empresa. Esse pedido é exatamente o que um atacante faria.
Autorizar uma vez cede acesso para sempre?
Não necessariamente, mas o app pode guardar um refresh token e continuar acessando enquanto não for revogado. O Google oferece revogação nas configurações da conta.
App interno dispensa verificação?
O público interno restringe os usuários ao Workspace, mas as exigências variam conforme o tipo de escopo. Confira a regra atual na página de verificação de apps OAuth e no Console, porque as exigências mudam. Não assuma que interno significa liberado.
