> ## 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.

# SAML SSO no EK — Como Funciona

> Entenda como o EK se integra com seu Identity Provider para SAML 2.0 SSO antes de começar a configuração.

<Note>
  Este guia foi escrito para administradores de TI e identidade que gerenciam uma instância EK on-premise. Qualquer referência a "seu IdP", "seu administrador de IdP" ou "seu domínio de e-mail" refere-se à infraestrutura da sua própria organização — não a nada gerenciado pela Automation Anywhere.
</Note>

O EK suporta **SAML 2.0 SSO** para implantações on-premise, permitindo que seus usuários façam login por meio do **Identity Provider (IdP)** existente da sua organização. A configuração é feita inteiramente por meio da aba **Super Admin Dashboard → SSO Metadata** — sem necessidade de alterações de código.

O EK funciona com qualquer **IdP SAML 2.0 compatível com padrões** — Okta, Azure AD / Entra ID, Ping, ADFS, OneLogin, Auth0, Keycloak, Google Workspace e outros. Uma vez que você carregue os metadados do IdP para um domínio de e-mail, o EK roteará automaticamente o SSO para qualquer usuário cujo e-mail pertença a esse domínio.

## Entendendo Seus Dois Hostnames do EK

Uma implantação EK on-premise tem dois hostnames com funções distintas:

* `<your-backend-host>` — processa todo o tráfego SAML: metadados SP, iniciação SSO e o endpoint ACS. **Este é o único host que seu IdP precisa conhecer.** *(Exemplo: `ek-api.corp.acme.com`)*
* `<your-frontend-host>` — a interface web que seus usuários abrem no navegador. O EK redireciona os usuários para cá após um login bem-sucedido, configurado via a variável de ambiente `FRONTEND_ROOT_URL`. **Este host nunca aparece na configuração do seu IdP.** *(Exemplo: `ek.corp.acme.com`)*

## Como o SAML SSO Funciona no EK

Configurar o SAML SSO requer uma troca mútua de confiança entre dois sistemas. Cada lado precisa saber quem é o outro antes que qualquer autenticação possa acontecer:

<CardGroup cols={2}>
  <Card title="Service Provider (SP) — EK" icon="server">
    Sua instância EK on-premise. O EK publica metadados SP para que seu IdP saiba para onde enviar respostas SAML, qual formato de NameID usar e qual certificado de assinatura confiar nas AuthnRequests.
  </Card>

  <Card title="Identity Provider (IdP) — Sua Organização" icon="shield-halved">
    O Okta, Entra ID, Ping, ADFS, etc. da sua organização. Seu IdP publica seus próprios metadados XML descrevendo seu emissor, endpoint SSO e certificado de assinatura — o EK precisa disso para validar as asserções que seu IdP retorna.
  </Card>
</CardGroup>

Para habilitar o SSO para um domínio de e-mail (por exemplo, `acme.com`), um Super Admin precisa completar ambos os lados desta troca:

<Steps>
  <Step title="Compartilhar Metadados SP com Seu IdP">
    Forneça ao seu administrador de IdP os metadados SP publicados pela sua instância EK para que ele possa registrar o EK como uma aplicação SAML no seu IdP.
  </Step>

  <Step title="Carregar Metadados do IdP no EK">
    Depois que a aplicação do IdP for criada, carregue os metadados XML resultantes do IdP no EK por meio de **Super Admin → SSO Metadata**, vinculados ao domínio de e-mail que os usuários usarão para login.
  </Step>
</Steps>

Uma vez que ambos os lados estejam configurados, qualquer usuário com um e-mail terminando em `@<domínio>` pode fazer login no EK via SAML SSO por meio do IdP corporativo.

## Como o Usuário Atinge o Fluxo SSO

A tela de login do EK sempre mostra uma opção "Sign in with SSO". O que acontece quando um usuário clica nela depende de duas variáveis de ambiente do frontend incorporadas à compilação da interface web do EK:

| Variável                    | Finalidade                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | Determina qual modo de SSO a tela de login usa.                                                     |
| `VITE_SSO_ENTERPRISE_ID`    | Usado apenas no modo de clique único para especificar o domínio de e-mail contra o qual autenticar. |

