Skip to main content
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 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. 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:

​
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://<subdomínio>.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://<subdomínio>.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:
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

​
Fontes