> ## 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 Microsoft Entra ID > Como a equipe de TI liga o Microsoft Entra ID ao QX: o app registration, os claims opcionais, o provisionamento de usuários e o SSO obrigatório. 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](/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**. | Endereço no QX | Campo no Entra ID | | - | - | | URL de login | O `loginUrl` do app, que o portal My Apps abre. O campo do portal que grava o `loginUrl`: não conferido em fonte oficial. | | URI de redirecionamento | **Redirect URI** do app registration, na plataforma Web | | Base URL do provisionamento de usuários | **Tenant URL**, no provisionamento do enterprise application | 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 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//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 | Mensagem que a pessoa vê | O que a equipe de TI confere | | - | - | | A sua organização exige um segundo fator. | O claim opcional `amr`, como na seção **Verificação em duas etapas**. A pessoa entra no Entra ID com o segundo fator. | | 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 Entra ID. | | O provedor de identidade não mandou os grupos do seu usuário. | O claim de grupos do app, quando o grupo dos owners define o papel. O número de grupos da pessoa e a opção **Groups assigned to the application**. | | O provedor de identidade não mandou a hora do login (auth\_time). | O claim opcional `auth_time` no token de ID. | | O seu acesso ao QX está desativado. | A atribuição da pessoa ao app e o estado da pessoa no Entra ID. | | O QX não encontrou o seu usuário. | O mapeamento de `objectId` para `externalId` no provisionamento de usuários. Se o provisionamento já criou a pessoa. | | O provedor de identidade não respondeu. | O status do Entra ID. Tente de novo em alguns minutos. | | Não foi possível entrar com SSO. | O client secret, a **Autenticação do cliente**, a URI de redirecionamento, o ID do tenant no endereço do provedor e o claim `email` no token de ID. | ## Fontes * Microsoft, [ID token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference). * Microsoft, [Optional claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference). * Microsoft, [OpenID Connect on the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc). * Microsoft, [Microsoft identity platform and OAuth 2.0 authorization code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow). * Microsoft, [Configure group claims](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims). * Microsoft Graph, [servicePrincipal resource type](https://learn.microsoft.com/en-us/graph/api/resources/serviceprincipal?view=graph-rest-1.0). * Microsoft, [Tutorial: Develop and plan provisioning for a SCIM endpoint](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups). * Microsoft, [Known issues and resolutions with SCIM 2.0 protocol compliance](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility). * Microsoft, [How application provisioning works](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works). * Microsoft, [Customize application attributes](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes). * Microsoft, [OpenID Connect discovery document](https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.