<AccordionGroup>
  <Accordion title="Modo A — SSO de clique único (VITE_ALLOW_ONLY_SSO_LOGIN=true)">
    A tela de login mostra apenas um botão SSO — sem campos de e-mail ou senha. Esta é a configuração típica para uma implantação on-premise atendendo um único domínio de e-mail.

    Quando o usuário clica no botão, o frontend lê `VITE_SSO_ENTERPRISE_ID` e redireciona imediatamente para:

    ```
    https://<your-backend-host>/sso/login?enterprise_id=<VITE_SSO_ENTERPRISE_ID>&target_url=https://<your-frontend-host>/okta/authenticate
    ```

    Para que isso funcione:

    * `VITE_SSO_ENTERPRISE_ID` deve estar definido no frontend.
    * Seu valor deve corresponder a um domínio que tenha metadados do IdP carregados na aba **SSO Metadata**.
    * Ao carregar os metadados, o **SSO Team Email Domain** deve corresponder exatamente a `VITE_SSO_ENTERPRISE_ID` (insensível a maiúsculas/minúsculas; os valores são normalizados para minúsculas ao salvar).

    Se `VITE_SSO_ENTERPRISE_ID` não estiver definido, o usuário vê *"Could not determine domain for SSO login"* e não pode prosseguir. Se estiver definido, mas não houver metadados para esse domínio, o redirecionamento é feito, mas o SSO falha no backend.
  </Accordion>

  <Accordion title="Modo B — SSO com modal de e-mail (VITE_ALLOW_ONLY_SSO_LOGIN=false, padrão)">
    A tela de login mostra e-mail/senha e controles de SSO juntos. Clicar no botão SSO abre um modal *"Enter your email"*. Após o usuário enviar seu e-mail, o frontend extrai o domínio e verifica com o backend se o SSO está configurado para ele via `POST https://<your-backend-host>/sso/verify_enterprise_id`.

    * Se **sim**, o frontend redireciona para:
      ```
      https://<your-backend-host>/sso/login?enterprise_id=<email-domain>&target_url=https://<your-frontend-host>/okta/authenticate
      ```
    * Se **não**, o usuário vê *"Your organization is not configured for SSO login. Please contact your administrator."*

    `VITE_SSO_ENTERPRISE_ID` não é usado neste modo. Vários domínios podem coexistir — cada um precisa de seus próprios metadados do IdP carregados na aba SSO Metadata.
  </Accordion>
</AccordionGroup>

<Info>
  Ambos os modos usam o mesmo endpoint backend `/sso/login` com o mesmo parâmetro `enterprise_id`. A única diferença é se esse valor é codificado por uma variável de ambiente do frontend (Modo A) ou derivado do e-mail do usuário no login (Modo B).
</Info>

## O Que o Backend Faz com `enterprise_id`

Quando o backend recebe `GET /sso/login?enterprise_id=acme.com`, ele busca os metadados do IdP carregados para `acme.com` e constrói uma configuração SAML SP em tempo de execução:

| Parâmetro                 | Valor                                                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entity ID**             | `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO` se definido no momento da implantação; caso contrário, padrão para `https://<your-backend-host>/user/generic/sso/saml/acs/admin` |
| **Endpoint ACS**          | `https://<your-backend-host>/user/generic/sso/saml/acs/admin` (ligação HTTP-POST)                                                                                   |
| **Formato NameID**        | `emailAddress`                                                                                                                                                      |
| **Metadados IdP remotos** | Uma URL assinada apontando para o XML carregado no armazenamento                                                                                                    |

Se não houver metadados arquivados para o `enterprise_id` fornecido, o backend não pode construir uma configuração SAML SP e a tentativa de SSO falha.

## Cadeia de Redirecionamento no Nível do Navegador

Uma vez que `enterprise_id` resolve para metadados carregados, a autenticação prosegue como uma sequência de redirecionamentos do navegador:

<Steps>
  <Step title="O usuário começa no frontend">
    O usuário abre o EK em `https://<your-frontend-host>` e clica no botão SSO.
  </Step>

  <Step title="Frontend → Backend">
    O frontend redireciona o navegador para o ponto de entrada SSO do backend:

    ```
    GET https://<your-backend-host>/sso/login?enterprise_id=acme.com&target_url=https://<your-frontend-host>/okta/authenticate
    ```
  </Step>

  <Step title="Backend → IdP">
    O backend constrói uma AuthnRequest SAML a partir dos metadados do IdP carregados para `acme.com` e redireciona o navegador para o endpoint SSO do seu IdP.
  </Step>

  <Step title="IdP autentica o usuário">
    Seu IdP processa a autenticação — senha, MFA, certificado, ou o que sua organização tiver configurado.
  </Step>

  <Step title="IdP → Backend">
    O IdP faz POST na resposta SAML para o endpoint ACS do backend EK:

    ```
    POST https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    O backend valida a asserção contra o certificado de assinatura do IdP dos metadados carregados, depois faz login do usuário em sua conta EK existente ou provisiona uma nova.
  </Step>

  <Step title="Backend → Frontend">
    O backend redireciona o navegador do usuário de volta ao EK em `<your-frontend-host>`. A URL exata é determinada pela variável de ambiente `FRONTEND_ROOT_URL` no backend — se estiver configurada incorretamente, o usuário parecerá completar o SSO com sucesso, mas cairá na página errada.
  </Step>
</Steps>

<Note>
  O IdP apenas interage com `<your-backend-host>`. O host do frontend aparece no início do fluxo (onde o usuário começa) e no final (onde ele aterrissa após o login) — ele nunca aparece em nenhuma URL voltada para o IdP.
</Note>

Pronto para configurar o SSO? Consulte o [Guia de Configuração de Metadados SSO](/super-admin/sso/saml-sso-metadata-setup-guide) para instruções passo a passo.