> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de Problemas e Referência SSO

> Permissões, URLs de referência rápida e orientação para solução de problemas do SAML SSO na sua instância EK on-premise.

Este artigo cobre permissões, valores de referência rápida e soluções para problemas comuns de SSO. Para instruções de configuração, consulte o [Guia de Configuração de Metadados SSO](/super-admin/sso/saml-sso-metadata-setup-guide).

## Permissões

Todas as ações de gerenciamento de metadados SSO são restritas a Super Admins, com uma exceção: um administrador de equipe pode carregar metadados do IdP via arquivo para o domínio da sua própria equipe.

| Ação                                                                               | Função Necessária                                                                                        |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Visualizar a aba de Metadados SSO                                                  | Super Admin                                                                                              |
| Carregar metadados do IdP via arquivo (`POST /admin/saml-metadata/upload`)         | Super Admin, ou um administrador de equipe cujo `sso_domain` corresponda ao `email_domain` da sua equipe |
| Carregar metadados do IdP via XML colado (`POST /admin/saml-metadata/upload-text`) | Apenas Super Admin                                                                                       |
| Baixar metadados armazenados (`GET /admin/saml-metadata/download`)                 | Super Admin                                                                                              |
| Excluir metadados armazenados (`DELETE /admin/saml-metadata/delete`)               | Super Admin                                                                                              |

<Note>
  O endpoint de metadados SP em `/saml/well-known/sp-metadata` é público por design. Não contém segredos — apenas o entity ID do SP, URL ACS, formato NameID e certificado público de assinatura.
</Note>

## Referência Rápida

