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

> Como a equipe de TI liga o JumpCloud ao QX: o login com SSO, o provisionamento de usuários e o SSO obrigatório.

Este guia é para o administrador do JumpCloud da sua empresa. Ele mostra como ligar o JumpCloud a uma organização do QX. O trabalho tem duas partes: a equipe de TI configura o JumpCloud, e o owner da organização configura o QX.

## O que o QX oferece

* A pessoa entra no QX pelo login com SSO no JumpCloud, com o protocolo OIDC. O QX nunca vê a senha.
* O JumpCloud cria, atualiza e desativa os usuários do QX pelo provisionamento de usuários, com o protocolo SCIM 2.0. O QX recebe só usuários. Os grupos ficam no JumpCloud.
* O JumpCloud tem um grupo dos owners e um grupo dos operadores. A cada login, o QX dá à pessoa o papel do grupo dela.
* 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, o QX só aceita o login com SSO em que a pessoa usou um segundo fator no JumpCloud.
* A sessão aberta pelo login com SSO vence 8 horas depois do login. Ela não se prorroga.

Hoje o QX aceita só o JumpCloud, nas regiões EUA, UE e Índia. O QX não oferece SAML.

## A ordem do trabalho

Faça os passos nesta ordem:

1. A equipe de TI cria o app OIDC no JumpCloud.
2. A equipe de TI liga os dois grupos ao app.
3. O owner configura a conexão SSO no QX.
4. A equipe de TI cola a URL de login do QX no app.
5. O owner gera a chave de provisionamento.
6. A equipe de TI ativa o provisionamento de usuários no JumpCloud.
7. O owner faz o teste de login.
8. O owner habilita o login com SSO.
9. O owner liga o SSO obrigatório.

Antes de começar, confira duas coisas:

* O usuário do owner no JumpCloud tem o mesmo e-mail do usuário do owner no QX.
* O owner está no grupo dos owners.

## Os endereços do QX

O owner vê os endereços em **Configurações › SSO**, no quadro **Endereços para o JumpCloud**. Cada endereço tem um botão **Copiar**.

| Endereço no QX | Campo no JumpCloud |
| - | - |
| URL de login | **Login URL**, na aba SSO do app |
| URI de redirecionamento | **Redirect URIs**, na aba SSO do app |
| Base URL do provisionamento de usuários | **Base URL**, na aba Provisioning do app |

A URL de login só aparece depois que o owner salva a conexão SSO. Os outros dois endereços são estes:

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

## 1. Crie o app OIDC no JumpCloud

1. No JumpCloud Admin Portal, vá a **Access › SSO Applications**.
2. Clique em **+ Add New Application**.
3. Escolha **Custom Application** e clique em **Next**.
4. Escolha **Manage Single Sign-On**, depois **Configure SSO with OIDC**, e clique em **Next**.
5. Em **Display Label**, digite `QX`.
6. Ligue **Show this application in User Portal**. O atalho do portal abre o QX.
7. Clique em **Next** e depois em **Configure Application**.
8. Na aba SSO, em **Redirect URIs**, cole a URI de redirecionamento do QX.
9. Em **Client Authentication Type**, escolha **Client Secret Basic**. O QX não funciona com os outros dois tipos.
10. Deixe **Login URL** vazio por enquanto. O passo 4 preenche o campo. O JumpCloud aceita o app sem **Login URL** (não conferido em fonte oficial).
11. Em **Subject Claim**, mantenha **JumpCloud User ID (Recommended Default)**.
12. Em Attribute Mapping, marque os escopos **Email** e **Profile**. Sem o e-mail, o QX recusa cada login.
13. Marque **include group attribute** e digite `groups` como nome do atributo de grupos.
14. Clique em **Activate**. O JumpCloud mostra o client secret uma vez só. Copie o client ID e o client secret, e clique em **Got It**.

Entregue o client ID e o client secret ao owner por um canal seguro, como um gerenciador de senhas.

