Skip to main content
Este guia é para o administrador do Google Workspace da sua empresa. Ele mostra como ligar o Google Workspace a uma organização do QX. O trabalho tem duas partes: a equipe de TI cria o cliente OAuth no Google Cloud, e o owner da organização configura o QX. O guia do login com SSO explica as regras que valem para todo provedor de identidade.

​
O que o QX oferece

  • A pessoa entra no QX pelo login com SSO no Google, com o protocolo OIDC. O QX nunca vê a senha.
  • O QX aceita só as contas do domínio da empresa. O owner digita o domínio na conexão SSO, e o QX confere o claim hd a cada login.
  • O QX não recebe o provisionamento de usuários do Google Workspace. O Google documenta o provisionamento só para os apps do catálogo dele.
  • O token do Google não traz grupos. O papel vem do QX: a pessoa nova entra como operador, e o owner muda o papel em Usuários.
  • O owner pode ligar a vinculação por e-mail. Com ela, o primeiro login com SSO liga a pessoa ao usuário do QX que tem o mesmo e-mail.
  • O owner pode ligar a criação no primeiro login. Com ela, o primeiro login com SSO de uma pessoa do domínio sem usuário no QX cria um operador.
  • O owner liga o SSO obrigatório para a organização inteira. Com a regra ligada, ninguém da organização entra com senha, nem o owner.
  • Quando a organização exige a verificação em duas etapas, a pessoa digita o código do app autenticador do QX depois do login no Google.
  • A sessão aberta pelo login com SSO vence no prazo que o owner escolhe, de 1 a 8 horas depois do login. Ela não se prorroga.
  • O owner remove a conexão SSO para trocar de cliente OAuth ou de domínio, e depois configura uma nova.
O QX não oferece SAML.

​
A ordem do trabalho

Faça os passos nesta ordem:
  1. A equipe de TI cria o cliente OAuth no Google Cloud.
  2. O owner configura a conexão SSO no QX.
  3. O owner faz o teste de login.
  4. O owner habilita o login com SSO.
  5. O owner liga o SSO obrigatório.
Antes de começar, confira duas coisas:
  • A conta Google do owner tem o mesmo e-mail do usuário do owner no QX.
  • O owner sabe o domínio das contas da empresa no Google Workspace, como empresa.com.br. O valor do hd para uma conta de um domínio secundário da empresa: não conferido em fonte oficial.

​
Os endereços do QX

O owner vê os endereços em Configurações › SSO, no quadro Endereços para o provedor de identidade. Cada endereço tem um botão Copiar. A URL de login só aparece depois que o owner salva a conexão SSO. O quadro não mostra a Base URL do provisionamento de usuários, porque o Google Workspace não usa o provisionamento. A URI de redirecionamento é esta:

​
1. Crie o cliente OAuth no Google Cloud

Faça estes passos no Google Cloud console, num projeto da organização Google Cloud da empresa:
  1. Configure o público do app com o tipo de usuário Internal. Com esse tipo, o Google aceita só as contas da organização da empresa.
  2. Abra a página Clients e clique em Create Client.
  3. Escolha o tipo Web application.
  4. Em Authorized redirect URIs, cole a URI de redirecionamento do QX.
  5. Clique em Create.
  6. Abra o cliente. O client ID e o client secret ficam no topo da página. Copie os dois.
O QX pede os escopos openid, email e profile. Um app que só as pessoas da organização Google Workspace da empresa usam não precisa da verificação do Google. Entregue o client ID e o client secret ao owner por um canal seguro, como um gerenciador de senhas.

​
2. Configure a conexão SSO no QX

