Guias

SSO com Google Workspace

Passo a passo para configurar Google Sign-In como método de login: pré-requisitos, autorização da app, restrição de domínio, fallback de senha e revogação.

Atualizado em 03 de maio de 2026

Pré-requisitos

Antes de começar, garanta:

Domínio Google Workspace verificado e operacional (ex.: acme.com). Contas pessoais @gmail.com não são aceitas — o SSO exige hosted domain (hd) presente no token.
Acesso de admin ao Google Workspace para criar credencial OAuth no Google Cloud Console.
Acesso de admin ao tenant Interaflow.
Usuários já cadastrados no tenant. A autenticação Google na fase atual exige pré-provisionamento — usuários ainda não cadastrados recebem 403 user_not_provisioned no login. JIT está fora do escopo da fase 1.
Variável de ambiente GOOGLE_OAUTH_CLIENT_ID configurada no backend do Interaflow (cuidada pela operação Interaflow ou pelo time de infra). Se ausente, o endpoint retorna 503 google_sso_not_configured.

O usuário clica “Entrar com Google” na tela de login, o navegador faz o Google Sign-In, o frontend envia o id_token resultante para o backend Interaflow, e o backend valida assinatura, audiência, e-mail verificado e domínio antes de emitir o JWT do Interaflow.

Usuário ─► Google Sign-In ─► id_token ─► /api/v1/auth/google ─► JWT Interaflow

Passo a passo

1. Crie a credencial OAuth no Google

No Google Cloud Console:

Vá em APIs & Services → Credentials.
Crie uma OAuth 2.0 Client ID do tipo Web application.
Nas Authorized JavaScript origins, inclua a URL do dashboard Interaflow do seu tenant.
Anote o Client ID gerado — é o valor que precisa estar em GOOGLE_OAUTH_CLIENT_ID no backend.

2. Habilite SSO Google no tenant

Na UI do Interaflow, em Configurações → SSO, ative Google:

Habilitar Google SSO — liga o método para o tenant.
Domínios autorizados — lista de domínios Workspace cujas contas podem se autenticar (ex.: acme.com, acme-subsidiaria.com). O domínio é checado contra a claim hd do id_token. Domínios fora da lista resultam em 403 domain_not_authorized.
Forçar SSO (opcional) — se ativado, bloqueia o login por senha para todos os usuários do tenant (exceto superuser). Use quando a política da empresa for “só Google daqui pra frente”.

3. (Opcional) Garanta o pré-provisionamento dos usuários

Como JIT não está disponível na fase 1, todos os usuários esperados precisam existir no tenant antes do primeiro login Google. Cadastre manualmente em Configurações → Usuários ou via importação. Use o mesmo e-mail que o usuário tem no Google Workspace — o vínculo é feito por e-mail.

Em uma janela anônima, acesse a URL do tenant e clique em “Entrar com Google”. O fluxo esperado:

Popup do Google Sign-In abre.
Usuário escolhe a conta Workspace autorizada.
Dashboard abre logado.

Se algo falhar, o backend devolve um detail específico — veja a tabela de erros adiante.

Mapeamento de usuário Google → User do tenant

A primeira autenticação cria o vínculo. A partir daí, ele é estável:

O backend busca o User pelo e-mail retornado no token Google.
Se o User existe e ainda não tem google_sub populado, o backend vincula a conta Google àquele User (auth_provider passa a google se o User não tinha senha cadastrada).
Em logins futuros, o backend exige que o google_sub recebido bata com o google_sub armazenado. Diferenças resultam em 401 google_account_mismatch — protege contra alguém criar uma conta Google nova com o mesmo e-mail do User para se passar pela pessoa.

Fallback para senha

Por padrão, SSO e senha coexistem no tenant. Um usuário pode entrar por qualquer um dos dois métodos — útil em transições e em contas de serviço.

Se o tenant tem Forçar SSO ativado, o login por senha é bloqueado para todos os usuários comuns (mesmo os com senha cadastrada). Apenas superuser continua podendo usar senha — é uma escotilha deliberada para casos onde o SSO está fora do ar e é preciso entrar para corrigir.

Revogação

Para revogar o acesso de uma pessoa:

Desativar o User no Interaflow. Preferido. Bloqueia tanto SSO quanto senha imediatamente.
Remover a conta do Google Workspace. O Google deixa de emitir id_token válido para essa conta. O User pode permanecer cadastrado no tenant até ser revisado.
Limpar o vínculo (google_sub). Útil quando a pessoa precisa revincular com uma conta Google diferente — peça ao admin Interaflow para desvincular; a próxima autenticação vai criar o novo vínculo com a conta nova.

Erros comuns e como resolver

Erro	Causa provável	Como corrigir
503 google_sso_not_configured	`GOOGLE_OAUTH_CLIENT_ID` não está setado no backend.	Solicite ao time de infra para configurar a variável e reiniciar o backend.
401 invalid_google_token	Token Google adulterado, vencido ou de Client ID diferente.	Refaça o login. Se persistir, confirme que o Client ID na app de frontend bate com o do backend.
401 email_not_verified	A conta Google não tem o e-mail verificado.	Verifique o e-mail no Google Workspace.
403 sso_not_enabled_for_tenant	SSO Google não está ativado no `TenantSettings` desse tenant.	Habilite em Configurações → SSO.
403 domain_not_authorized	Domínio do `hd` não está na lista de domínios autorizados, ou conta é `@gmail.com` pessoal.	Adicione o domínio na lista, ou confirme que a pessoa está usando a conta Workspace correta.
403 user_not_provisioned	E-mail Google não corresponde a nenhum User cadastrado no tenant.	Cadastre o User antes do primeiro login.
401 user_inactive	User existe mas está marcado como inativo.	Reative o User em Configurações → Usuários.
401 google_account_mismatch	Conta Google diferente da que vinculou inicialmente está tentando entrar com o mesmo e-mail.	Pessoal: confirme que está usando a conta certa. Caso de troca legítima de conta: peça desvínculo ao admin.
403 sso_only_enforced	Login por senha tentado em tenant com Forçar SSO ativo.	Use o login Google. Superuser pode continuar entrando por senha.

Boas práticas

Comece sem Forçar SSO. Habilite Google primeiro, valide com toda a equipe, e só depois ative Forçar SSO.
Mantenha um superuser de socorro. Pelo menos uma conta superuser com senha forte e MFA (no provedor de identidade dela), para recuperar acesso se o Google sair do ar.
Documente o domínio para a equipe. Avise os usuários de qual conta Google usar (@acme.com, não a pessoal).
Audite logins por SSO. O log de atividade registra login_google por usuário; revise periodicamente.

Limites conhecidos

Sem JIT (Just-In-Time provisioning) na fase 1. Usuários precisam existir no tenant antes de logar via Google.
Apenas Google Workspace. Outros provedores (Microsoft, Okta, Azure AD) não estão suportados por enquanto.
hd é obrigatório. Contas @gmail.com pessoais sempre resultam em domain_not_authorized, mesmo que o e-mail esteja na lista de Users cadastrados.