# 연결에 SAML IdP 메타데이터 가져오기

`POST /v1/connections/{connection_id}:import-metadata` · 권한 `connections:write`

업로드한 ID 공급자의 SAML 2.0 메타데이터 문서를 엔터프라이즈 SAML 연결에 적용합니다.

- 연결의 ID 공급자 측 값(엔티티 ID, HTTP-Redirect 单 Sign-On URL, 단일 로그아웃 URL)은 문서의 값으로 대체됩니다.
- 문서에 있는 서명 인증서 중 아직 만료되지 않았고 아직 등록되지 않은 인증서가 추가됩니다(`source`는 `manual`). 연결에 이미 있는 인증서는 활성 상태를 유지합니다. 이러한 인증서를 삭제하려면 [인증서 삭제](../connection-certificates/delete.md)를 참조하십시오.
- 연결은 이제 업로드한 문서를 따릅니다. 저장된 메타데이터 URL과 인증서 고정(pinning)은 제거됩니다.
- 이 변경으로 마지막으로 통과한 [연결 테스트](test.md)가 무효화되며, 연결을 활성화하려면 새로운 테스트를 통과해야 합니다.

**활성** 연결에서는 ID 공급자의 엔티티 ID나 SSO URL을 변경하거나 서명 고정을 제거하는 문서는 적용되지 않습니다. 이 경우 전체 가져오기는 [초안 리비전](revisions.md)이 되며, 응답에는 변경되지 않은 실시간 ID 공급자 측 값이 표시되고, `added_certificate_fingerprints`는 비어 있으며, `revision`이 설정됩니다. `revision_id`와 함께 [연결 테스트](test.md)로 초안을 테스트한 다음 [게시](publish-revision.md)하십시오. 그 밖의 가져오기(새 인증서, SLO URL, MFA 값)는 바로 적용됩니다.

문서는 엄격한 제한(최대 1 MiB, `DOCTYPE` 불가)에 따라 파싱됩니다. 문서가 올바르지 않으면 응답에 그 이유가 표시되지 않으며, 이유와 문서 내용 모두 기록되지 않습니다. 여러 `EntityDescriptor` 요소가 있는 문서에는 `entity_id`가 필요합니다. SAML 자료에는 버전이 없으므로 이 요청은 `If-Match` 헤더를 받지 않습니다. 쓰기 작업은 `connection.idp_metadata_imported`로 감사되며, 새 인증서마다 `connection.idp_certificate_added`도 함께 감사됩니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `connection_id` | path | 예 | 엔터프라이즈 SAML 연결 ID(`conn_…`). |
| `metadata_xml` | string | 예 | 메타데이터 문서(`EntityDescriptor` 또는 `EntitiesDescriptor`), 최대 1 MiB. |
| `entity_id` | string | 여러 엔티티인 경우 | 여러 엔티티가 있는 문서에서 가져올 ID 공급자의 엔티티 ID. 엔티티가 하나이면 일치해야 합니다. |
| `mfa_authn_context_values` | array \| null | 아니요 | ID 공급자가 다중 인증으로 간주하는 SAML `AuthnContextClassRef` 값(최대 10개). 값을 제공하면(빈 목록도 포함) 저장되며, 생략하거나 `null`이면 저장된 값이 유지됩니다. |

## 응답

`200 OK`:

```json
{
  "idp_entity_id": "https://idp.example.com/entity",
  "idp_sso_url": "https://idp.example.com/sso/redirect",
  "idp_slo_url": null,
  "certificates": [
    {"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
  ],
  "added_certificate_fingerprints": ["3b0c…"]
}
```

| 필드 | 설명 |
|---|---|
| `idp_entity_id`, `idp_sso_url`, `idp_slo_url` | 가져오기 후의 ID 공급자 측 값입니다. 문서에 단일 로그아웃 서비스가 없으면 `idp_slo_url`은 `null`입니다. |
| `certificates` | 연결의 활성 서명 인증서입니다([인증서 목록](../connection-certificates/list.md) 참조). |
| `added_certificate_fingerprints` | 이번 가져오기로 추가된 인증서의 SHA-256 지문입니다. 이미 등록된 인증서는 나열되지 않습니다. |
| `revision` | 가져오기가 초안 리비전이 된 경우에만 표시됩니다. 초안입니다([리비전 목록](revisions.md) 참조). |

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 404 | `not_found` | 이 환경에 연결이 없거나 엔터프라이즈 연결이 아닙니다. |
| 409 | `conflict` | 연결이 SAML 연결이 아니거나, SAML 구성이 아직 없거나, 가져오기로 활성 인증서가 3개를 초과하게 됩니다(아무것도 변경되지 않습니다). |
| 422 | `validation_failed` | 문서 또는 필드가 올바르지 않습니다. `errors[]`는 해당 필드를 가리킵니다(`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). 스테이징 및 프로덕션 환경에서는 테스트 ID 공급자도 `/metadata_xml`에서 거부됩니다. 예약된 `.invalid` 도메인 아래의 엔티티 ID이거나 [로컬 모의 서버](/docs/cli/mock-server)의 공개 테스트 키인 경우입니다. |
| 413 | `payload_too_large` | 요청 본문이 4 MiB보다 큽니다. |
| 400 | `unknown_field` | 본문에 알 수 없는 필드가 있습니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나, 잘못되었거나, 취소되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |

## 예제

```bash
jq -Rs '{metadata_xml: .}' idp-metadata.xml > import.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:import-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @import.json
```

```bash
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml
```