## 2. Ligue os dois grupos ao app

1. Abra a aba **User Groups** do app.
2. Marque o grupo dos owners e o grupo dos operadores.
3. Clique em **Save**.

Cada pessoa precisa estar em um só desses dois grupos. A pessoa que está nos dois grupos não entra no QX.

## 3. 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. Em **Região**, escolha a região da conta do JumpCloud: **EUA**, **UE** ou **Índia**.
3. Em **Client ID** e **Client secret**, cole os valores do passo 1.
4. Em **Grupo dos owners** e **Grupo dos operadores**, digite o nome de cada grupo exatamente como o JumpCloud mostra.
5. Clique em **Salvar conexão SSO**.

Depois de salvar, o quadro **Endereços para o JumpCloud** mostra a URL de login.

## 4. Cole a URL de login no JumpCloud

1. Abra o app no JumpCloud, na aba SSO.
2. Em **Login URL**, cole a URL de login do QX.
3. Salve o app.

## 5. Gere a chave de provisionamento

O owner faz estes passos no QX:

1. Em **Configurações › SSO**, clique em **Gerenciar chaves de provisionamento**.
2. Clique em **Gerar chave de provisionamento** e depois em **Gerar chave**. Se o login do owner tem mais de 15 minutos, o QX pede a senha.
3. Copie a chave. O QX mostra a chave uma vez só. A chave começa com `qxp_`.
4. Entregue a chave à equipe de TI por um canal seguro. Não mande a chave por e-mail nem por mensagem.
5. Depois que a equipe de TI colar a chave, marque **Colei a chave no JumpCloud** e clique em **Voltar para as chaves**.

## 6. Ative o provisionamento de usuários no JumpCloud

1. Abra a aba **Provisioning** do app.
2. Deixe **Use mTLS** desligado.
3. Em **Base URL**, cole a Base URL do provisionamento de usuários, sem barra no fim.
4. Em **Token**, cole a chave de provisionamento.
5. Em **Test User Email**, digite um e-mail que nenhum usuário do QX tem. O JumpCloud cria esse usuário de teste e apaga o usuário depois.
6. Clique em **Test Connection**.
7. Desligue **Enable management of User Groups and Group Membership in this application**. O QX não recebe grupos.
8. Clique em **Activate**. Não clique em **Save**.

Se a ativação falhar com a mensagem "O QX precisa do externalId para criar ou ligar um usuário", mapeie o `externalId`:

1. Na aba **Provisioning**, abra **User Attributes** e clique em **Edit**.
2. Clique em **+Add Attribute** e escolha o tipo **Expression**.
3. No campo do atributo do JumpCloud, digite esta expressão:

```text theme={null}
notNullOrEmpty(providerUser.externalId) ? providerUser.externalId : jcUser.id
```

4. No campo do atributo SCIM, escolha `externalId`.
5. Clique em **Update** e depois em **Activate** de novo.

O `externalId` leva o JumpCloud User ID. O QX reconhece a pessoa por esse identificador. O e-mail sozinho nunca identifica a pessoa.

## 7. Faça o teste de login

1. Em **Configurações › SSO**, o owner clica em **Testar login**.
2. O QX abre o JumpCloud. O owner entra com o próprio usuário.
3. O QX mostra "Teste de login aprovado. A conexão SSO está verificada."

O teste pede três coisas:

* O provisionamento de usuários já ligou o usuário do owner.
* O owner está no grupo dos owners.
* Quando a organização exige a verificação em duas etapas, o owner entra no JumpCloud com o segundo fator.

## 8. Habilite o login com SSO

1. Em **Configurações › SSO**, o owner clica em **Habilitar login com SSO**.
2. Uma pessoa do grupo dos operadores abre o QX pelo atalho do portal do JumpCloud e confere o login.

