Como separar autenticação de usuário, conector e agente numa UI própria do Gemini Enterprise

- Leitura
- 7 min
- Tabelas
- 1
- Fontes
- 1
Um guia publicado pelo Google Cloud em 20 de novembro de 2026 destrincha as três camadas de autenticação que o app pronto do Gemini Enterprise esconde, e que qualquer UI customizada precisa reimplementar na mão.
Quem usa o aplicativo web padrão do Gemini Enterprise nem percebe a engenharia de identidade rodando por trás: o funcionário loga com Google Identity ou Workforce Identity Federation (Microsoft Entra ID, Okta), os resultados de busca já respeitam as ACLs documento a documento, e o popup de login de um conector federado ou agente customizado aparece sozinho na hora certa.
O problema começa quando a empresa decide embutir o Gemini Enterprise num portal interno, intranet ou sistema de linha de negócio com UI própria. Nesse cenário, descrito num guia técnico publicado pelo Google Developers Blog em 20 de novembro de 2026 e assinado por Neeraj Agrawal, forward deployed engineer do Google Cloud↳Google Cloud13 conteúdosPrograma da Google Cloud no Brasil projeta formar de forma gratuita 30 mil universitáriosDev (Back & Front) · mar 2026Google Cloud OnBoard capacita estudantes e desenvolvedores de TIGestão Dev & TI · mai 2019Desenvolvedores poderão participar de treinamento gratuito do Google CloudGestão Dev & TI · mai 2019Ver tudo em DevSecOps →, a UI customizada ("Customer UI") e o backend↳Back-end49 conteúdosIntegração front-end com backend: 7 decisões que evitam caos entre APIs, BFF e GraphQLDev (Back & Front) · abr 2026Como criar uma FAKE API REST para testes — JSONPlaceholderDev (Back & Front) · set 2025Construindo um aplicativo de bate-papo de IA simples com Spring AI e AngularDev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → dela ("Customer BE") passam a chamar a StreamAssist API diretamente. E as três camadas de autenticação que o app pronto resolvia sozinho viram responsabilidade de quem construiu a integração.
Camada 1: quem está autenticando no StreamAssist
A primeira decisão é se a chamada à StreamAssist API representa um usuário humano específico ou um serviço compartilhado sem identidade individual. O guia descreve três padrões, todos sem chave de Service Account em disco:

| Padrão | Quando usar | Fluxo |
|---|---|---|
| 1A: Google Identity | Funcionário loga com Google Workspace/Cloud Identity | Login OAuth 2.0 com escopo do Google Cloud gera um token de acesso enviado direto como Bearer para a StreamAssist API |
| 1B: Workforce Identity Federation | Funcionário loga via Entra ID ou Okta, e o engine já usa WIF | O Customer BE troca o token OIDC do IdP externo no Google Security Token Service (STS) contra o Workforce Pool Provider já configurado |
| 1C: Workload Identity Federation | Bot de backend, webhook de Slack/Teams, portal sem usuário individual | O Customer BE troca um JWT de máquina (client credentials do IdP) no Google STS contra um Workload Identity Pool do projeto |
Todo principal que chama a StreamAssist API precisa do papel IAM Discovery Engine User no projeto GCP. Para os padrões 1A e 1B, o usuário (ou o grupo do Workforce Pool) também precisa de uma licença de usuário do Gemini Enterprise ativa no Admin Console, o que costuma ser o detalhe que trava integrações em produção quando passa despercebido no checklist.
A escolha entre os padrões não é só estética. Como o padrão 1C autentica uma máquina, e não uma pessoa, todo request chega ao Gemini Enterprise com a mesma identidade de workload. Isso serve bem para bots não personalizados sobre uma base de conhecimento compartilhada, mas inviabiliza ACLs por documento, conectores 3LO por usuário e agentes customizados com permissão restrita, que dependem de saber exatamente quem está perguntando.
Camada 2: conectores federados e o Keystore
Com o usuário autenticado na StreamAssist API, a próxima camada entra em cena quando o engine tem Federated Connectors ativos: Google Drive, SharePoint Online, Jira, Box, ServiceNow, Confluence. Esses conectores pesquisam a API de terceiros em tempo real e aplicam a permissão daquele usuário específico, o que exige OAuth de três pernas (3LO) por pessoa, não por aplicação.
O app pronto do Gemini Enterprise resolve isso com um botão "Connect" embutido. Uma UI própria não tem esse botão, então o guia descreve um fluxo de 11 passos que o Customer BE precisa orquestrar:
- Descobrir os conectores do engine e checar no Keystore gerenciado pelo Gemini Enterprise se o usuário já tem token válido para cada um.
- Quando falta consentimento, abrir a URL de autorização num popup (3P Auth Server).
- Após o login, o redirect cai na página
/oauth-redirectdo GE FE Server, que repassa a URL de callback (código de autorização e state) para a Customer UI viapostMessagedo navegador e fecha o popup. - A Customer UI encaminha esse callback ao Customer BE, que troca o código pelo token no endpoint de terceiros e salva o refresh token dentro do Keystore do próprio Gemini Enterprise.
- A partir daí, o Customer BE inclui o data store do conector nas chamadas à StreamAssist API, e as buscas passam a cobrir aquele sistema de terceiros.
O ponto que mais derruba quem monta essa integração pela primeira vez é o redirect fixo: o endpoint /oauth-redirect do GE FE Server, por padrão, só envia o postMessage para a origem do app web embutido do Gemini Enterprise. Uma UI própria rodando em domínio customizado precisa pedir à equipe do Gemini Enterprise para habilitar a flag de origem customizada, senão o passo 7 do fluxo simplesmente não entrega o callback de volta.
Camada 3: OAuth por ferramenta em agentes ADK customizados
A terceira camada aparece quando a UI não se limita a buscar documentos: ela registra um agente ADK customizado, publicado no Vertex AI↳Inteligência artificial440 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025IA generativa e a urgência de reconstruir nossa relação com a verdadeAI · jun 2025Ver tudo em AI → Agent Engine, que orquestra várias APIs corporativas (Google Drive e SharePoint Online, por exemplo) num mesmo assistente. Aqui o guia descarta explicitamente a abordagem óbvia.
Anexar uma configuração estática de OAuth direto no registro do agente raiz bloqueia o agente inteiro antes mesmo da primeira interação. Se o assistente fala com Drive e SharePoint, o usuário é forçado a logar nos dois mesmo para fazer uma pergunta genérica de política interna que não toca nenhum dos dois. Além disso, esse OAuth de raiz foi desenhado pensando no app web embutido, não em prompts de autorização específicos por ferramenta via StreamAssist API.
A solução proposta tem três passos de configuração:
- Isolar o OAuth na ferramenta, não no agente: ferramentas que não precisam de login rodam como funções Python normais; as que tocam API protegida (SharePoint, Drive) são embrulhadas em
AuthenticatedFunctionTooldo ADK com umGcpAuthProviderapontando para o Auth Provider do GCP Auth Manager. - Ligar Agent Identity no deploy: o Root Router Agent e seus sub-agentes sobem ao Vertex AI Agent Engine com Agent Identity ativado, o que dá ao agente uma identidade SPIFFE própria. Essa identidade precisa do papel IAM
Agent Identity Service Agentpara buscar tokens no Token Vault do GCP Auth Manager. - Cadastrar o Auth Provider 3LO no Console: para cada app OAuth de terceiro (SharePoint, Google Workspace), configura-se a Default Continue URI como
<website-url>/validateUserIdna Customer UI, e a URI de redirect/oauthcallbackdo GCP Auth Manager é registrada no app do Entra ID ou do terceiro correspondente.
Na prática, isso muda o momento em que o popup de login aparece: só quando o usuário efetivamente aciona uma ferramenta protegida, não no início da conversa.
O guia descreve 19 passos para esse fluxo completo, mas o resumo é que, na primeira chamada protegida, o Token Vault dá cache miss, devolve uma URL de autorização que sobe de volta pela cadeia (Agent Engine → GE Server → Customer BE → Customer UI), o usuário aprova no popup, o Customer BE valida a sessão via Validate User Authorization API no GE Server, e o GCP Auth Manager finaliza salvando o token no Token Vault. Na sequência, a mesma query é reexecutada automaticamente, agora com cache hit, sem novo popup.

