연결에 IdP 서명 인증서 추가

POST /v1/connections/{connection_id}/certificates · 권한 connections:write

엔터프라이즈 SAML 연결에 IdP의 서명 인증서를 추가합니다. 인증서를 직접 업로드하거나 인증서를 교체(로테이션)할 때 사용합니다. 먼저 새 인증서를 추가하고, IdP를 새 인증서로 전환한 다음, 이전 인증서를 삭제하세요. 교체는 활성 연결에서도 즉시 적용됩니다.

인증서는 하나의 PEM CERTIFICATE 블록(최대 8 KiB)이어야 합니다. 만료되지 않아야 하며, 2048비트 이상의 RSA 키 또는 ECDSA P-256, P-384, P-521 키를 가져야 합니다. 거부되면 응답은 이유를 알려 주지 않으며, 이유와 인증서 내용은 기록되지 않습니다. 연결당 활성 인증서는 최대 3개입니다. 연결에서 삭제된 인증서는 다시 추가할 수 없습니다. 이 요청은 If-Match 헤더를 받지 않습니다. 쓰기 작업은 connection.idp_certificate_added로 감사됩니다.

요청

필드 유형 필수 설명
connection_id 경로 예 엔터프라이즈 SAML 연결 ID(conn_…).
certificate 문자열 예 PEM 인증서 하나(-----BEGIN CERTIFICATE----- …), 최대 8 KiB.

응답

새 인증서와 함께 201 Created를 반환합니다(인증서 목록 참고). 같은 인증서가 이미 연결에 있으면 등록된 인증서와 함께 200 OK를 반환하며, 아무것도 기록되거나 감사되지 않습니다.

{"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}

오류

HTTP code 발생 조건
404 not_found 이 환경에 연결이 없거나 엔터프라이즈 SAML 연결이 아닙니다.
409 conflict 연결이 SAML 연결이 아니거나, SAML 설정이 아직 없거나, 활성 인증서가 이미 3개이거나, 이 인증서가 전에 연결에서 삭제되었습니다.
422 validation_failed 인증서가 없거나, 너무 크거나, 허용되지 않습니다. errors[]가 /certificate를 가리킵니다. 스테이징 및 운영 환경은 로컬 모의 서버의 공개 테스트 키에 해당하는 인증서도 거부합니다.
400 unknown_field 본문에 알 수 없는 필드가 있습니다.
401 unauthenticated 자격 증명이 없거나, 잘못되었거나, 취소되었습니다.
403 insufficient_permissions 자격 증명에 필요한 권한이 없습니다.
429 rate_limited 요청 한도를 초과했습니다. Retry-After 기간이 지난 후 다시 시도하세요.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없습니다. Retry-After 기간이 지난 후 다시 시도하세요.

예시

jq -Rs '{certificate: .}' idp-signing.pem > cert.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/certificates" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @cert.json

keenauth connections certificates add conn_01j9xp6q0r1s5t7v9w1x3y5z7b --certificate-file idp-signing.pem