A pessoa entra no QX pelo atalho do portal do JumpCloud. A tela **Entrar com SSO** do QX pede que a pessoa abra o QX pelo portal.

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

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.

## Como o QX trata cada pessoa

* O provisionamento de usuários cria o usuário da pessoa nova. A tela **Usuários** mostra "Aguardando login com SSO". O primeiro login com SSO ativa o usuário e dá o papel do grupo.
* Quando a pessoa já tem usuário no QX, o provisionamento de usuários liga esse usuário pelo e-mail, na mesma organização. O usuário mantém o histórico.
* Depois de uma troca de grupo, o papel muda no próximo login com SSO. Para trocar de grupo, ponha a pessoa no grupo novo antes de tirar a pessoa do grupo antigo.
* Para desativar uma pessoa, tire a pessoa dos dois grupos ou suspenda a pessoa no JumpCloud. O provisionamento de usuários desativa o usuário no QX. Todas as sessões do usuário terminam no mesmo instante.
* Para reativar uma pessoa, devolva a pessoa a um grupo. O usuário volta a "Aguardando login com SSO" e entra de novo no próximo login com SSO.
* O nome e o e-mail da pessoa mudam só no JumpCloud. O owner vê o usuário no QX, mas não muda esses dados.

## Troque a chave de provisionamento

A conexão SSO guarda até 2 chaves ativas. Com duas chaves, o JumpCloud troca de chave sem interromper o provisionamento de usuários.

1. O owner gera uma chave nova, como no passo 5. Numa sessão aberta com SSO e com login de mais de 15 minutos, o QX pede a confirmação de identidade no JumpCloud.
2. A equipe de TI abre a aba **Provisioning** do app e expande **Configuration Settings**.
3. A equipe de TI cola a chave nova em **Token Key** e clica em **Update**. O botão **Save** não troca a chave.
4. O owner confere a coluna **Último uso** da chave nova.
5. O owner clica em **Revogar** na chave antiga e depois em **Revogar chave**.

## Troque o client secret

1. No JumpCloud, a equipe de TI abre o app e escolhe **Actions › Regenerate Secret** e depois **Regenerate**.
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 JumpCloud cai

Com o SSO obrigatório ligado, ninguém entra no QX enquanto o JumpCloud 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**.
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 JumpCloud volta, o owner clica em **Ligar SSO obrigatório**.

O usuário que o provisionamento de usuários criou e que nunca entrou no QX não entra com senha. Ele espera o JumpCloud voltar.

## As mensagens de recusa

| Mensagem que a pessoa vê | O que a equipe de TI confere |
| - | - |
| A sua organização exige um segundo fator. | A pessoa entra no JumpCloud com o segundo fator. |
| O seu usuário no JumpCloud precisa estar em um grupo do QX, e só em um. | O grupo da pessoa, os nomes dos grupos no QX e o atributo `groups`. |
| O seu acesso ao QX está desativado. | O estado da pessoa no JumpCloud e nos grupos do app. |
| O QX não encontrou o seu usuário. | O e-mail da pessoa no JumpCloud e no QX, e o provisionamento de usuários. |
| O JumpCloud não respondeu. | O status do JumpCloud. Tente de novo em alguns minutos. |
| Não foi possível entrar com SSO. | **Client Authentication Type**, o client secret, a região e os escopos **Email** e **Profile**. |

## Fontes

* JumpCloud, [SSO with OIDC](https://jumpcloud.com/support/sso-with-oidc).
* JumpCloud, [Provision and manage users and groups in apps using custom SCIM identity management integration](https://jumpcloud.com/support/provision-and-manage-users-and-groups-in-apps-using-custom-scim-identity-management-integration).
* JumpCloud, [Authorize users to an SSO application](https://jumpcloud.com/support/authorize-users-to-an-sso-application).
* JumpCloud, [Rotate SSO application certificates, SCIM token keys, and OIDC tokens](https://jumpcloud.com/support/rotate-sso-certs).


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