연결에 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). 연결에 이미 있는 인증서는 활성 상태를 유지합니다. 이러한 인증서를 삭제하려면 인증서 삭제를 참조하십시오. - 연결은 이제 업로드한 문서를 따릅니다. 저장된 메타데이터 URL과 인증서 고정(pinning)은 제거됩니다.
- 이 변경으로 마지막으로 통과한 연결 테스트가 무효화되며, 연결을 활성화하려면 새로운 테스트를 통과해야 합니다.
활성 연결에서는 ID 공급자의 엔티티 ID나 SSO URL을 변경하거나 서명 고정을 제거하는 문서는 적용되지 않습니다. 이 경우 전체 가져오기는 초안 리비전이 되며, 응답에는 변경되지 않은 실시간 ID 공급자 측 값이 표시되고, added_certificate_fingerprints는 비어 있으며, revision이 설정됩니다. revision_id와 함께 연결 테스트로 초안을 테스트한 다음 게시하십시오. 그 밖의 가져오기(새 인증서, 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:
{
"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 |
연결의 활성 서명 인증서입니다(인증서 목록 참조). |
added_certificate_fingerprints |
이번 가져오기로 추가된 인증서의 SHA-256 지문입니다. 이미 등록된 인증서는 나열되지 않습니다. |
revision |
가져오기가 초안 리비전이 된 경우에만 표시됩니다. 초안입니다(리비전 목록 참조). |
오류
| 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이거나 로컬 모의 서버의 공개 테스트 키인 경우입니다. |
| 413 | payload_too_large |
요청 본문이 4 MiB보다 큽니다. |
| 400 | unknown_field |
본문에 알 수 없는 필드가 있습니다. |
| 401 | unauthenticated |
자격 증명이 없거나, 잘못되었거나, 취소되었습니다. |
| 403 | insufficient_permissions |
자격 증명에 필요한 권한이 없습니다. |
| 429 | rate_limited |
요청 한도를 초과했습니다. Retry-After 기간 이후에 다시 시도하십시오. |
| 503 | service_unavailable |
종속 서비스를 일시적으로 사용할 수 없습니다. Retry-After 기간 이후에 다시 시도하십시오. |
예제
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
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml