SP 메타데이터 엔드포인트

SAML SSO 구성 중에 사용되는 EK 서비스 제공자 메타데이터 엔드포인트에 대한 기술 참고.

EK 백엔드는 **ID 제공자(IdP)**가 애플리케이션과 신뢰를 자동으로 구축하기 위해 사용할 수 있는 공개 SAML 서비스 제공자(SP) 메타데이터 엔드포인트를 노출합니다. 이를 통해 SSO 설정 중에 관리자가 SP 구성 세부 정보를 수동으로 교환할 필요가 없어집니다.

​

엔드포인트

GET /saml/well-known/sp-metadata

속성	값
인증	없음(공개 접근 가능)
Content-Type	application/samlmetadata+xml
Content-Disposition	inline; filename="sp_metadata.xml"

​

목적

IdP(예: Okta, Azure AD, OneLogin)와 EK 간에 SAML SSO를 구성할 때 IdP는 SP에 대한 여러 가지를 알아야 합니다:

• 엔티티 ID — SP의 고유 식별자.
• Assertion 컨sumer 서비스(ACS) URL — IdP가 SAML 응답을 POST해야 하는 위치.
• 지원되는 NameID 형식 — IdP가 사용자를 식별하는 방법.
• 서명 인증서 (해당되는 경우) — 서명된 AuthnRequest를 확인하는 데 사용할 수 있는 공개 키.

관리자가 각 값을 개별적으로 복사-붙여넣어야 하는 대신 이 엔드포인트는 모든 값을 하나의 표준 호환 SAML 2.0 메타데이터 XML 문서로 제공합니다. 관리자는 IdP를 이 URL로 직접 가리키거나 XML을 다운로드하여 IdP에 업로드할 수 있습니다.

설정 중에 이 엔드포인트를 사용하는 방법에 대한 단계별 지침은 SSO 메타데이터 설정 가이드를 참조하세요.

​

응답 형식

엔드포인트는 SAML 2.0 EntityDescriptor 문서를 반환합니다. 아래는 대표적인 예시입니다:

<?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-인코딩-인증서...</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>

​

보장 대 선택적 구성 요소

​

보장(항상 존재)

XML 요소 / 속성	설명
<md:EntityDescriptor entityID="...">	SP 엔티티 ID. CUSTOM_ENTITY_ID_FOR_GENERIC_SSO가 설정되지 않은 경우 ACS URL이 기본값; 설정된 경우 해당 값이 대신 사용됨.
<md:SPSSODescriptor>	모든 SP SSO 설명자 정보의 컨테이너. 항상 WantAssertionsSigned="true"와 protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"을 포함.
AuthnRequestsSigned 속성	항상 SPSSODescriptor에 존재. SP 서명 인증서가 구성된 경우 "true", 그렇지 않으면 "false".
<md:NameIDFormat>	항상 urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. EK는 IdP가 NameID로 사용자의 이메일 주소를 제공할 것을 기대합니다.
<md:AssertionConsumerService>	ACS 엔드포인트. 항상 HTTP-POST 바인딩, 인덱스 0 및 isDefault="true"를 사용합니다. Location은 EK 백엔드 루트 URL에서 파생됩니다: {BACKEND_ROOT_URL}/user/generic/sso/saml/acs/admin.

​

선택적(조건부로 존재)

XML 요소 / 속성	조건	설명
<md:KeyDescriptor use="signing">	서버가 SAML_SP_CERT_FILE 및 SAML_SP_KEY_FILE을 통해 유효한 SP 서명 인증서와 키로 구성된 경우에만 존재.	서명된 AuthnRequest를 확인할 수 있도록 IdP에 SP의 X.509 서명 인증서를 포함. 없으면 AuthnRequest는 서명되지 않고 전송되며 AuthnRequestsSigned는 "false"임.

​

관련 환경 변수

변수	메타데이터에 미치는 영향
CUSTOM_ENTITY_ID_FOR_GENERIC_SSO	설정되면 기본 entityID(ACS URL)를 재정의함.
SAML_SP_CERT_FILE	SP의 PEM 인코딩 X.509 인증서 경로. SAML_SP_KEY_FILE과 함께 설정되면 KeyDescriptor 블록이 포함되고 AuthnRequestsSigned가 "true"가 됨.
SAML_SP_KEY_FILE	SP의 PEM 인코딩 개인 키 경로. 요청 서명을 활성화하려면 SAML_SP_CERT_FILE과 함께 필요.