SSO com Google Workspace: ligando o login da sua empresa ao CollaborAI
O passo a passo para o administrador criar o projeto no Google Cloud, configurar o cliente OAuth e liberar Gmail e Calendar — o que cada etapa habilita e os erros que mais aparecem no caminho.
Quando uma empresa coloca o time inteiro para usar IA, duas perguntas aparecem quase sempre na mesma reunião: “todo mundo vai ter que criar mais uma senha?” e “o agente vai conseguir mexer no meu e-mail e na minha agenda?”.
As duas se resolvem no mesmo lugar — um projeto no Google Cloud da sua própria organização. Este guia é o passo a passo que o administrador executa uma vez, do zero até as credenciais prontas.
O que a configuração habilita
Login com a conta corporativa. As pessoas entram no CollaborAI com a mesma conta Google que já usam para o e-mail da empresa. Não há senha nova, não há lista de usuários paralela — e, quando alguém é desligado no Google Workspace, o acesso ao CollaborAI cai junto, sem depender de ninguém lembrar de remover a conta.
Gmail e Calendar nos agentes. Depois do login, cada pessoa autoriza individualmente os conectores. A partir daí os agentes passam a resumir threads, responder e-mails, criar eventos e consultar disponibilidade antes de agendar — sempre com a permissão de quem autorizou, nunca com um acesso global à caixa de e-mails da empresa.
São dois fluxos OAuth diferentes, atendidos pelo mesmo cliente do Google Cloud. É por isso que, mais adiante, você vai cadastrar quatro URIs de redirecionamento: duas do login e duas dos conectores, cada par cobrindo o ambiente de homologação e o de produção.
Antes de começar
- Acesso administrativo ao Google Cloud Platform da organização.
- Permissão para criar projetos e configurar a tela de permissão OAuth.
- O subdomínio da sua empresa já definido com o time do CollaborAI — é o
suaempresaque aparece nas URLs deste guia. Troque por ele em todos os endereços.
Passo 1 — Criar o projeto no Google Cloud
Acesse o console.cloud.google.com, selecione a organização da empresa e crie um projeto novo com o nome CollaborAI. Confirme que ele está dentro da organização correta e aguarde o provisionamento.
Passo 2 — Abrir a tela de permissão OAuth
No menu lateral, vá em APIs e Serviços › Tela de permissão OAuth.
Se todas as pessoas que vão usar o CollaborAI têm conta na sua organização do Workspace, escolha o tipo de usuário interno. O consentimento fica restrito ao seu domínio e o aplicativo não precisa passar pelo processo de verificação do Google.
Passo 3 — Criar o cliente OAuth
Ainda no projeto CollaborAI, abra a seção Clientes e crie um cliente do tipo aplicativo da Web com o nome CollaborAI.
Em Origens JavaScript autorizadas:
https://login.suaempresa.dev.collaborai.io
https://login.suaempresa.collaborai.ioEm URIs de redirecionamento autorizados:
https://login.suaempresa.dev.collaborai.io/oauth2/idpresponse
https://login.suaempresa.collaborai.io/oauth2/idpresponse
Repare no final do endereço: idpresponse, com “se”. É o erro de digitação que mais aparece
nessa etapa, e o sintoma é um redirect_uri_mismatch na hora de testar o login.
Passo 4 — Ativar as APIs do Gmail e do Calendar
Vá até a Biblioteca de APIs e ative as duas:
Faça isso antes do passo seguinte: os escopos de Gmail e Calendar só aparecem na lista depois que as APIs correspondentes estão ativadas no projeto.
Passo 5 — Conceder os escopos
Volte ao Google Auth Platform › Acesso a dados e clique em Adicionar ou remover escopos.
Use o filtro por API para encontrar cada um e marque exatamente estes cinco:
| Escopo | Para que serve |
|---|---|
gmail.readonly | Ler a caixa do próprio usuário: resumir threads, buscar mensagens, responder perguntas |
gmail.send | Enviar e responder e-mails escritos com o assistente |
gmail.modify | Organizar a caixa a pedido do usuário: etiquetas, arquivar, marcar |
calendar.events | Criar, listar, atualizar e excluir eventos |
calendar.readonly | Consultar disponibilidade antes de agendar, evitando conflitos |
Dois cuidados que valem a leitura atenta:
- Nem um a mais, nem um a menos. A lista precisa bater exatamente com a que o CollaborAI pede na hora do consentimento. Escopo faltando derruba as ferramentas que dependem dele; escopo sobrando faz a plataforma pedir mais permissão do que usa.
- Não marque os superconjuntos.
https://mail.google.com/dá acesso total à caixa, e o escopocalendarcompleto permite gerenciar calendários inteiros. Nenhum dos dois é necessário: os agentes só mexem em mensagens e eventos, e o princípio aqui é pedir o mínimo que faz o trabalho.
Além desses cinco, o consentimento inclui openid, email e profile — a identificação básica de
quem está entrando, sem acesso a conteúdo.
Passo 6 — Adicionar as URIs dos conectores
Volte em Clientes e acrescente mais duas URIs de redirecionamento, agora apontando para a API:
https://api.suaempresa.dev.collaborai.io/connectors/oauth/google/callback
https://api.suaempresa.collaborai.io/connectors/oauth/google/callback
A diferença entre elas é o que cada fluxo faz. As de login. devolvem a pessoa autenticada para a
plataforma; as de api. recebem a autorização individual de Gmail e Calendar. Faltando as últimas,
o login funciona e os conectores falham — um sintoma que costuma custar meia hora de investigação.
Passo 7 — Enviar o Client ID e o Client Secret
Com tudo configurado, abra o cliente CollaborAI e copie os dois valores:
| Dado | O que é |
|---|---|
| Client ID | Identificador do cliente OAuth gerado pelo Google Cloud |
| Client Secret | Chave secreta associada ao Client ID, usada na autenticação |
Envie os dois pelo canal seguro combinado com a equipe do CollaborAI — nunca por e-mail comum ou mensageiro. O Google mostra a chave secreta uma única vez; se ela se perder, gere outra na mesma tela.
Do nosso lado, essas credenciais entram em um cofre de parâmetros criptografado da AWS em modo write-only: a plataforma grava e usa, mas não existe nenhum endpoint que leia a chave de volta — nem para o administrador. O painel mostra apenas se está configurada e desde quando.
O checklist
- Projeto CollaborAI criado dentro da organização
- Tela de permissão OAuth configurada (tipo interno, se todos são do seu domínio)
- Cliente OAuth criado, com as duas origens JavaScript
- Duas URIs de redirecionamento de login (
/oauth2/idpresponse) - Gmail API e Google Calendar API ativadas
- Cinco escopos concedidos em Acesso a dados
- Duas URIs de redirecionamento dos conectores (
/connectors/oauth/google/callback) - Client ID e Client Secret enviados pelo canal seguro
Os erros que mais aparecem
| Sintoma | Causa provável |
|---|---|
redirect_uri_mismatch no login | URI digitada como idpresponde, ou faltando o https:// |
| Login funciona em produção e falha na homologação | Só as URIs de produção foram cadastradas — são dois ambientes |
| Os escopos de Gmail e Calendar não aparecem na lista | As APIs do passo 4 não foram ativadas nesse projeto |
| Login entra normal, mas o agente não lê e-mail nem agenda | Faltam as URIs de api. do passo 6, ou algum escopo do passo 5 |
| Tela de consentimento pedindo permissão demais | Foi marcado https://mail.google.com/ ou o escopo calendar completo |
Terminado o passo a passo, o resto é com a nossa equipe: o provedor de identidade é registrado no ambiente da sua empresa, o login é testado primeiro em homologação e depois em produção. Para as pessoas do time, o efeito final é o mais simples possível — abrir o endereço da empresa, clicar em entrar com a conta corporativa e começar a trabalhar. E, quando alguém pedir ao agente para responder um e-mail ou marcar uma reunião, o Google vai perguntar, uma única vez, se ela autoriza.
Se a tela de login também vai receber o logotipo e o nome da sua organização, vale configurar as duas coisas na mesma janela: a pessoa passa a abrir uma tela com a marca da empresa e entrar com a conta da empresa, sem nada que lembre um fornecedor no meio do caminho.
