콘텐츠로 이동

매핑 규칙 수정 (레거시 호환 인터페이스)



POST /api/v1/saml/mapping/field/{fdmp_uuid}/modify

개요

SSO 속성 매핑과 공급자 바인딩을 전체적으로 업데이트합니다.

호출 전 및 사용 단계

이는 레거시 주소 호환 인터페이스이며, 현재 소스 코드에 여전히 실제 등록되어 있습니다. 과거 "2026-05-31 지원 종료" 주석은 현재 요청이 금지되었음을 의미하지 않습니다. 신규 연동 시에는 매핑 규칙 수정을 우선 사용하십시오. 레거시 경로는 동일한 컨트롤러/요청 필드/응답을 사용하며, saml 접두사 때문에 OIDC를 제외하지 않습니다.

이 그룹은 특정 SSO 공급자의 로그인 attributes를 현재 워크스페이스 역할로 매핑하며, 배포 플랜 LDAP/OIDC의 custom_login_mapping 및 시스템 매핑과 다릅니다. 규칙을 생성한다고 매핑이 자동으로 활성화되지는 않습니다. 해당 SSO 설정에서 isOpenSAMLMapping(이 그룹의 set_disable)을 활성화해야 하며, SSO 설정 자체도 활성화되어 있어야 합니다.

속성 이름 매칭은 소문자로 비교하며, 값은 정규식/포함 매칭이 아닙니다. 문자열 배열은 값을 하나씩 매칭합니다. 배열이 아닌 객체/숫자/null 등은 먼저 json.dumps로 문자열로 변환하며, 배열 요소는 일괄적으로 문자열로 변환하지 않습니다. 따라서 ID 소스에서 안정적인 문자열 속성과 문자열 배열을 사용하는 것이 좋습니다. 여러 역할이 일치하면 합집합을 사용합니다. SSO 매핑을 활성화한 후 규칙이 없거나 일치하는 항목이 없으면 계정이 이 워크스페이스에 액세스하는 것을 금지할 수 있으며, 이후 로그인/전환 시 기존 연결을 삭제합니다. 단순히 기본 역할을 추가하는 것이 아닙니다. 기록 후 워크스페이스 및 멤버 캐시를 비동기로 새로 고치므로 기존 SSO 세션의 후속 액세스에 영향을 줄 수 있으며, 다음 로그인에만 적용된다고 보장할 수 없습니다.

ssoUUID와 세 가지 매핑 필드를 명시적으로 제출해야 합니다. 전체를 덮어쓰며 필드별로 병합하지 않습니다. ssoUUID를 생략하면 현재 None이 비어 있지 않은 열에 기록되어 500이 발생하므로, 선택 사항이라는 선언을 '유지'로 해석해서는 안 됩니다. ssoUUID를 변경해도 새 공급자가 유효하다는 것이 입증되지 않으므로 먼저 이 워크스페이스의 SSO 목록을 조회해야 합니다. 입력 역할은 필터링되므로 저장 후 targetValues/roleInfos와 ssoInfo를 확인하십시오. 제출 후 캐시 새로 고침 작업을 전달하며, 전달에 실패하면 500이 발생할 수 있지만 규칙은 이미 저장되어 있으므로 무작정 반복 생성하지 마십시오. 이 그룹은 SSO 설정 변경 이메일을 보내지 않으며, 공유 SSO create/modify의 needNotify 파라미터를 이 페이지에 적용하지 않습니다.

라우트 파라미터

파라미터 이름 타입 필수 설명
fdmp_uuid string Y 공급자 UUID 또는 배포 플랜 사용자 지정 lgmp_가 아닙니다.
예: fdmp_example
가져오기 또는 입력 방법: 매핑 목록 content.data[].uuid에서 이 워크스페이스의 fdmp_를 가져옵니다.

요청 헤더

