연결의 속성 매핑 교체

PUT /v1/connections/{connection_id}/attribute-mappings · 권한 connections:write

기업 연결의 속성 매핑 목록 전체를 교체합니다. 규칙의 순서는 중요하지 않으며, 응답은 대상별로 정렬됩니다. If-Match는 필수입니다. 없으면 요청이 428로 실패합니다. 읽은 이후 목록이 변경되었거나 값이 일치하지 않으면 412로 실패하며 아무것도 기록되지 않습니다. 같은 목록을 보내면 아무것도 기록되지 않습니다. 변경 사항은 다음 로그인부터 적용되며, 마지막으로 통과한 연결 테스트를 무효화하지 않습니다. 쓰기는 connection.attribute_mappings_replaced로 감사 기록됩니다(추가, 삭제, 변경된 대상). 로그인에서 얻은 속성 값은 감사 로그에 절대 기록되지 않습니다.

요청

필드 유형 필수 설명
connection_id 경로 예 기업 연결 ID(conn_…).
If-Match 헤더 예 마지막 조회에서 받은 ETag. 없으면 428; 오래되었으면 412.
attribute_mappings 배열 예 새 전체 목록. 최대 28개 규칙.
attribute_mappings[].target 문자열 예 email(모든 목록에 필수), given_name, family_name, name, locale, zoneinfo, phone, groups 또는 user_metadata.<key>(키는 [a-z0-9_]{1,40}; 등록된 OIDC 클레임 이름과 idp_ 접두사는 허용되지 않음; 최대 20개 키). 대상당 규칙 하나. 매핑으로는 app_metadata를 쓸 수 없습니다.
attribute_mappings[].source_name 문자열 예 1~512바이트, 제어 문자나 양방향 문자가 없어야 하며, 앞뒤 공백이 없어야 합니다.
attribute_mappings[].source_name_format 문자열 | null 아니요 SAML NameFormat(절대 URI). 하나의 소스 이름은 하나의 형식으로만 읽을 수 있습니다.
attribute_mappings[].overwrite 문자열 예 always, if_empty 또는 never.
attribute_mappings[].profile 문자열 아니요 사전 설정 이름; 생략하면 generic.

응답

저장된 목록(속성 매핑 조회 참조)과 새 ETag가 포함된 200 OK.

오류

HTTP code 발생 조건
404 not_found 이 환경에 연결이 없거나 기업 연결이 아닙니다.
409 conflict 연결의 프로토콜에는 속성 매핑이 없습니다(LDAP).
412 precondition_failed If-Match가 현재 버전과 일치하지 않거나, 목록이 동시에 변경되었습니다.
422 validation_failed 규칙이 위의 규칙을 위반합니다. 위반된 각 규칙은 /attribute_mappings/<index>/<field>를 가리키는 errors[] 항목 하나가 되며, 목록 수준 규칙(email_required, too_many_metadata_keys)은 /attribute_mappings를 가리킵니다.
428 precondition_required If-Match 헤더가 없습니다.
400 unknown_field 요청 본문에 알 수 없는 필드가 있습니다.
401 unauthenticated 자격 증명이 없거나 잘못되었거나 폐기되었습니다.
403 insufficient_permissions 자격 증명에 필요한 권한이 없습니다.
429 rate_limited 요청 한도를 초과했습니다. Retry-After 기간이 지난 후 다시 시도하십시오.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없습니다. Retry-After 기간이 지난 후 다시 시도하십시오.

예시

curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "6f1c…"' \
  -d '{"attribute_mappings":[{"target":"email","source_name":"email","overwrite":"always"},{"target":"user_metadata.department","source_name":"department","overwrite":"if_empty"}]}'

keenauth connections attribute-mappings put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @mappings.json --if-match '"6f1c…"'