O owner faz estes passos no QX:
  1. Abra Configurações › SSO e clique em Configurar conexão SSO.
  2. Escolha Google Workspace e clique em Continuar.
  3. Em Endereço do provedor de identidade, o formulário mostra https://accounts.google.com. Esse endereço é o mesmo para toda empresa.
  4. Em Domínio da empresa, digite o domínio das contas da empresa, como empresa.com.br. O QX guarda o domínio em letras minúsculas e sem espaços. O domínio fica fixo depois que o owner salva a conexão.
  5. Em Client ID e Client secret, cole os valores do passo 1.
  6. Em Autenticação do cliente, mantenha Basic (client_secret_basic). O Google aceita também Post (client_secret_post).
  7. Em Verificação em duas etapas, o formulário mostra só Pelo app autenticador do QX. A seção Verificação em duas etapas deste guia explica a opção.
  8. Em Duração da sessão com SSO, escolha de 1 a 8 horas. O padrão é 8 horas. Prefira uma duração curta, como explica a seção Duração da sessão.
  9. Se os usuários do QX já existem, marque Vincular usuários do QX pelo e-mail.
  10. Para que o primeiro login crie o usuário de uma pessoa nova do domínio, marque Criar usuário no primeiro login.
  11. Clique em Salvar conexão SSO. Se o login do owner tem mais de 15 minutos, o QX pede a senha.
O formulário não mostra Papel das pessoas, porque o papel vem do QX. Depois de salvar, o quadro Endereços para o provedor de identidade mostra a URL de login. Uma mudança na vinculação por e-mail ou na criação no primeiro login encerra as sessões abertas com SSO. Faça a mudança fora do horário de trabalho.

​
3. Faça o teste de login

  1. Em Configurações › SSO, o owner clica em Testar login.
  2. O QX abre o Google. O owner entra com a própria conta do Google Workspace.
  3. O QX mostra “Teste de login aprovado. A conexão SSO está verificada.”
O teste liga a conta Google do owner ao usuário do owner no QX. O teste pede duas coisas:
  • A conta é do domínio da conexão. Com uma conta de outro domínio, o teste falha com “A conta que você usou no provedor de identidade é de outra empresa.”
  • O e-mail da conta Google é igual ao e-mail do owner no QX.

​
4. Habilite o login com SSO

  1. Em Configurações › SSO, o owner clica em Habilitar login com SSO. Se o login do owner tem mais de 15 minutos, o QX pede a senha.
  2. Uma pessoa que não é owner abre a URL de login do QX e confere o login.
A pessoa entra no QX pela URL de login. A URL leva ao Google e volta ao QX com a pessoa identificada. Guarde a URL nos favoritos do navegador. O Google documenta o atalho no inicializador de apps só para um app SAML personalizado. Um atalho para o app OIDC do QX: não conferido em fonte oficial.

​
5. Ligue o SSO obrigatório

  1. Em Configurações › SSO, o owner clica em Ligar SSO obrigatório.
  2. O owner confere o aviso e clica em Ligar SSO obrigatório de novo. Se o login do owner tem mais de 15 minutos, o aviso pede a senha.
Cada sessão aberta com senha na organização termina, inclusive a do owner. A partir daí, todo usuário da organização entra pelo login com SSO.

​
Verificação em duas etapas

A conexão SSO do Google Workspace tem uma opção só: Pelo app autenticador do QX. A opção vale quando a organização exige a verificação em duas etapas.
  • Depois do login no Google, a pessoa digita o código do app autenticador do QX. No primeiro login, a pessoa cadastra o app.
  • A pessoa tem 15 minutos para terminar. Depois desse prazo, ela entra de novo pelo Google.
Uma pessoa que entra com SSO também cadastra o app autenticador em Segurança da conta. Antes do cadastro, o QX pede um login no Google com a mesma conta. O Google pode aceitar a sessão que a pessoa já tem no Google, sem pedir a senha de novo. Para trocar de app, a pessoa pede o reset do segundo fator a outro owner ou ao suporte do QX. O Google não aceita um pedido de novo login. Por isso, quando o login com SSO tem mais de 15 minutos, a confirmação de identidade antes de um ato sensível pede o código do app autenticador do QX. A confirmação por código exige o app já cadastrado. A pessoa sem app cadastra o app antes, em Segurança da conta.

​
Duração da sessão

