> ## 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 OneLogin > Como a equipe de TI liga o OneLogin ao QX: o login com SSO, o provisionamento de usuários e o SSO obrigatório. Este guia é para o administrador do OneLogin da sua empresa. Ele mostra como ligar o OneLogin a uma organização do QX. O trabalho tem duas partes: a equipe de TI configura o OneLogin, e o owner da organização configura o QX. O [guia do login com SSO](/sso) explica as regras que valem para todos os provedores. ## O que o QX oferece * A pessoa entra no QX pelo login com SSO no OneLogin, com o protocolo OIDC. O QX nunca vê a senha. * O OneLogin 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 OneLogin. * Por padrão, o papel vem do QX: a pessoa nova entra como operador, e o owner muda o papel em **Usuários**. Se a empresa preferir, o grupo dos owners no OneLogin define o papel a cada login. * 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 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 OneLogin. * 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 conta ou de app do OneLogin, e depois configura uma nova. O QX não pede um login novo ao OneLogin. Quando um ato sensível pede a confirmação de identidade, o QX pede o código do app autenticador do QX. ## A ordem do trabalho Faça os passos nesta ordem: 1. A equipe de TI cria o app OIDC no OneLogin. 2. A equipe de TI atribui o app às pessoas e configura os grupos. 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 OneLogin. 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 OneLogin tem o mesmo e-mail do usuário do owner no QX. * Quando o grupo dos owners define o papel, o owner está nesse grupo. ## 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 OneLogin | | - | - | | URL de login | **Login Url**, no app OIDC | | URI de redirecionamento | **Redirect URI's**, no app OIDC | | Base URL do provisionamento de usuários | **SCIM Base URL**, no app de provisionamento | O nome **SCIM Base URL** vem do guia de SCIM do OneLogin. Os nomes dos outros dois campos seguem o portal de administração do OneLogin (não conferido em fonte oficial). 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 OneLogin Os nomes das abas e dos campos desta lista seguem o portal de administração do OneLogin (não conferido em fonte oficial). 1. No portal de administração, adicione o app **OpenId Connect (OIDC)**. 2. Em **Display Name**, digite `QX` e salve. 3. Na aba **Configuration**, em **Redirect URI's**, cole a URI de redirecionamento do QX. 4. Deixe **Login Url** vazio por enquanto. O passo 4 preenche o campo. 5. Na aba **SSO**, em **Token Endpoint**, escolha o método **Basic**. Ele é o **Basic (client\_secret\_basic)** do QX. O método **POST** é o **Post (client\_secret\_post)** do QX. 6. Na aba **SSO**, copie o client ID e o client secret. O endereço do provedor de identidade é `https://.onelogin.com/oidc/2`, com o subdomínio da conta do OneLogin. Entregue o client ID e o client secret ao owner por um canal seguro, como um gerenciador de senhas. ## 2. Atribua o app e configure os grupos 1. Atribua o app às pessoas que usam o QX. 2. Só quando o grupo dos owners define o papel: configure o parâmetro **Groups** do app para que ele inclua o grupo dos owners. 3. Só quando o owner vai ligar a vinculação por e-mail: faça o OneLogin mandar o `email_verified`, como o guia "Enabling the email\_verified claim" do OneLogin explica. Quando o grupo dos owners define o papel, o QX pede o escopo `groups` em cada login e lê o claim `groups`. Com o papel definido no QX, o QX não pede esse escopo. O OneLogin preenche o claim `groups` com o parâmetro **Groups** do app. Esse parâmetro costuma vir dos papéis do OneLogin ou do `member_of` do AD. Os valores são nomes. Sem papel, a pessoa não recebe o claim. O OneLogin não manda o `email_verified` quando o administrador não mapeia esse claim. Sem ele, o QX não liga ninguém pelo e-mail. ## 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. Escolha **OneLogin** e clique em **Continuar**. 3. Em **Endereço do provedor de identidade**, digite `https://.onelogin.com/oidc/2`. O QX confere o formato do subdomínio e grava o subdomínio em letras minúsculas. O endereço fica fixo depois que o owner salva a conexão. 4. Em **Client ID** e **Client secret**, cole os valores do passo 1. 5. Em **Autenticação do cliente**, escolha o mesmo método do app: **Basic (client\_secret\_basic)** ou **Post (client\_secret\_post)**. 6. Em **Papel das pessoas**, escolha **Definido no QX** ou **Definido pelo grupo dos owners**. Na segunda opção, digite em **Grupo dos owners** o nome do grupo exatamente como o OneLogin manda no login. 7. Só com o grupo dos owners: confira a linha "Com o grupo dos owners, o QX pede também o escopo groups." 8. Se usuários do QX vão entrar antes que o provisionamento de usuários ligue cada um, marque **Vincular usuários do QX pelo e-mail**. A opção só funciona com o papel definido no QX, e precisa do `email_verified` do passo 2. 9. Em **Verificação em duas etapas**, a única opção é **Pelo app autenticador do QX**. 10. Em **Duração da sessão com SSO**, escolha de 1 a 8 horas. O padrão é 8 horas. 11. Clique em **Salvar conexão SSO**. Se o login do owner tem mais de 15 minutos, o QX pede a senha. Depois de salvar, o quadro **Endereços para o provedor de identidade** mostra a URL de login. O QX compara o endereço do provedor de identidade com o `iss` de cada token, letra por letra. Se o `iss` dos tokens do OneLogin é igual ao issuer do discovery: não conferido em fonte oficial. O teste de login confere a igualdade. Uma mudança no papel das pessoas, no grupo dos owners ou na vinculação por e-mail encerra as sessões abertas com SSO. Faça a mudança fora do horário de trabalho. 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**. ## 4. Cole a URL de login no OneLogin 1. Abra o app OIDC no OneLogin, na aba **Configuration**. 2. Em **Login Url**, cole a URL de login do QX. 3. Salve o app. O portal do OneLogin abre o QX por esse endereço, e o QX começa o login. ## 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 provedor de identidade** e clique em **Voltar para as chaves**. ## 6. Ative o provisionamento de usuários no OneLogin O guia de SCIM do OneLogin usa um app **SCIM Provisioner with SAML**. Se o app OIDC do passo 1 também oferece o provisionamento: não conferido em fonte oficial. Com um app de provisionamento à parte, atribua a ele as mesmas pessoas do app OIDC. O QX não usa os campos de SAML desse app. 1. Na aba **Configuration** do app de provisionamento, em **SCIM Base URL**, cole a Base URL do provisionamento de usuários, sem barra no fim. 2. Em **SCIM Bearer Token**, cole a chave de provisionamento. O OneLogin manda a chave no cabeçalho `Authorization: Bearer`. 3. Em **SCIM JSON Template**, mande o `externalId` com o valor do `sub` do login, como o texto abaixo explica. 4. Não marque **Include in User Provisioning** no parâmetro **Groups**. O QX não recebe grupos. 5. Clique em **Save**. 6. Clique em **Enable**. O OneLogin pede um usuário que não existe e espera uma lista vazia ou `404`. Depois, **API Status** mostra **Enabled**. 7. Ligue o provisionamento do app em **Enable provisioning**. O QX reconhece a pessoa pelo `sub` do login. O modelo padrão do OneLogin oferece o `externalId` com `$user.external_id`, como atributo opcional, e oferece o `$user.id`, o ID do usuário no OneLogin. Esta linha do modelo manda o ID do usuário: ```json theme={null} "externalId": "{$user.id}" ``` Se o `sub` do login do OneLogin é igual ao `$user.id`: não conferido em fonte oficial. Quando os dois valores diferem, o teste de login do owner falha com "O identificador do login não bate com o identificador do provisionamento de usuários." Quando o `externalId` não pode levar o `sub`, deixe o `externalId` fora do modelo, como no modelo padrão. Então o owner marca **Vincular usuários do QX pelo e-mail**, e a equipe de TI mapeia o `email_verified` (passo 2). O provisionamento de usuários cria o usuário sem `externalId`, e o primeiro login com SSO conclui a vinculação. O modelo padrão manda o `userName` com `{$parameters.scimusername}`, que costuma ser o e-mail. O QX precisa de um e-mail em `userName` ou em `emails`. O que o QX faz com as chamadas do OneLogin: * O OneLogin atualiza o usuário com um `PUT` do usuário inteiro. Um `PUT` sem `externalId` mantém o valor gravado no QX. * Para suspender a pessoa, o OneLogin manda `active` falso num `PUT`. O QX desativa o usuário. * Quando o administrador exclui a pessoa no OneLogin, ele escolhe **Delete**, **Suspend** ou **Do Nothing**. Com **Delete**, o OneLogin manda `DELETE`. * O OneLogin pede respostas em `application/json`. O QX responde nesse tipo quando o cabeçalho `Accept` pede só `application/json`. Nos outros casos, o QX responde em `application/scim+json`. Se o OneLogin aceita esse tipo: não conferido em fonte oficial. ## 7. Faça o teste de login 1. Em **Configurações › SSO**, o owner clica em **Testar login**. 2. O QX abre o OneLogin. O owner entra com o próprio usuário. O OneLogin pode usar a sessão que já está aberta nele. 3. O QX mostra "Teste de login aprovado. A conexão SSO está verificada." O teste liga o usuário do owner no OneLogin ao usuário do owner no QX. O provisionamento de usuários não precisa ligar o owner antes. O teste pede duas coisas: * Quando o grupo dos owners define o papel, o owner está no grupo dos owners. * Quando o provisionamento de usuários já criou o owner, o `externalId` do owner é igual ao `sub` do login. ## 8. 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 o QX pelo portal do OneLogin e confere o login. A pessoa entra no QX pelo portal do OneLogin. A tela **Entrar com SSO** do QX pede que a pessoa abra o QX pelo portal do provedor de identidade. ## 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. 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 Com o OneLogin, a conexão SSO oferece 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 OneLogin, 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 OneLogin. Quando o login de uma sessão com SSO tem mais de 15 minutos, um ato sensível pede a confirmação de identidade. Com o OneLogin, a confirmação é sempre o código do app autenticador do QX. A confirmação por código exige um app já cadastrado. 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 OneLogin com a mesma identidade. O OneLogin pode usar a sessão que já está aberta nele. Para trocar de app, a pessoa pede o reset do segundo fator a outro owner ou ao suporte do QX. ## 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 OneLogin. 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. ## 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. O usuário novo é operador. * 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. * Com o papel definido no QX, o owner muda o papel em **Usuários**, e o login com SSO não muda o papel. * Com o papel definido pelo grupo dos owners, o papel muda no próximo login com SSO depois de uma troca de grupo. Quem está no grupo entra como owner, e as outras pessoas entram como operador. O papel fica só para leitura em **Usuários**. * O QX não cria usuário no primeiro login pelo OneLogin. A pessoa sem usuário no QX entra depois que o provisionamento de usuários cria o usuário dela. * Para desativar uma pessoa, suspenda a pessoa no OneLogin. O provisionamento de usuários desativa o usuário no QX. Todas as sessões do usuário terminam no mesmo instante. * Quando o OneLogin manda `active` verdadeiro para um usuário desativado, o usuário volta a "Aguardando login com SSO" e entra de novo no próximo login com SSO. * Quando o OneLogin manda `DELETE`, o QX desliga o acesso do usuário e deixa de mostrar o usuário ao provisionamento de usuários. O usuário e o histórico dele ficam no QX. Quando o OneLogin provisiona a mesma pessoa de novo, com o mesmo `externalId`, o QX traz de volta o mesmo usuário. * O nome e o e-mail da pessoa mudam só no OneLogin. O owner vê o usuário no QX, mas não muda esses dados. * Uma troca de e-mail no OneLogin não bloqueia o login com SSO. A página do usuário mostra o e-mail do OneLogin quando ele é diferente do e-mail no QX. ## Troque a chave de provisionamento A conexão SSO guarda até 2 chaves ativas. Com duas chaves, o OneLogin 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 o código do app autenticador do QX. 2. A equipe de TI cola a chave nova em **SCIM Bearer Token**, no app de provisionamento, e salva. 3. O owner confere a coluna **Último uso** da chave nova. 4. O owner clica em **Revogar** na chave antiga e depois em **Revogar chave**. ## Troque o client secret 1. No OneLogin, a equipe de TI gera um client secret novo na aba **SSO** do app OIDC (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 OneLogin cai Com o SSO obrigatório ligado, ninguém entra no QX enquanto o OneLogin 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 OneLogin 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 OneLogin 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 OneLogin voltar. ## Remova a conexão SSO Para trocar de conta ou de app do OneLogin, 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 e as chaves de provisionamento. O OneLogin deixa de criar e desativar usuários no QX. Desligue o provisionamento no app antigo do OneLogin. * 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 OneLogin. | | O provedor de identidade não mandou os grupos do seu usuário. | O parâmetro **Groups** do app e os papéis da pessoa, quando o grupo dos owners define o papel. | | 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 da pessoa no OneLogin e a atribuição do app. | | O QX não encontrou o seu usuário. | O e-mail da pessoa no OneLogin e no QX, o provisionamento de usuários, a opção **Vincular usuários do QX pelo e-mail** e o mapeamento do `email_verified`. | | O identificador do login não bate com o identificador do provisionamento de usuários. | O `externalId` do **SCIM JSON Template**, que precisa levar o `sub` do login. | | O provedor de identidade não respondeu. | O status do OneLogin. Tente de novo em alguns minutos. | | Não foi possível entrar com SSO. | **Autenticação do cliente**, o client secret e o subdomínio no **Endereço do provedor de identidade**. | ## Fontes * OneLogin, Connect an OIDC enabled app (OneLogin Developers). * OneLogin, [Provider configuration](https://developers.onelogin.com/openid-connect/api/provider-config). * OneLogin, [Authorization code flow](https://developers.onelogin.com/openid-connect/api/authorization-code). * OneLogin, [Upgrade v1 to v2](https://developers.onelogin.com/openid-connect/api/upgrade). * OneLogin, [Scopes](https://developers.onelogin.com/docs/openid-connect/scopes/). * OneLogin, [Enabling the email\_verified claim](https://developers.onelogin.com/docs/openid-connect/guides/email-verified/). * OneLogin, [Implement RESTful SCIM APIs for your app](https://developers.onelogin.com/scim/implement-scim-api). * OneLogin, [Create a SCIM test app](https://developers.onelogin.com/scim/create-app). * OneLogin, [Define your SCIM user schema](https://developers.onelogin.com/scim/define-user-schema). * OneLogin, [Test your SCIM](https://developers.onelogin.com/scim/test-your-scim). * OneLogin, documento de discovery da conta `onelogin`: `https://onelogin.onelogin.com/oidc/2/.well-known/openid-configuration`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.