# 연결의 SAML SP 메타데이터 다운로드

`GET /v1/connections/{connection_id}/sp-metadata` · 권한 `connections:read`

엔터프라이즈 SAML 연결의 서명된 SAML 2.0 서비스 공급자(SP) 메타데이터 문서를 다운로드합니다. 이 파일은 ID 공급자 관리자가 ID 공급자에 업로드하는 파일입니다. 연결의 공개 메타데이터 주소(`https://<sp host>/saml/<conn_…>/metadata`)가 제공하는 문서와 동일합니다.

- `entityID`, `validUntil`(7일 후), `cacheDuration`(`PT24H`);
- 서명 및 암호화 인증서(매년 키 교체 기간에는 각각 두 개);
- 지원되는 NameID 형식, 어설션 소비자 서비스(HTTP-POST) 및 단일 로그아웃 엔드포인트;
- 연결의 활성 SP 서명 키로 만든 enveloped XML 서명.

SP 키가 아직 없으면 처음 사용할 때 생성됩니다. 문서에는 비밀 값이 포함되지 않습니다. 조회는 감사 로그에 기록되지 않습니다.

`revision_id`를 지정하면 [초안 리비전](revisions.md)의 문서를 대신 받을 수 있습니다. [SP 호스트 마이그레이션](migrate-sp-host.md)의 경우 문서에는 새 호스트의 엔드포인트가 포함됩니다. 리비전을 게시하기 전에 ID 공급자 관리자에게 전달하십시오.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `connection_id` | path | 예 | 엔터프라이즈 연결 ID(`conn_…`). |
| `revision_id` | query | 아니요 | 연결의 초안 리비전(`connrev_…`). |

## 응답

`200 OK`와 함께 XML 문서가 본문으로 반환됩니다.

| 헤더 | 값 |
|---|---|
| `Content-Type` | `application/samlmetadata+xml` |
| `Content-Disposition` | `attachment; filename="<conn_…>-sp-metadata.xml"` |
| `Cache-Control` | `no-store` |

```xml
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    ID="_…" entityID="https://acme.eu.keenauth.app/saml/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/metadata"
    validUntil="2026-11-02T10:00:00Z" cacheDuration="PT24H">
  <ds:Signature>…</ds:Signature>
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    …
  </md:SPSSODescriptor>
</md:EntityDescriptor>
```

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 404 | `not_found` | 이 환경에 연결이 없거나 엔터프라이즈 연결이 아닙니다. |
| 409 | `conflict` | 연결이 SAML 연결이 아니거나 아직 SAML 구성이 없습니다. |
| 422 | `validation_failed` | `revision_id`의 형식이 잘못되었거나 반복되었거나(`invalid_value`, `repeated`), 이 연결의 초안 리비전이 아닙니다(`not_found`). `errors[]`는 `/revision_id`를 가리킵니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나 잘못되었거나 취소되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |

## 예시

```bash
curl -o sp-metadata.xml "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/sp-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections sp-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --file sp-metadata.xml
```

`--file`을 지정하지 않으면 CLI는 XML을 표준 출력으로 씁니다. 기존 파일은 절대 덮어쓰지 않습니다.