<CardGroup cols={2}>
  <Card title="Host do Backend" icon="server">
    `<your-backend-host>` (por exemplo, `ek-api.corp.acme.com`)

    Processa todo o tráfego SAML — metadados SP, iniciação SSO e o endpoint ACS. **Este é o único host que seu IdP precisa conhecer.**
  </Card>

  <Card title="Host do Frontend" icon="globe">
    `<your-frontend-host>` (por exemplo, `ek.corp.acme.com`)

    A interface web que seus usuários abrem. Configurado no backend via `FRONTEND_ROOT_URL`. **Nunca aparece na configuração do IdP.**
  </Card>

  <Card title="URL de Metadados SP" icon="link">
    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Compartilhe isso com seu administrador de IdP para registrar o EK como uma aplicação SAML.
  </Card>

  <Card title="URL ACS" icon="arrow-right-to-bracket">
    ```
    https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    Onde seu IdP faz POST nas respostas SAML. Sempre o host do backend — nunca o frontend.
  </Card>

  <Card title="Ponto de Entrada SSO Iniciado pelo SP" icon="right-to-bracket">
    ```
    https://<your-backend-host>/sso/login?enterprise_id=<email-domain>
    ```

    O endpoint do backend para o qual o frontend redireciona quando um usuário inicia o SSO.
  </Card>

  <Card title="Formato NameID Necessário" icon="id-card">
    ```
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    ```

    Seu IdP deve enviar o endereço de e-mail do usuário neste formato.
  </Card>
</CardGroup>

### Variáveis de Ambiente do Modo de SSO do Frontend

| Variável                    | Descrição                                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | `true` para SSO de clique único, `false` (padrão) para SSO com modal de e-mail.                                        |
| `VITE_SSO_ENTERPRISE_ID`    | Apenas modo de clique único. Deve corresponder a um domínio que tenha metadados do IdP carregados na aba SSO Metadata. |

* **Onde carregar metadados do IdP?** Painel do Super Admin → aba **SSO Metadata** → **Add Metadata** / **Update**
* **Um documento por domínio.** Recarregar substitui os metadados existentes. Excluir desabilita o SSO para aquele domínio.
* **Função necessária?** Super Admin para todas as ações, exceto administradores de equipe podem carregar via arquivo para o domínio da sua própria equipe.

## Solução de Problemas

<AccordionGroup>
  <Accordion title="Erro &#x22;Please enter a valid domain&#x22;">
    O campo **SSO Team Email Domain** espera um domínio simples como `acme.com` ou `eu.acme.co.uk`. Remova qualquer `@`, `https://`, caminhos ou números de porta antes de enviar.
  </Accordion>

  <Accordion title="Erro &#x22;File must be an XML file&#x22;">
    O carregador de arquivos aceita apenas arquivos com extensão `.xml`. Se seu IdP forneceu os metadados como um arquivo `.txt` ou sem extensão, renomeie-o para `.xml` ou mude para a opção **Paste XML Content**.
  </Accordion>

  <Accordion title="Erro &#x22;Content does not appear to be valid XML&#x22;">
    Ao usar **Paste XML Content**, o conteúdo colado deve começar com `<?xml` ou `<` após remover espaços em branco. Certifique-se de que você copiou o documento de metadados completo e que nenhum preâmbulo ou comentário foi incluído.
  </Accordion>

  <Accordion title="Login é bem-sucedido com o IdP, mas o EK rejeita a asserção">
    Isso é quase sempre causado por um dos seguintes:

    * **Incompatibilidade de certificado** — o certificado de assinatura do IdP nos metadados carregados não corresponde mais ao certificado que o IdP está realmente usando. Isso tipicamente acontece após uma rotação de certificado do IdP. Obtenha metadados novos do seu administrador de IdP e use **Update**.
    * **Formato NameID incorreto** — o IdP não está enviando o endereço de e-mail como o NameID. Confirme que o formato está definido como `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` no lado do IdP.
    * **Incompatibilidade de Entity ID** — a audiência ou Entity ID configurada no seu IdP não corresponde ao Entity ID da sua instância EK. Recompartilhe o XML de metadados SP do EK e peça ao seu administrador de IdP para reimportá-lo.
  </Accordion>

  <Accordion title="Usuário faz login com sucesso, mas tem o acesso negado">
    Isso é controlado por **Super Admin → Access Controls**, não pela aba SSO Metadata. Consulte o guia [**Controles de Acesso SAML**](/super-admin/sa-access-controls) para detalhes sobre `Allow Any New Users` vs `Restrict to SAML Metadata` e [regras de atribuição automática de equipe/projeto](/super-admin/sa-automated-management).
  </Accordion>

  <Accordion title="SSO iniciado pelo IdP não está funcionando">
    Por padrão, o EK apenas aceita respostas SAML iniciadas a partir de seu próprio endpoint `/sso/login` — significando SSO iniciado pelo SP apenas. Para habilitar SSO iniciado pelo IdP (não solicitado), o operador on-premise deve definir `ALLOW_IDP_INITIATED_SSO=true` no backend EK e reiniciar o serviço. Esta é uma configuração de nível de implantação, não algo configurável na aba SSO Metadata.
  </Accordion>

  <Accordion title="IdP configurado com o host do frontend em vez do host do backend">
    Se a aplicação do IdP foi configurada com o hostname do frontend do EK para a URL ACS ou Entity ID, as respostas SAML serão enviadas para o serviço errado e a autenticação falhará silenciosamente — geralmente exibindo um 404 ou uma página de erro genérica após a tela de login do IdP.

    Peça ao seu administrador de IdP para confirmar que:

    * A **URL ACS** é `https://<your-backend-host>/user/generic/sso/saml/acs/admin`.
    * O **Entity ID / Audience** corresponde ao `entityID` em `https://<your-backend-host>/saml/well-known/sp-metadata`.

    O host do frontend nunca deve aparecer na configuração da aplicação SAML do IdP.
  </Accordion>

  <Accordion title="Botão de SSO de clique único não faz nada (ou mostra &#x22;Could not determine domain for SSO login&#x22;)">
    `VITE_SSO_ENTERPRISE_ID` não está definido no frontend. Defina-o para o domínio de e-mail para o qual você carregou metadados do IdP, depois reimplante ou reinicie o frontend para que o valor tenha efeito.
  </Accordion>

  <Accordion title="Botão de SSO de clique único redireciona, mas o SSO falha no backend">
    `VITE_SSO_ENTERPRISE_ID` está definido, mas não corresponde a nenhum domínio com metadados carregados na aba SSO Metadata. Corrija isso:

    * Carregando metadados do IdP para o domínio atualmente em `VITE_SSO_ENTERPRISE_ID` — recomendado, pois mantém sua configuração do frontend inalterada.
    * Atualizando `VITE_SSO_ENTERPRISE_ID` para corresponder a um domínio que já tenha metadados carregados, depois reimplantando ou reiniciando o frontend.

    Os dois valores devem corresponder exatamente (insensível a maiúsculas/minúsculas).
  </Accordion>

  <Accordion title="SSO com modal de e-mail mostra &#x22;Your organization is not configured for SSO login&#x22;">
    O domínio de e-mail do usuário não tem metadados do IdP carregados na aba SSO Metadata. Carregue metadados para aquele domínio, ou peça ao usuário para fazer login usando e-mail/senha ou OAuth.
  </Accordion>

  <Accordion title="Usuários completam o SSO, mas caem na página errada ou recebem erro de redirecionamento">
    Após uma resposta SAML bem-sucedida, o EK redireciona o usuário para a URL do frontend definida por `FRONTEND_ROOT_URL` no backend. Se esta variável não estiver definida, apontar para o host errado, ou usar o esquema ou porta errados, o usuário parecerá finalizar a autenticação, mas cairá em uma página quebrada.

    Peça ao seu operador on-premise para confirmar que `FRONTEND_ROOT_URL` corresponde exatamente a `https://<your-frontend-host>` — esquema correto, porta correta, sem problemas de barra final.
  </Accordion>
</AccordionGroup>