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

> Como uma organização liga o provedor de identidade da empresa ao QX: os provedores testados, o que vale para todos e o que fazer quando algo dá errado.

Este guia é para a equipe de TI e para o owner da organização no QX. Ele mostra o que vale para todo provedor de identidade. O guia de cada provedor mostra os passos no console dele.

## Os provedores que o QX testa

O QX testa cinco provedores de identidade. Cada um tem um guia:

| Provedor | Guia | Provisionamento de usuários |
| - | - | - |
| JumpCloud | [Login com SSO pelo JumpCloud](/sso-jumpcloud) | Sim |
| Google Workspace | [Login com SSO pelo Google Workspace](/sso-google-workspace) | Não |
| Microsoft Entra ID | [Login com SSO pelo Microsoft Entra ID](/sso-entra-id) | Sim |
| Okta | [Login com SSO pelo Okta](/sso-okta) | Sim |
| OneLogin | [Login com SSO pelo OneLogin](/sso-onelogin) | Sim |

O QX não oferece SAML. Um provedor fora da lista não aparece na escolha do provedor.

## O que vale para todo provedor

* A pessoa entra no QX pelo login com SSO, com o protocolo OIDC. O QX usa o fluxo do código de autorização com PKCE (S256). O QX nunca vê a senha.
* O QX pede os escopos `openid`, `email` e `profile`. Sem o e-mail, o QX recusa cada login. Quando o grupo dos owners define o papel, o Okta e o OneLogin recebem também o escopo `groups`.
* O app do QX no provedor tem um client ID e um client secret. O app autentica o QX no endpoint de token com `client_secret_basic` ou `client_secret_post`. O owner escolhe o mesmo método em **Autenticação do cliente**, no QX.
* O provisionamento de usuários usa o protocolo SCIM 2.0. O QX recebe só usuários. Os grupos ficam no provedor. O Google Workspace não manda provisionamento para o QX.
* O QX reconhece a pessoa pelo identificador que o provedor manda no login. O provisionamento de usuários manda o mesmo identificador como `externalId`. O guia de cada provedor diz qual identificador é esse.

O owner vê os endereços do QX em **Configurações › SSO**, no quadro **Endereços para o provedor de identidade**:

| Endereço no QX | Para que serve |
| - | - |
| URL de login | Abre o QX pelo portal do provedor. Aparece depois que o owner salva a conexão SSO. |
| URI de redirecionamento | O provedor devolve a pessoa a esse endereço depois do login. |
| Base URL do provisionamento de usuários | O provedor chama esse endereço para criar, atualizar e desativar usuários. |

Em produção, os endereços fixos são estes:

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

## A escolha do provedor

O owner abre **Configurações › SSO**, clica em **Configurar conexão SSO**, escolhe o provedor e clica em **Continuar**. O formulário mostra só os campos daquele provedor:

* **Endereço do provedor de identidade**: o endereço que o provedor usa como emissor dos tokens. O QX confere o formato de cada provedor. No Microsoft Entra ID, o endereço leva o ID do tenant.
* **Domínio da empresa**: só no Google Workspace. O QX aceita só quem entra com uma conta desse domínio.
* **Client ID**, **Client secret** e **Autenticação do cliente**.
* **Verificação em duas etapas** e **Duração da sessão com SSO**.
* **Papel das pessoas** e as opções de e-mail que o provedor permite.

O provedor, o endereço do provedor e o domínio não mudam depois que o owner salva a conexão. Esses valores dizem quem pode entrar na organização. Para trocar de provedor, de tenant ou de região, o owner remove a conexão e configura uma nova.

Uma troca do client ID ou da **Autenticação do cliente** exige o login com SSO desabilitado e pede um novo teste de login. O owner faz a troca nesta ordem:

1. Se o SSO obrigatório está ligado, clique em **Desligar SSO obrigatório**.
2. Clique em **Desabilitar login com SSO**. As sessões abertas com SSO terminam, inclusive a do owner. O owner entra de novo com a senha, ou cria uma senha em **Esqueceu sua senha?**.
3. Clique em **Editar conexão SSO**, troque o valor e clique em **Salvar conexão SSO**.
4. Clique em **Testar login**.
5. Clique em **Habilitar login com SSO**.
6. Se o SSO obrigatório estava ligado, clique em **Ligar SSO obrigatório**.