O que isso muda pra quem constrói
Para times que já embutem busca corporativa numa intranet ou portal interno, o recorte prático é escolher o padrão certo em cada camada em vez de tentar fazer tudo com uma única credencial. Um bot de FAQ compartilhado cabe no padrão 1C; um copiloto com documentos restritos por cargo exige 1A ou 1B. Um agente ADK que fala com múltiplos sistemas corporativos só escala em produção se o OAuth for por ferramenta, e não por registro do agente, senão a experiência fica pior que a do app pronto que ele está tentando substituir.
O guia não resolve tudo sozinho: ele assume que o engine do Gemini Enterprise já está configurado com os provedores de identidade corretos, e que a equipe de produto tem orçamento de engenharia para implementar três fluxos OAuth distintos, cada um com seu próprio componente de popup e troca de token. Para quem quer ver o código de referência antes de implementar do zero, o próprio post do Google Cloud aponta para o repositório gemini-enterprise-custom-ui-auth no GitHub, com scripts Python, comandos curl e UIs de teste interativas para as três partes do fluxo.
Fonte: Google Developers Blog
Highlights
- Google publica guia em 20 de novembro de 2026 sobre três camadas de autenticação do Gemini Enterprise com UI customizada
- Padrão 1A usa Google Identity, 1B usa Workforce Federation (Entra ID ou Okta), 1C usa Workload Identity para bots sem identidade pessoal
- Conectores federados precisam de OAuth por pessoa em popup de três pernas; Keystore gerenciado pela plataforma armazena refresh tokens
- Agentes ADK customizados precisam de Agent Identity ativado e GcpAuthProvider por ferramenta, não OAuth estático no agente raiz
- Repositório gemini-enterprise-custom-ui-auth no GitHub tem código de referência com scripts Python, curl e UIs de teste interativas
Este artigo foi escrito por Alan Andrade, colunista de inteligência artificial. Conteúdo produzido por agente de IA da redação iMasters, sob revisão editorial humana. Saiba como produzimos no expediente.
Google adiciona políticas semânticas de governança para agentes de IA no Gemini
O Google lançou em preview um sistema que julga, em linguagem natural, cada chamada de ferramenta que um agente propõe antes de ela rodar. A ideia é pegar o que IAM e prompts não conseguem pegar: o pedido que faz sentido técnico mas quebra uma regra de negócio.














