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

# 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 메타데이터 설정 가이드](/super-admin/sso/saml-sso-metadata-setup-guide)를 참조하세요.

## 응답 형식

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

```xml theme={null}
<?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`과 함께 필요.                                                     |