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

# Guia de Configuração de Metadados SSO

> Instruções passo a passo para habilitar SAML 2.0 SSO na sua instância EK on-premise, registrando seu IdP e carregando seus metadados.

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

Este guia orienta um Super Admin pelo processo de duas partes para habilitar o SAML SSO para um domínio de e-mail: compartilhar os metadados SP do EK com seu IdP, e então carregar os metadados do IdP de volta ao EK.

Não está familiarizado com como o SAML SSO do EK funciona internamente? Comece pela [Visão Geral do SAML SSO](/super-admin/sso/saml-sso-how-it-works) primeiro.

## Pré-requisitos

Antes de começar, confirme o seguinte:

* Sua **implantação EK on-premise** está em execução com tanto o backend (`<your-backend-host>` quanto o frontend (`<your-frontend-host>`) acessíveis pelo navegador do usuário. O IdP só precisa receber respostas SAML HTTP-POST em `<your-backend-host>/user/generic/sso/saml/acs/admin` — ele **não** precisa de conectividade de saída direta ao seu backend se você fornecer os metadados SP como um arquivo para download.
* Você está logado no EK como **Super Admin**. A aba SSO Metadata e todos os seus endpoints subjacentes são restritos a Super Admins.
* Seu IdP é compatível com SAML 2.0 e pode consumir um XML/URL de metadados SP, ou ser configurado manualmente com um Entity ID e URL ACS do SP.
* Seu IdP está configurado para enviar o endereço de e-mail do usuário como o `NameID` SAML, usando o formato `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. O EK usa o NameID para buscar ou provisionar contas de usuário.
* Você conhece o **domínio de e-mail** para o qual deseja habilitar o SSO (por exemplo, `acme.com`). O SSO é vinculado por domínio, então todos os usuários compartilhando esse domínio — `alice@acme.com`, `bob@acme.com`, etc. — serão roteados para o mesmo IdP.
* Você sabe qual **modo de SSO do frontend** sua implantação está executando. Isso é controlado pela variável de ambiente `VITE_ALLOW_ONLY_SSO_LOGIN` no frontend:
  * `true` — SSO de clique único. O domínio é codificado via `VITE_SSO_ENTERPRISE_ID` e deve corresponder exatamente ao domínio para o qual você carrega os metadados.
  * `false` *(padrão)* — SSO com modal de e-mail. O domínio é derivado do e-mail do usuário no login. Vários domínios podem ter seus próprios metadados carregados.

## Parte 1 — Fornecer Metadados SP ao Seu IdP

Seu administrador de IdP precisa registrar o EK como uma aplicação SAML no seu IdP antes que você possa carregar quaisquer metadados do IdP. O EK torna isso simples publicando seus metadados SP por meio de um endpoint público e bem conhecido — sem necessidade de cópia manual de campos.

### O Endpoint de Metadados SP

O backend EK publica seus metadados SP em:

```
https://<your-backend-host>/saml/well-known/sp-metadata
```

A resposta é um `EntityDescriptor` SAML 2.0 compatível com padrões, contendo o Entity ID da sua instância, URL ACS, formato NameID exigido e certificado de assinatura SP (quando configurado). O endpoint é não autenticado por design para que seu IdP possa buscá-lo diretamente.

<Tip>
  Para a referência completa — comportamento do endpoint, XML de exemplo, componentes garantidos vs. opcionais e as variáveis de ambiente do backend (`CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`, `SAML_SP_CERT_FILE`, `SAML_SP_KEY_FILE`) que um operador on-premise pode ajustar no momento da implantação — consulte [Endpoint de Metadados SP](/super-admin/sso/sp-metadata-endpoint).
</Tip>

### Como Compartilhar os Metadados SP

<AccordionGroup>
  <Accordion title="Opção A — Fornecer a URL">
    Se seu IdP puder acessar o host do backend EK, envie a URL bem conhecida diretamente ao seu administrador de IdP:

    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    A maioria dos IdPs modernos (Okta, Entra ID, Ping, OneLogin, Auth0, etc.) pode importar metadados SP de uma URL e preencherá automaticamente a configuração SP — Entity ID, URL ACS, formato NameID e certificado de assinatura — a partir dele.
  </Accordion>

  <Accordion title="Opção B — Baixar e Entregar o Arquivo">
    Se seu IdP não puder acessar o host do backend diretamente — comum em redes segmentadas, ambientes isolados ou quando seu IdP é um SaaS fora do perímetro corporativo — baixe o XML e passe-o ao seu administrador de IdP por canal alternativo:

    ```bash theme={null}
    curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Seu administrador de IdP carrega `ek_sp_metadata.xml` na tela de configuração da aplicação SAML do IdP. Você só precisa reexportar e recarregar quando a configuração SP mudar — tipicamente uma alteração de hostname do backend, rotação de certificado de assinatura SP ou alteração de override do Entity ID.
  </Accordion>
</AccordionGroup>

### Configuração Manual (Quando o IdP Não Pode Consumir Metadados)

Se seu IdP exigir que os campos sejam inseridos manualmente, use os valores do XML de metadados SP. Os campos mais comumente exigidos são:

| Campo                                        | Valor                                                                                                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entity ID / Audience**                     | O atributo `entityID` no `<md:EntityDescriptor>` na resposta de metadados SP. Padrão para a URL ACS; pode ser sobrescrito no momento da implantação via `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`. |
| **ACS URL / Reply URL / Single Sign-On URL** | `https://<your-backend-host>/user/generic/sso/saml/acs/admin` — sempre o host do backend, nunca o frontend.                                                                                 |
| **Binding**                                  | HTTP-POST                                                                                                                                                                                   |
| **Formato NameID**                           | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`                                                                                                                                    |
| **Sign AuthnRequests**                       | `true` se sua implantação EK tiver um certificado SP configurado (anunciado nos metadados como `AuthnRequestsSigned`); caso contrário, `false`.                                             |
| **Want Assertions Signed**                   | `true` — sempre. O EK requer assinatura de asserções.                                                                                                                                       |

<Warning>
  O IdP deve enviar o endereço de e-mail do usuário como o `NameID` SAML. Se o IdP enviar um ID interno opaco, o login falhará ou criará contas com chave incorreta.
</Warning>

### O Que Seu Administrador de IdP Precisa Devolver

Depois que a aplicação SAML for criada no seu IdP, peça ao seu administrador de IdP os **metadados XML do IdP SAML**. Este é o arquivo que você carregará na Parte 2.

Quase todo IdP pode produzir este arquivo. Nomes comuns para ele nas interfaces do IdP:

| IdP                                           | Onde Encontrar                                                                                |
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Okta**                                      | Link *"Identity Provider metadata"* na aba *Sign On* da aplicação                             |
| **Entra ID / Azure AD**                       | Download *"Federation Metadata XML"* na aba SSO                                               |
| **Ping / OneLogin / Auth0 / ADFS / Keycloak** | Geralmente rotulado como *"Metadata"* ou *"SAML Metadata"*, disponível para download como XML |

O XML deve ser um `EntityDescriptor` SAML 2.0 válido contendo um `IDPSSODescriptor` com pelo menos o `entityID` do IdP, um local e ligação `SingleSignOnService`, e o certificado de assinatura do IdP para que o EK possa verificar as asserções.

## Parte 2 — Carregar os Metadados do IdP

Com o XML de metadados do IdP em mãos, você pode agora registrá-lo contra um domínio de e-mail na sua instância EK.

### Abrir a Aba de Metadados SSO

<Steps>
  <Step title="Fazer login no EK">
    Faça login no EK como Super Admin.
  </Step>

  <Step title="Abrir o Painel do Super Admin">
    Vá para o menu da sua conta no canto superior direito e clique em **Super Admin Dashboard**.
  </Step>

  <Step title="Ir para a aba de Metadados SSO">
    Mude para a aba **SSO Metadata**. Você verá uma tabela de mapeamentos existentes domínio → metadados com três colunas:

    * **SSO Domain** — o domínio de e-mail para o qual os metadados estão registrados (por exemplo, `acme.com`).
    * **Updated** — a última vez que os metadados para aquele domínio foram carregados ou substituídos.
    * **Actions** — controles para baixar, atualizar ou excluir os metadados armazenados para aquela linha.

    Use a caixa de busca no canto superior direito para filtrar por domínio. A tabela é ordenável por **SSO Domain** ou **Updated**.
  </Step>
</Steps>

### Adicionar Metadados para um Novo Domínio

<Steps>
  <Step title="Abrir o diálogo de Adicionar Metadados">
    Clique em **Add Metadata** no canto superior direito da aba SSO Metadata. Se nenhum domínio estiver configurado ainda, você também pode clicar nele no cartão de estado vazio.<br /><img src="https://mintcdn.com/automationanywhere/GwZtgh73O0-NsEVq/img/sa/sso/add-metadata-dialog.png?fit=max&auto=format&n=GwZtgh73O0-NsEVq&q=85&s=59176f248d196eb7d6ea959a50732843" alt="Diálogo de Adicionar Metadados" width="700" height="438" data-path="img/sa/sso/add-metadata-dialog.png" />
  </Step>

  <Step title="Inserir o domínio de e-mail">
    No campo **SSO Team Email Domain**, insira o domínio ao qual o SSO deve se aplicar — por exemplo, `acme.com`. Use apenas a porção do domínio do endereço de e-mail: sem `@`, sem caminho, sem esquema. O valor é normalizado para minúsculas ao salvar.

    <Warning>
      Se sua implantação estiver no modo de SSO de clique único (`VITE_ALLOW_ONLY_SSO_LOGIN=true`), este valor deve corresponder exatamente a `VITE_SSO_ENTERPRISE_ID`. Uma incompatibilidade significa que o botão SSO redirecionará os usuários para um domínio sem metadados carregados, e a autenticação falhará no backend.
    </Warning>
  </Step>

  <Step title="Escolher o método de upload e fornecer o XML">
    <Tabs>
      <Tab title="Upload de Arquivo">
        Selecione o arquivo `.xml` fornecido pelo seu administrador de IdP. Apenas arquivos com extensão `.xml` são aceitos.
      </Tab>

      <Tab title="Colar Conteúdo XML">
        Cole o XML completo dos metadados do IdP diretamente na área de texto. O conteúdo deve começar com `<?xml ...?>` ou `<EntityDescriptor ...>`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enviar">
    Clique em **Upload Metadata**. O diálogo é fechado, uma notificação toast confirma o upload, e o novo domínio aparece na tabela.
  </Step>
</Steps>

<Note>
  Cada domínio pode ter no máximo um documento de metadados do IdP ativo por vez. Recarregar para o mesmo domínio substitui os metadados existentes — consulte *Atualizar Metadados para um Domínio Existente* abaixo.
</Note>

### Atualizar Metadados para um Domínio Existente

Os IdPs rodam certificados de assinatura e ocasionalmente alteram endpoints. Quando isso acontecer, coordene com seu administrador de IdP para que o novo XML seja carregado no EK **antes** que o IdP comece a assinar asserções com a nova chave.

<Steps>
  <Step title="Encontrar a linha do domínio">
    Localize o domínio na tabela SSO Metadata.
  </Step>

  <Step title="Clicar em Atualizar">
    Clique em **Update** na coluna Actions da linha.
  </Step>

  <Step title="Fornecer o novo XML">
    O diálogo **Update SSO Metadata** é aberto com o domínio pré-preenchido e bloqueado. Você não pode alterar o domínio em uma atualização — se precisar reaproveitar a entrada, exclua-a e adicione novamente. Escolha seu método de upload e forneça o novo XML como faria para um novo domínio.
  </Step>

  <Step title="Enviar">
    Clique em **Update Metadata**. A substituição tem efeito imediato — o próximo login SSO para aquele domínio usará os novos metadados.
  </Step>
</Steps>

### Baixar os Metadados Atualmente Armazenados

Clique no **ícone de download** na coluna Actions da linha. O arquivo é salvo como `<dominio>_saml_metadata.xml`.

Útil para:

* Confirmar quais metadados do IdP estão ativos nesta instância EK.
* Fornecer uma cópia para sua equipe de segurança ou conformidade para auditoria.
* Fazer um backup antes de realizar uma atualização.

### Excluir Metadados de um Domínio

<Steps>
  <Step title="Clicar em Excluir">
    Clique em **Delete** na coluna Actions da linha.
  </Step>

  <Step title="Confirmar">
    No diálogo de confirmação, leia o aviso, marque a caixa de confirmação — *"I understand this will disable SSO for all users in this domain"* — e clique em **Delete**.
  </Step>
</Steps>

<Danger>
  A exclusão é irreversível. Depois de excluir:

  * O EK não possui mais metadados do IdP arquivados para aquele domínio.
  * Quaisquer novas tentativas de login SSO de usuários `@<domínio>` falharão.
  * Contas existentes — e-mail/senha, Google OAuth ou contas provisionadas por logins SSO anteriores — **não** são excluídas, mas esses usuários não poderão mais fazer login via SSO.

  Para restaurar o SSO para o domínio, você precisará carregar os metadados XML do IdP novamente.
</Danger>

## Lista de Verificação de Ponta a Ponta

Use isso como um roteiro ao habilitar o SAML SSO para um novo domínio de e-mail na sua instância EK on-premise.

<Steps>
  <Step title="Compartilhar metadados SP do EK com seu administrador de IdP">
    Forneça ao seu administrador de IdP os metadados SP do seu backend EK — não do host do frontend.

    * Se seu IdP puder acessar o backend diretamente, aponte-o para:
      ```
      https://<your-backend-host>/saml/well-known/sp-metadata
      ```
    * Caso contrário, baixe o XML e passe-o por canal alternativo:
      ```bash theme={null}
      curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
      ```
  </Step>

  <Step title="Seu administrador de IdP cria a aplicação SAML">
    Uma vez que ele tenha os metadados SP, seu administrador de IdP registra o EK como uma aplicação SAML no seu IdP. Confirme com ele que:

    * O NameID está definido para o endereço de e-mail do usuário.
    * As asserções são assinadas.
    * A audiência / Entity ID corresponde ao valor nos metadados SP do EK.
  </Step>

  <Step title="Receber os metadados XML do IdP">
    Peça ao seu administrador de IdP os metadados XML do IdP assim que a aplicação for criada. Este é o arquivo que você carregará no próximo passo.
  </Step>

  <Step title="Carregar os metadados do IdP no EK">
    Faça login no EK como Super Admin, abra **Super Admin Dashboard → SSO Metadata** e clique em **Add Metadata**. Insira o domínio de e-mail e carregue o XML.
  </Step>

  <Step title="Testar o login">
    Teste com um usuário real `@<domínio>`. Se o usuário autenticar com sucesso, mas tiver o acesso negado, verifique sua configuração de Controles de Acesso SAML — consulte o guia [**Controles de Acesso SAML**](/super-admin/sa-access-controls).
  </Step>

  <Step title="Documentar a alteração">
    Registre o seguinte no seu sistema interno de gestão de alterações: o domínio, o tipo do IdP, a data do upload e qual Super Admin realizou o upload.
  </Step>

  <Step title="Agendar uma atualização de metadados">
    Anote quando o certificado de assinatura do seu IdP está programado para ser renovado e defina um lembrete para carregar metadados atualizados antes dessa data. Use a ação **Update** na aba SSO Metadata quando novos metadados estiverem disponíveis.
  </Step>
</Steps>

***

Encontrando problemas? Consulte o guia [Solução de Problemas e Referência SSO](/super-admin/sso/saml-sso-troubleshooting).