Skip to main content
Este guia é para o administrador do Okta da sua empresa. Ele mostra como ligar o Okta a uma organização do QX. O trabalho tem duas partes: a equipe de TI configura o Okta, 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 Okta, com o protocolo OIDC. O QX nunca vê a senha.
  • O Okta 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 Okta.
  • 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 Okta 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 conexão SSO escolhe onde a pessoa prova o segundo fator: no Okta ou no app autenticador do QX.
  • 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 servidor de autorização ou de app do Okta, e depois configura uma nova.
O QX testa o Okta Identity Engine. No teste de login, na confirmação de identidade e no cadastro do app autenticador, o QX manda prompt=login e max_age=0. O max_age=0 força um login novo no Identity Engine. O Okta Classic usa max_age=1, e o QX não testa o Classic.

​
A ordem do trabalho

Faça os passos nesta ordem:
  1. A equipe de TI cria o app OIDC no Okta.
  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 Okta.
  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 Okta 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 Initiate login URI vem da ajuda do Okta. Os nomes dos outros dois campos seguem o Admin Console do Okta (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 Okta

Os nomes dos menus e dos campos desta lista seguem o Admin Console do Okta (não conferido em fonte oficial).
  1. No Admin Console, abra Applications › Applications e clique em Create App Integration.
  2. Escolha OIDC - OpenID Connect e Web Application, e clique em Next.
  3. Em App integration name, digite QX.
  4. Em Grant type, mantenha Authorization Code.
  5. Em Sign-in redirect URIs, cole a URI de redirecionamento do QX.
  6. Clique em Save. A aba General mostra o client ID e o client secret.
  7. Em Client authentication, mantenha Client secret.
  8. O QX manda sempre o PKCE com S256. A opção Require PKCE as additional verification pode ficar ligada.
  9. Copie o client ID e o client secret.
O Okta oferece os métodos client_secret_basic e client_secret_post no endpoint de token. Qual método um app novo usa por padrão: não conferido em fonte oficial. No QX, comece com Basic (client_secret_basic). Se o teste de login falhar com “O teste de login falhou.”, troque para Post (client_secret_post) e teste de novo. 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 ou aos grupos que usam o QX. Quando o grupo dos owners define o papel, atribua também esse grupo.
  2. Só quando o grupo dos owners define o papel: faça o Okta mandar o claim groups no ID token, como a lista abaixo 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. Os valores do claim são os nomes dos grupos. O Okta manda até 100 grupos.
  • No servidor de autorização da org (https://<domínio do Okta>), use o Groups claim filter do app. Dê ao claim o nome groups e escolha um filtro que inclua o grupo dos owners, como Equals com o nome do grupo. Esse filtro põe os grupos só no ID token, que é o token que o QX lê.
  • Num servidor de autorização customizado (https://<domínio do Okta>/oauth2/<id do servidor>), crie no servidor um claim groups com o tipo de valor Groups, no ID token, com um filtro que inclua o grupo dos owners.
Se um servidor customizado precisa de um escopo chamado groups para aceitar o pedido do QX com o grupo dos owners: não conferido em fonte oficial. Se o Okta recusar o pedido por causa do escopo groups, crie esse escopo no servidor.

​
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 Okta e clique em Continuar.
  3. Em Endereço do provedor de identidade, cole o issuer do servidor de autorização: https://<domínio do Okta> para o servidor da org, ou https://<domínio do Okta>/oauth2/<id do servidor> para um servidor customizado. Todo Okta tem o servidor customizado default. O QX tira a barra do fim do endereço. 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 Okta 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. O Okta manda o email_verified, que a vinculação exige.
  9. Em Verificação em duas etapas, escolha Pelo Okta ou Pelo app autenticador do QX. A seção Verificação em duas etapas deste guia explica as opções.
  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. Com um domínio próprio, o modo de issuer do servidor (ORG_URL, CUSTOM_URL ou DYNAMIC) decide o iss. No modo DYNAMIC, o iss muda com o domínio do pedido. Use no QX o endereço que aparece no iss dos tokens. Uma mudança no papel das pessoas, no grupo dos owners, na vinculação por e-mail ou na verificação em duas etapas 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 Okta

  1. Abra o app OIDC no Okta.
  2. Em Initiate login URI, cole a URL de login do QX.
  3. Escolha Redirect to app to initiate login (OIDC Compliant).
  4. Salve o app.
O painel do Okta abre o QX por esse endereço. O Okta manda o parâmetro iss com o endereço da org, também quando o QX usa um servidor customizado. O QX ignora esse parâmetro e começa sempre um login novo.

​
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 Okta

O Okta configura o SCIM 2.0 num app do App Integration Wizard. Se o app OIDC do passo 1 oferece o provisionamento por SCIM: não conferido em fonte oficial. Quando o app OIDC não oferece, use um app do Okta com SCIM e atribua a ele as mesmas pessoas.
  1. Na configuração do SCIM do app, em SCIM connector base URL, cole a Base URL do provisionamento de usuários, sem barra no fim.
  2. Em Unique identifier field for users, escolha o e-mail. O Okta procura a pessoa no QX por userName com esse valor.
  3. Na autenticação, escolha HTTP Header e cole a chave de provisionamento como bearer token.
  4. Deixe Import Groups e Push Groups desligados. O QX não recebe grupos.
  5. Salve. O Okta chama GET /Users?startIndex=1&count=2, e o QX responde com a lista dos usuários.
  6. Na aba Provisioning, em To App, clique em Edit. Ligue Create User, Update User Attributes e Deactivate Users, e clique em Save.
O QX reconhece a pessoa pelo sub do login, que é o ID do usuário no Okta. O provisionamento de usuários precisa mandar o mesmo valor em externalId. O exemplo de criação da documentação do Okta manda o ID do usuário no Okta em externalId. Se todo app do App Integration Wizard manda o externalId: não conferido em fonte oficial. Sem externalId, o QX recusa a criação com a mensagem “O QX precisa do externalId para criar ou ligar um usuário quando a conexão SSO não vincula usuários pelo e-mail”. Nesse caso, o owner marca Vincular usuários do QX pelo e-mail. O provisionamento de usuários então aceita um usuário sem externalId, e o primeiro login com SSO conclui a vinculação. O que o QX faz com as chamadas do Okta:
  • O Okta atualiza o usuário com um PUT do usuário inteiro. Um PUT sem externalId mantém o valor gravado no QX.
  • O Okta manda uma senha provisória na criação. O QX ignora a senha.
  • Para desativar a pessoa, o Okta manda active=false num PUT. O Okta nunca manda DELETE.

​
7. Faça o teste de login

  1. Em Configurações › SSO, o owner clica em Testar login.
  2. O QX abre o Okta e pede um login novo. 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 liga o usuário do owner no Okta ao usuário do owner no QX. O provisionamento de usuários não precisa ligar o owner antes. O teste exige o auth_time no token, e o Okta manda esse claim em todo login. O teste pede duas coisas:
  • Quando o grupo dos owners define o papel, o owner está no grupo dos owners.
  • Quando a organização exige a verificação em duas etapas pelo Okta, o owner entra no Okta com o segundo fator.

​
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 painel do Okta e confere o login.
A pessoa entra no QX pelo painel do Okta. 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

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 Okta: o QX manda acr_values=urn:okta:loa:2fa:any em cada pedido ao Okta. O QX aceita o login com SSO só quando o acr do token é urn:okta:loa:2fa:any. Nessa opção, o QX não lê o amr. Um token sem acr, ou com um valor de um fator só, como urn:okta:loa:1fa:any, não passa.
  • Pelo app autenticador do QX: depois do login no Okta, 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 Okta.
Depois de mudar para Pelo Okta, faça o teste de login com o segundo fator. Uma pessoa que entra com SSO também cadastra o app autenticador em Segurança da conta. Antes do cadastro, o QX pede um novo login no Okta. 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 Okta. 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 Okta. A pessoa sem usuário no QX entra depois que o provisionamento de usuários cria o usuário dela.
  • Para desativar uma pessoa, tire a atribuição do app ou desative a pessoa no Okta. O Okta manda active=false, e o QX desativa o usuário. Todas as sessões do usuário terminam no mesmo instante.
  • O Okta não manda nada ao QX quando suspende uma pessoa. As sessões dessa pessoa no QX continuam até vencer. Para cortar o acesso na hora, desative a pessoa. Uma duração curta limita o tempo das sessões abertas.
  • Quando o Okta manda active=true para um usuário desativado, o usuário volta a “Aguardando login com SSO” e entra de novo no próximo login com SSO.
  • O Okta nunca exclui um usuário do QX. O usuário desativado e o histórico dele ficam no QX.
  • O nome e o e-mail da pessoa mudam só no Okta. O owner vê o usuário no QX, mas não muda esses dados.
  • Uma troca de e-mail no Okta não bloqueia o login com SSO. A página do usuário mostra o e-mail do Okta 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 Okta 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 Okta.
  2. A equipe de TI cola a chave nova na autenticação HTTP Header da configuração do SCIM do app 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 Okta, a equipe de TI gera um client secret novo na aba General do app (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 Okta cai

Com o SSO obrigatório ligado, ninguém entra no QX enquanto o Okta 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 Okta 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 Okta 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 Okta voltar.

​
Remova a conexão SSO

Para trocar de servidor de autorização, de domínio ou de app do Okta, 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 Okta deixa de criar e desativar usuários no QX. Desligue o provisionamento no app antigo do Okta.
  • 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