파라미터 이름 타입 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터 이름 타입 필수 설명
targetValues[*] string 문자열이며 표시 이름이 아니고 중첩 객체를 제출하지 않습니다. 현재 요소 형식은 일관된 강타입 검증이 적용되지 않습니다.
예: general
가져오기 또는 입력 방법: 이 워크스페이스에서 표시되는 단일 역할 UUID/시스템 식별자입니다.
sourceField string Y 필수이며 비어 있지 않은 값을 권장합니다. 매칭 시 필드 이름은 대소문자를 구분하지 않지만, 동일 이름 검사는 여전히 데이터베이스의 동등성 의미 체계에 따릅니다. 점 경로는 지원하지 않습니다. 생성 시 통일된 길이 상한 선언은 없으며, 수정 시 ≤256, 저장 열 256이므로 모두 ≤256으로 제어하는 것이 좋습니다.
null 허용: False
최대 길이: 256
예: groups
가져오기 또는 입력 방법: ID 공급자 관리자가 제공한 실제 attributes 최상위 필드 이름을 사용합니다.
sourceValue string Y 필수이며 비어 있지 않은 값을 권장합니다. 와일드카드/정규식이 아닙니다. 생성 시 길이가 선언되지 않았고, 수정 시 ≤256, 저장 열 256이므로 모두 ≤256을 권장합니다.
null 허용: False
최대 길이: 256
예: engineering
가져오기 또는 입력 방법: 속성의 실제 문자열 또는 문자열 배열의 단일 요소를 사용하며, 전체 배열 텍스트를 입력하지 마십시오.
ssoUUID string 생성 시 필수로 선언되어 있으며, 수정 시에는 선택 사항으로 선언되어 있지만 구현에서는 생략된 값 None으로 기존 ssoUUID를 덮어쓰므로 정상 제출 시 데이터베이스 500이 발생할 수 있습니다. 현재/새 대상을 명시적으로 다시 입력해야 합니다. 현재 생성/수정 시 SSO 존재 여부/소속 워크스페이스를 강제 검증하지 않으므로 저장 성공이 대상의 유효성을 입증하지 않습니다. 다른 워크스페이스/가짜 UUID를 제출하지 마십시오.
null 허용: False
최대 길이: 48
예: sso_example
가져오기 또는 입력 방법: SSO 설정 목록에서 현재 워크스페이스의 공급자 uuid를 가져오며, SAML 또는 OIDC는 실제 설정에 따라 선택합니다.
targetValues array Y 필수 배열이며 비어 있지 않은 값을 권장합니다. 일부 알 수 없거나 다른 워크스페이스의 역할은 필터링되고 상태 0/2는 유지됩니다. []이거나 표시되는 레코드가 전혀 없으면 NotFoundRole이 발생합니다. 상태 2로 저장해도 현재 사용 가능함을 보장하지 않으며, 목록 roleInfos에는 0만 표시됩니다. 모든 대상이 소프트 삭제되었지만 레코드가 여전히 존재하는 경우 빈 집합으로 필터링될 수 있으며 유효한 매핑으로 간주하지 않습니다.
예: ["general"]
가져오기 또는 입력 방법: 현재 워크스페이스의 역할 목록에서 표시되는 역할 식별자(예: general/readOnly/사용자 지정 role_)를 가져옵니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/saml/mapping/field/fdmp_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"ssoUUID":"sso_example","sourceField":"groups","sourceValue":"engineering","targetValues":["general"]}'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 타입 설명
content boolean 성공 시 true이며, 매핑 엔터티 또는 로그인 결과를 반환하지 않습니다.
{
  "code": 200,
  "content": true,
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError Body 최상위가 객체가 아님 일부 json 파일 형식 오류 완전한 ssoUUID/sourceField/sourceValue/targetValues 객체를 제출합니다.
404 ft.SamlMappingFieldAlreadyExists 이 워크스페이스에 동일한 ssoUUID+sourceField+sourceValue의 삭제되지 않은 매핑이 이미 있음(수정 시 자기 자신 제외) 워크스페이스에 동일한 매핑 필드 이름과 필드 값이 이미 존재함 새 조합을 사용하거나 기존 UUID를 업데이트하며 HTTP가 404임에 유의합니다.
404 ft.NotFoundRole 입력 역할 또는 기존 매핑 대상 집합에 이 워크스페이스에서 표시되는 역할 레코드가 전혀 없음([] 포함). 수정/삭제 감사에서도 발생할 수 있음 지정된 역할을 찾을 수 없거나 역할이 삭제됨 역할 목록에서 현재 입력/기존 대상을 확인하고, 빈 집합을 비우기 성공으로 간주하지 않습니다. 과거의 잘못된 규칙은 관리자가 수정한 후 처리하십시오.
500 ft.InternalServerError 저장된 JSON 형식, 데이터베이스 또는 제출 후 작업 전달 중 처리되지 않은 예외 발생 내부 오류 데이터베이스가 이미 커밋되었는데 캐시 작업 전달이 실패했을 수 있으므로 먼저 목록에서 규칙/SSO 스위치를 다시 읽은 후 처리하고 traceId를 보관합니다.
404 ft.SamlMappingNoExists fdmp_uuid가 이 워크스페이스에 삭제되지 않은 매핑 레코드가 없음 지정된 Saml Mapping을 찾을 수 없음 이 워크스페이스 매핑 목록에서 fdmp_ UUID를 다시 가져옵니다. sso_ 또는 lgmp_가 아닙니다.

문서 평가

이 페이지가 도움이 되었나요?