## O papel das pessoas

* **Definido no QX** é o padrão. A pessoa nova entra como operador, e o owner muda o papel em **Usuários**.
* **Definido pelo grupo dos owners**: o QX lê o claim `groups` a cada login com SSO. Quem está no grupo entra como owner, e as outras pessoas entram como operador. O papel fica só para leitura em **Usuários**. O Google Workspace não tem essa opção, porque o token do Google não traz grupos.

O grupo só dá o papel de owner a uma pessoa que o provisionamento de usuários ou o teste de login vinculou. O grupo nunca tira o papel do último owner ativo da organização.

## Verificação em duas etapas

A opção da conexão SSO vale quando a organização exige a verificação em duas etapas. Mudar a opção encerra as sessões abertas com SSO.

* **Pelo provedor**: o QX aceita o login com SSO só quando o token prova o segundo fator. No JumpCloud e no Microsoft Entra ID, o claim `amr` precisa ter `mfa`, ou um método de posse (`otp`, `hwk`, `swk`, `sms`, `tel` ou `sc`) junto com a senha, um PIN ou biometria. Um método sozinho não passa. No Okta, o QX pede `acr_values=urn:okta:loa:2fa:any` e aceita só um `acr` igual a esse valor.
* **Pelo app autenticador do QX**: depois do login no provedor, 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. É a única opção no Google Workspace e no OneLogin.

O QX nunca aceita o segundo fator sem prova. Antes de um ato sensível, a confirmação de identidade também pede uma prova. O QX pede um novo login no provedor quando o provedor permite. No Google Workspace e no OneLogin, ou quando o token não diz a hora do login, o QX pede o código do app autenticador.

## Duração da sessão

O owner escolhe a duração da sessão com SSO, de 1 a 8 horas. O padrão é 8 horas. Depois desse prazo, a pessoa entra de novo pelo provedor. Um prazo menor encurta também as sessões abertas, contado do login. Um prazo maior vale só para os logins seguintes.

Sem provisionamento de usuários, uma pessoa que o provedor desativa mantém a sessão aberta no QX até o fim do prazo. No Google Workspace, escolha um prazo curto.

## Remova a conexão SSO

O owner remove a conexão em **Configurações › SSO**, no quadro **Remover conexão SSO**. 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 e as chaves de provisionamento. O provedor deixa de criar e desativar usuários no QX.
* Os usuários continuam no QX. Quem só entrava com SSO cria uma senha em **Esqueceu sua senha?**, na tela de login.

Depois da remoção, o owner configura uma conexão nova, com outra URL de login.

## Quando algo dá errado

| Situação | O que fazer |
| - | - |
| O provedor está fora do ar e o SSO obrigatório está ligado | Um owner com sessão aberta clica em **Desligar SSO obrigatório**. Sem owner com sessão, o suporte do QX desliga a regra e grava o motivo. Quem não tem senha usa **Esqueceu sua senha?**. |
| A conexão está errada, ou a empresa troca de provedor, de tenant ou de região | O owner remove a conexão e configura uma nova. |
| Nenhum owner consegue entrar | O suporte do QX remove a conexão e grava o motivo. Depois, o owner entra com senha. |
| A pessoa perdeu o app autenticador | Outro owner ou o suporte do QX faz o reset do segundo fator. Quando a organização exige a verificação em duas etapas e a conexão usa **Pelo app autenticador do QX**, a pessoa cadastra um app novo no próximo login com SSO. Nos outros casos, a pessoa cadastra o app em **Segurança da conta**. |
| A aba SSO diz que o QX mudou as configurações do provedor | O owner faz o teste de login de novo. O login com SSO continua funcionando. |
| O acesso de todos precisa acabar agora | O owner diminui a duração da sessão com SSO, ou desabilita o login com SSO. |

O guia de cada provedor lista as mensagens de recusa e o que conferir no console do provedor.


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