> ## Documentation Index
> Fetch the complete documentation index at: https://developers.useqx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Login com SSO pelo Google Workspace

> Como a equipe de TI liga o Google Workspace ao QX: o cliente OAuth, o domínio da empresa, a verificação em duas etapas e o SSO obrigatório.

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](/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**.

| Endereço no QX | Campo no Google |
| - | - |
| URI de redirecionamento | **Authorized redirect URIs**, no cliente OAuth |
| URL de login | Nenhum campo. A pessoa guarda a URL de login nos favoritos do navegador. |

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:

```text theme={null}
https://app.useqx.com/sso/callback
```

## 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

| Mensagem que a pessoa vê | O que a equipe de TI confere |
| - | - |
| O prazo para terminar o login acabou. Entre de novo pelo provedor de identidade. | A pessoa digita o código do app autenticador do QX em até 15 minutos depois do login no Google. |
| O seu usuário do QX é owner. Para usar o login com SSO, faça o teste de login em Configurações > SSO. | O owner faz o teste de login. O QX nunca liga um owner pelo e-mail. |
| O seu acesso ao QX está desativado. | O estado do usuário em **Usuários**, no QX. |
| O QX não encontrou o seu usuário. | O domínio da conta Google e o **Domínio da empresa** da conexão. O e-mail da pessoa no Google e no QX. As opções **Vincular usuários do QX pelo e-mail** e **Criar usuário no primeiro login**. |
| A conta que você usou no provedor de identidade é de outra empresa. | No teste de login, o owner entra com uma conta do domínio da conexão. |
| O provedor de identidade não respondeu. | O status do Google. Tente de novo em alguns minutos. |
| Não foi possível entrar com SSO. | O client ID, o client secret, a **Autenticação do cliente** e a URI de redirecionamento do cliente OAuth. |

## Fontes

* Google, [OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect).
* Google, [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server).
* Google, [Manage app audience](https://support.google.com/cloud/answer/15549945).
* Google, [When verification is not needed](https://support.google.com/cloud/answer/13464323).
* Google, [Security bundle](https://developers.google.com/identity/siwg/security-bundle).
* Google Workspace, [Find and add unmanaged users](https://knowledge.workspace.google.com/admin/users/find-and-add-unmanaged-users).
* Google Workspace, [About automated user provisioning](https://knowledge.workspace.google.com/admin/users/advanced/about-automated-user-provisioning).
* Google Workspace, [Suspend a user temporarily](https://knowledge.workspace.google.com/admin/users/suspend-a-user-temporarily).
* Google Workspace, [Set session length for Google services](https://knowledge.workspace.google.com/admin/security/set-session-length-for-google-services).
* Google Workspace, [Set up your own custom SAML app](https://knowledge.workspace.google.com/admin/apps/set-up-your-own-custom-saml-app).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.