Skip to main content
Este guia é para o administrador do Microsoft Entra ID da sua empresa. Ele mostra como ligar o Entra ID a uma organização do QX. O trabalho tem duas partes: a equipe de TI configura o Entra ID, e o owner da organização configura o QX. O guia do login com SSO explica as regras que valem para todo provedor de identidade.

​
O que o QX oferece

  • A pessoa entra no QX pelo login com SSO no Entra ID, com o protocolo OIDC. O QX nunca vê a senha.
  • O Entra ID 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 Entra ID.
  • O QX reconhece a pessoa pelo claim oid, o identificador da pessoa no tenant.
  • 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 Entra ID define o papel a cada login.
  • O QX não vincula usuários pelo e-mail e não cria usuário no primeiro login com o Entra ID, porque o token do Entra ID não confirma o 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 Entra ID 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 tenant ou de app registration, e depois configura uma nova.
O QX aceita um app registration de um tenant só. O QX não oferece SAML.

​
A ordem do trabalho

Faça os passos nesta ordem:
  1. A equipe de TI cria o app registration no Entra ID.
  2. A equipe de TI adiciona os claims opcionais e o claim de grupos.
  3. O owner configura a conexão SSO no QX.
  4. A equipe de TI grava 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 Entra ID.
  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 Entra ID 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. 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 registration no Entra ID

Os nomes dos menus e dos campos deste passo: não conferido em fonte oficial.
  1. No Microsoft Entra admin center, abra App registrations e clique em New registration.
  2. Em Name, digite QX.
  3. Em Supported account types, escolha a opção de um tenant só: Accounts in this organizational directory only.
  4. Em Redirect URI, escolha a plataforma Web e cole a URI de redirecionamento do QX.
  5. Clique em Register.
  6. Na página Overview, copie o Application (client) ID e o Directory (tenant) ID.
  7. Em Certificates & secrets, crie um client secret e copie o valor.
Entregue o client ID, o client secret e o ID do tenant ao owner por um canal seguro, como um gerenciador de senhas.

​
2. Adicione os claims opcionais e o claim de grupos

O token de ID v2 do Entra ID não traz auth_time nem amr por padrão. Os dois são claims opcionais. Os nomes dos menus deste passo: não conferido em fonte oficial.
  1. No app registration, abra Token configuration.
  2. Clique em Add optional claim, escolha o token ID e marque auth_time e email.
  3. Para a verificação em duas etapas Pelo Microsoft Entra ID, marque também amr.
  4. Só quando o grupo dos owners define o papel: clique em Add groups claim e mantenha o ID do grupo como valor.
O claim auth_time é obrigatório. O QX pede um novo login ao Entra ID no teste de login, na confirmação de identidade e no cadastro do app autenticador, com prompt=login e max_age=0. Sem auth_time, o teste de login falha, o cadastro do app autenticador falha, e a confirmação de identidade pede o código do app autenticador do QX. O suporte do Entra ID a max_age: não conferido em fonte oficial. O claim email também é obrigatório. O QX recusa um token sem email. O Entra ID só manda o email quando a pessoa tem um endereço de e-mail no Entra ID. O claim groups traz o object ID de cada grupo. Por isso, o grupo dos owners é o Object ID do grupo. Com a opção Groups assigned to the application, o token traz só os grupos atribuídos ao app, sem grupos aninhados. Acima de 200 grupos, o token troca os grupos por uma referência a outro endereço. Quando o grupo dos owners define o papel, o QX recusa esse login com a mensagem dos grupos. Use Groups assigned to the application para ficar abaixo desse limite.

​
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 Microsoft Entra ID e clique em Continuar.
  3. Em Endereço do provedor de identidade, digite https://login.microsoftonline.com/<ID do tenant>/v2.0, com o Directory (tenant) ID do passo 1. O QX recusa common, organizations, consumers e o tenant das contas pessoais da Microsoft (9188040d-6c67-4c5b-b112-36a304b66dad) no lugar do ID do tenant. O QX grava o ID do tenant 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, mantenha Basic (client_secret_basic). O Entra ID aceita também 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 Object ID do grupo.
  7. Em Verificação em duas etapas, escolha Pelo Microsoft Entra ID ou Pelo app autenticador do QX. A seção Verificação em duas etapas deste guia explica as opções.
  8. Em Duração da sessão com SSO, escolha de 1 a 8 horas. O padrão é 8 horas.
  9. Clique em Salvar conexão SSO. Se o login do owner tem mais de 15 minutos, o QX pede a senha.
