Endpoint de Metadados SP

Referência técnica do endpoint de metadados do Service Provider do EK usado durante a configuração do SAML SSO.

O backend EK expõe um endpoint público de metadados do SAML Service Provider (SP) que os Identity Providers (IdPs) podem consumir para estabelecer confiança automaticamente com a aplicação. Isso elimina a necessidade de os administradores trocarem manualmente detalhes de configuração do SP durante a configuração do SSO.

​

Endpoint

GET /saml/well-known/sp-metadata

Propriedade	Valor
Autenticação	Nenhuma (acessível publicamente)
Content-Type	application/samlmetadata+xml
Content-Disposition	inline; filename="sp_metadata.xml"

​

Finalidade

Ao configurar o SAML SSO entre um IdP (por exemplo, Okta, Azure AD, OneLogin) e o EK, o IdP precisa saber várias coisas sobre o SP:

• Entity ID — um identificador único para o SP.
• URL do Assertion Consumer Service (ACS) — onde o IdP deve fazer POST nas respostas SAML.
• Formato NameID suportado — como o IdP deve identificar o usuário.
• Certificado de assinatura (se aplicável) — a chave pública que o IdP pode usar para verificar AuthnRequests assinados.

Em vez de exigir que um administrador copie e cole cada um desses valores individualmente, este endpoint os fornece todos em um único documento XML de metadados SAML 2.0 compatível com padrões. Os administradores podem apontar seu IdP diretamente para esta URL ou baixar o XML e carregá-lo no IdP.

Para instruções passo a passo sobre como usar este endpoint durante a configuração, consulte o Guia de Configuração de Metadados SSO.

​

Formato da Resposta

O endpoint retorna um documento EntityDescriptor SAML 2.0. Abaixo está um exemplo representativo:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://api.example.com/user/generic/sso/saml/acs/admin">
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIC...base64-encoded-cert...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                Location="https://api.example.com/user/generic/sso/saml/acs/admin"
                                index="0"
                                isDefault="true" />
  </md:SPSSODescriptor>
</md:EntityDescriptor>

​

Componentes Garantidos vs. Opcionais

​

Garantidos (sempre presentes)

Elemento / Atributo XML	Descrição
<md:EntityDescriptor entityID="...">	O Entity ID do SP. Padrão para a URL ACS, a menos que CUSTOM_ENTITY_ID_FOR_GENERIC_SSO esteja definido, caso em que esse valor é usado.
<md:SPSSODescriptor>	Contêiner para todas as informações do descritor SSO do SP. Sempre inclui WantAssertionsSigned="true" e protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol".
Atributo AuthnRequestsSigned	Sempre presente no SPSSODescriptor. Definido como "true" quando um certificado de assinatura SP está configurado, "false" caso contrário.
<md:NameIDFormat>	Sempre urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. O EK espera que o IdP forneça o endereço de e-mail do usuário como o NameID.
<md:AssertionConsumerService>	O endpoint ACS. Sempre usa ligação HTTP-POST, índice 0, e isDefault="true". O Location é derivado da URL raiz do backend EK: {BACKEND_ROOT_URL}/user/generic/sso/saml/acs/admin.

​

Opcionais (presentes condicionalmente)

Elemento / Atributo XML	Condição	Descrição
<md:KeyDescriptor use="signing">	Presente apenas quando o servidor está configurado com um certificado e chave de assinatura SP válidos via SAML_SP_CERT_FILE e SAML_SP_KEY_FILE.	Contém o certificado X.509 de assinatura do SP para que o IdP possa verificar AuthnRequests assinados. Quando ausente, os AuthnRequests são enviados sem assinatura e AuthnRequestsSigned é "false".

​

Variáveis de Ambiente Relacionadas

Variável	Efeito nos Metadados
CUSTOM_ENTITY_ID_FOR_GENERIC_SSO	Se definido, sobrescreve o entityID padrão (que é a URL ACS).
SAML_SP_CERT_FILE	Caminho para o certificado X.509 codificado em PEM do SP. Quando definido junto com SAML_SP_KEY_FILE, o bloco KeyDescriptor é incluído e AuthnRequestsSigned torna-se "true".
SAML_SP_KEY_FILE	Caminho para a chave privada codificada em PEM do SP. Necessário junto com SAML_SP_CERT_FILE para habilitar a assinatura de requisições.