> ## 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 Okta > Como a equipe de TI liga o Okta ao QX: o login com SSO, o provisionamento de usuários e o SSO obrigatório. 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](/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**. | Endereço no QX | Campo no Okta | | - | - | | URL de login | **Initiate login URI**, no app OIDC | | URI de redirecionamento | **Sign-in redirect URIs**, no app OIDC | | Base URL do provisionamento de usuários | **SCIM connector base URL**, na configuração do SCIM | 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: ```text theme={null} https://app.useqx.com/sso/callback https://app.useqx.com/scim/v2 ``` ## 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://`), 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:///oauth2/`), 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://` para o servidor da org, ou `https:///oauth2/` 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 | Mensagem que a pessoa vê | O que a equipe de TI confere | | - | - | | A sua organização exige um segundo fator. | O `acr` do Okta, como na seção **Verificação em duas etapas**. A pessoa entra no Okta 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 Okta. | | O provedor de identidade não mandou os grupos do seu usuário. | O claim `groups` do app ou do servidor de autorização, 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 Okta e a atribuição do app. | | O QX não encontrou o seu usuário. | O e-mail da pessoa no Okta e no QX, o provisionamento de usuários e a opção **Vincular usuários do QX pelo e-mail**. | | O provedor de identidade não pediu um login novo. | O Okta Classic. O QX testa só o Okta Identity Engine. | | O provedor de identidade não respondeu. | O status do Okta. Tente de novo em alguns minutos. | | Não foi possível entrar com SSO. | **Autenticação do cliente**, o client secret, o **Endereço do provedor de identidade** e, com o grupo dos owners, o escopo `groups` no servidor de autorização. | ## Fontes * Okta, [Authorization servers](https://developer.okta.com/docs/concepts/auth-servers/). * Okta, [OpenID Connect & OAuth 2.0 API](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview/). * Okta, [Customize tokens returned from Okta with a Groups claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/). * Okta, [Step-up authentication](https://developer.okta.com/docs/guides/step-up-authentication/main/). * Okta, [Custom URL domain](https://developer.okta.com/docs/guides/custom-url-domain/main/). * Okta, [Create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm). * Okta, [Develop a custom OpenID Connect application that can support SSO when launched from the Okta dashboard](https://support.okta.com/help/s/article/develop-a-custom-openid-connect-application-that-can-support-sso-when-launched-from-the-okta-dashboard). * Okta, [Okta and SCIM Version 2.0](https://developer.okta.com/docs/api/openapi/okta-scim/guides/scim-20/). * Okta, [SCIM FAQs](https://developer.okta.com/docs/concepts/scim/faqs/). * Okta, [Create SCIM app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm). * Okta, documentos de discovery dos servidores da org `okta.okta.com`: `https://okta.okta.com/.well-known/openid-configuration` e `https://okta.okta.com/oauth2/default/.well-known/openid-configuration`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.