O formulário não mostra Vincular usuários do QX pelo e-mail nem Criar usuário no primeiro login. Depois de salvar, o quadro Endereços para o provedor de identidade mostra a URL de login. Uma mudança no papel das pessoas, no grupo dos owners 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.

​
4. Grave a URL de login no Entra ID

O portal My Apps abre o app pelo loginUrl do service principal. Grave a URL de login do QX nesse valor. O campo do portal que grava o loginUrl: não conferido em fonte oficial. Sem esse valor, a pessoa abre o QX pela URL de login, guardada nos favoritos do navegador.

​
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 Entra ID

Os nomes dos menus deste passo: não conferido em fonte oficial.
  1. Abra o enterprise application do QX e depois Provisioning. Escolha o provisionamento automático.
  2. Em Tenant URL, cole a Base URL do provisionamento de usuários, sem barra no fim.
  3. Em Secret Token, cole a chave de provisionamento.
  4. Clique em Test Connection. O Entra ID procura um usuário que não existe, e o QX responde com uma lista vazia.
  5. Salve a configuração.
  6. Nos mapeamentos de atributos dos usuários, troque a origem de externalId: de mailNickname, o padrão, para objectId.
  7. Desligue o mapeamento de grupos. O Entra ID só deixa desligar esse mapeamento depois que o job de provisionamento existe. O QX não recebe grupos.
  8. Atribua ao enterprise application as pessoas que usam o QX.
  9. Ligue o provisionamento.
O externalId leva o objectId da pessoa. O QX liga a pessoa ao login quando o oid do token é igual ao externalId. O objectId da pessoa tem o mesmo valor do oid (não conferido em fonte oficial). Com o padrão mailNickname, o login com SSO não encontra 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 Entra ID e pede um novo login. 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 Entra ID ao usuário do owner no QX. O provisionamento de usuários não precisa ligar o owner antes. O teste pede três coisas:
  • O token traz auth_time. Sem ele, o teste falha com “O provedor de identidade não mandou a hora do login (auth_time).”
  • 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 Entra ID, o owner entra no Entra ID 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 portal My Apps, ou pela URL de login, e confere o login.

​
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 Microsoft Entra ID: o QX aceita o login com SSO só quando o claim opcional amr confirma o segundo fator. O 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. O Entra ID põe mfa no amr só depois de uma autenticação multifator. Sem o claim opcional amr, o QX recusa cada login.
  • Pelo app autenticador do QX: depois do login no Entra ID, 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 Entra ID.
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 Entra ID, e o token precisa trazer auth_time. Para trocar de app, a pessoa pede o reset do segundo fator a outro owner ou ao suporte do QX. Quando o login com SSO tem mais de 15 minutos, um ato sensível pede a confirmação de identidade. O QX pede um novo login no Entra ID. Quando o token não traz auth_time, o QX pede o código do app autenticador. A confirmação por código exige o app já cadastrado.

​
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 Entra ID. 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.
  • O QX reconhece a pessoa pelo oid. O sub do Entra ID muda de um app para outro, e um app registration novo muda o sub de cada pessoa.
  • O QX confere a cada login que o claim tid é o tenant do endereço do provedor.
  • O token traz o e-mail com o escopo email. A Microsoft diz que esse valor pode mudar e não tem verificação. Por isso, o QX não liga nem cria usuário pelo e-mail com o Entra ID.
  • 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.
  • Para desativar uma pessoa, tire a pessoa da atribuição do app ou desabilite a pessoa no Entra ID. O Entra ID manda active=false, e o QX desativa o usuário. Todas as sessões do usuário terminam no mesmo instante. Depois de tirar a pessoa da atribuição, o Entra ID deixa de gerenciar o usuário e nunca manda a exclusão.
  • O Entra ID manda a exclusão de uma pessoa só depois da exclusão definitiva, 30 dias depois da exclusão temporária ou quando um administrador apaga a pessoa de vez. 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.
  • Para reativar uma pessoa, atribua a pessoa ao app de novo. 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 Entra ID. O owner vê o usuário no QX, mas não muda esses dados.
  • Uma troca de e-mail no Entra ID não bloqueia o login com SSO. A página do usuário mostra o e-mail do Entra ID 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 Entra ID 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.
  2. A equipe de TI abre Provisioning no enterprise application, cola a chave nova em Secret Token, clica em Test Connection 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 app registration, a equipe de TI cria um client secret novo em Certificates & secrets (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 Entra ID cai

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

​
Remova a conexão SSO

Para trocar de tenant ou de app registration, 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 Entra ID deixa de criar e desativar usuários no QX. Desligue o provisionamento no enterprise application antigo.
  • 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