O owner escolhe a duração da sessão com SSO em Editar conexão SSO, de 1 a 8 horas. Depois desse prazo, a pessoa entra de novo pelo Google. Um prazo menor encurta também as sessões abertas, contado do login. Um prazo maior vale só para os logins seguintes. A confirmação de identidade não muda o prazo. O Google não avisa o QX quando suspende ou exclui uma pessoa. As regras de duração de sessão do Google também não valem para um app que entra pelo OAuth, como o QX. A pessoa suspensa perde o acesso aos serviços do Google da empresa e continua com a sessão aberta no QX até a sessão vencer. A recusa de um novo login com SSO dessa pessoa pelo Google: não conferido em fonte oficial. Por isso, escolha uma duração curta.

​
Como o QX trata cada pessoa

  • O QX reconhece a pessoa pelo sub do Google. O Google nunca reusa nem muda esse identificador.
  • O QX aceita só a conta com o claim hd igual ao domínio da conexão. Uma conta pessoal com um e-mail do domínio da empresa não tem hd, e o QX recusa essa conta.
  • Com Criar usuário no primeiro login, o primeiro login de uma pessoa do domínio sem usuário no QX cria um operador. O Google precisa confirmar o e-mail, com email_verified true ou "true".
  • Com Vincular usuários do QX pelo e-mail, o primeiro login liga a pessoa ao usuário da organização com o mesmo e-mail, quando o Google confirma o e-mail. O QX nunca liga um owner pelo e-mail. O owner faz o teste de login.
  • Sem as duas opções, o QX recusa a pessoa que ainda não tem vínculo, com “O QX não encontrou o seu usuário.”
  • O owner muda o papel em Usuários, e o login com SSO não muda o papel.
  • Para desativar uma pessoa, o owner desativa o usuário em Usuários. Todas as sessões do usuário terminam no mesmo instante. A suspensão da pessoa no Google não desativa o usuário no QX.
  • Depois do vínculo, uma troca de e-mail no Google não bloqueia o login com SSO. A página do usuário mostra o e-mail do Google quando ele é diferente do e-mail no QX.

​
Troque o client secret

  1. No Google Cloud console, a equipe de TI abre o cliente OAuth e cria um client secret novo (não conferido em fonte oficial).
  2. O owner abre Editar conexão SSO, cola o secret novo em Client secret e clica em Salvar conexão SSO.
Um client secret novo encerra todas as sessões abertas com SSO na organização. Faça a troca fora do horário de trabalho.

​
Quando o Google cai

Com o SSO obrigatório ligado, ninguém entra no QX enquanto o Google está fora do ar. As sessões abertas continuam até vencer.
  1. Se um owner ainda tem uma sessão aberta, ele clica em Desligar SSO obrigatório em Configurações › SSO. O QX não pede confirmação, então isso funciona com o Google fora do ar.
  2. Se nenhum owner tem sessão aberta, peça ao suporte do QX. O suporte desliga o SSO obrigatório e grava o motivo no log de auditoria.
  3. Quem não tem senha clica em Esqueceu sua senha? na tela de login e cria uma senha.
  4. Quando o Google volta, o owner clica em Ligar SSO obrigatório.
A confirmação de identidade pelo código do app autenticador não passa pelo Google, então ela funciona com o Google fora do ar.

​
Remova a conexão SSO

Para trocar de cliente OAuth ou de domínio, o owner remove a conexão SSO e configura uma nova. A conexão nova tem outra URL de login.
  1. Em Configurações › SSO, o owner clica em Remover conexão. Se o login do owner tem mais de 15 minutos, o QX pede a senha ou a confirmação de identidade.
  2. O owner confere o aviso e clica em Remover conexão de novo.
A remoção tem estes efeitos:
  • As sessões abertas com SSO terminam, inclusive a do owner.
  • O login com SSO e o SSO obrigatório param. As pessoas entram com senha.
  • O QX apaga as identidades externas.
  • Os usuários continuam no QX. Quem só entrava com SSO cria uma senha em Esqueceu sua senha?, na tela de login.
Se nenhum owner consegue entrar, peça ao suporte do QX. O suporte remove a conexão e grava o motivo no log de auditoria.

​
As mensagens de recusa

​
Fontes