매핑 구성 수정¶
POST /api/v1/login_mapping/field/{lgmp_uuid}/modify
개요¶
이 워크스페이스의 사용자 지정 로그인 매핑 규칙 하나를 전체 업데이트합니다.
호출 전 및 사용 단계¶
이 그룹은 현재 워크스페이스의 isSystem=false인 배포 플랜 사용자 지정 로그인 속성 매핑을 유지 관리하며, ssoUUID로 ID 공급자에 바인딩된 SAML 매핑 및 External/Inner 시스템 매핑과 다릅니다. 실제 적용을 위해서는 워크스페이스에서 isOpenCustomMappingRule을 활성화해야 하며, 사용자 지정 매핑에서 스위치를 구성하고 로그인 정책을 확인할 수 있습니다. 저장/삭제는 규칙만 변경하며, 기존 멤버의 역할을 즉시 변경하지 않고 기존 세션을 취소하지 않습니다. 이후 LDAP/OIDC 공유 로그인 흐름은 실제 userinfo를 기준으로 다시 매칭합니다.
매칭은 userinfo의 최상위 속성을 사용합니다. 배열은 각 요소를 str(value)로 비교하고, 그 외 값은 Python 문자열 형식으로 비교합니다. 필드와 값은 데이터베이스의 등가 의미 체계를 사용하며(대소문자/정렬 규칙은 배포 데이터베이스에 따라 결정됨), 정규식/포함 또는 중첩 경로 추출은 수행하지 않습니다. ID 소스의 안정적인 문자열만 사용하는 것이 좋습니다. 여러 매칭 규칙의 역할은 합집합으로 계산한 뒤 사용 가능한 역할을 필터링합니다. 워크스페이스 사용자 지정 스위치가 켜져 있으면 시스템 규칙보다 우선합니다. 매칭이 있으면 일반적으로 역할을 재설정하고, 매칭이 없으면 기존 연결이 비워질 수 있습니다. 기존 Owner 역할에는 보호 로직이 있습니다. 먼저 전용 테스트 ID로 실제 권한을 검증해야 하며, 이번 HTTP 성공만으로 다음 로그인 시 역할이 올바르다고 판단해서는 안 됩니다.
세 가지 비즈니스 필드는 모두 완전하게 제출해야 합니다. targetValues는 기존 역할 집합을 전체 교체하며 추가/병합하지 않습니다. UUID는 변경되지 않으며, 이 사용자 지정 규칙을 system으로 변환하거나 다른 워크스페이스로 이동하는 것은 지원되지 않습니다. 일부 유효하지 않은 역할이 필터링된 후에는 성공할 수 있으므로 targetValues와 roleInfos를 다시 읽어 확인해야 합니다. []는 비우기 명령이 아니며, 역할 레코드가 없으면 404가 발생합니다. 모든 매칭 레코드가 소프트 삭제된 역할인 경우 빈 집합이 저장될 수 있으므로, 이를 사용 가능한 구성으로 간주해서는 안 됩니다.
라우팅 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| lgmp_uuid | string | Y | 역할, SSO 공급자 또는 SAML fdmp_ 매핑 UUID가 아닙니다. 예: lgmp_example가져오기 또는 입력 방법: 규칙 목록의 content.data[].uuid에서 현재 워크스페이스의 lgmp_ 레코드를 가져옵니다. |
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| targetValues[*] | string | 단일 문자열이며 역할 표시 이름이 아닙니다. 배열 요소에는 통일된 강한 타입 제약이 없으며, 잘못된 형식은 500을 발생시킬 수 있으므로 객체나 중첩 배열을 제출하지 마십시오. 예: general가져오기 또는 입력 방법: 해당 워크스페이스에서 볼 수 있는 역할 UUID 또는 시스템 역할 식별자 하나를 사용합니다. |
|
| sourceField | string | Y | 필수 문자열이며, 비어 있지 않고 대소문자가 실제 속성과 일치하도록 권장합니다. 점 경로 탐색/와일드카드는 지원되지 않습니다. API 선언은 256자 이하이지만 현재 저장 열은 128자이므로 데이터베이스 오류를 피하려면 128자 이하로 제한하는 것이 좋습니다. 자동 trim은 수행되지 않습니다. null 허용: False 최대 길이: 256 예: department가져오기 또는 입력 방법: 배포된 LDAP/OIDC ID 소스 관리자에게 실제 userinfo 최상위 속성 이름을 확인하고, 성공적으로 로그인한 후 계정 attributes와 대조할 수 있습니다. |
| sourceValue | string | Y | 필수 문자열(256자 이하)이며, 원래 값을 정확히 입력하는 것이 좋습니다. JSON 배열 텍스트나 정규식이 아닙니다. 빈 문자열은 현재 일괄적으로 거부되지 않으며, 매칭 여부는 실제 userinfo에 따라 달라집니다. null 허용: False 최대 길이: 256 예: engineering가져오기 또는 입력 방법: 해당 속성으로 로그인할 때의 실제 값을 사용하며, 배열 속성은 요소 중 하나의 문자열 값을 사용합니다. |
| targetValues | array | Y | 필수 배열이며 비어 있지 않도록 권장합니다. 알 수 없거나 다른 워크스페이스의 역할은 필터링됩니다. 상태 0/2는 유지되며, 모두 존재하지 않거나 []이면 NotFoundRole이 발생합니다. 상태 2/삭제된 역할은 이후 로그인에서 유효한 권한을 얻지 못하므로, 저장 결과가 true라고 해서 모든 역할이 적용된다고 간주해서는 안 됩니다. 현재 워크스페이스의 사용자 지정 진입점에는 External 시스템 매핑의 Owner 금지가 적용되지 않으므로, 클라이언트는 실제 권한 부여 용도에 따라 대상 역할을 선택해야 합니다. 예: ["general"]가져오기 또는 입력 방법: 대상 워크스페이스의 역할 목록에서 현재 사용 가능한 역할 UUID/시스템 역할 식별자를 선택합니다. 예: general/readOnly 및 사용자 지정 role_. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/login_mapping/field/lgmp_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"sourceField":"department","sourceValue":"engineering","targetValues":["general"]}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여 줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 성공 시 true이며, 새 엔터티/UUID 또는 역할 목록이 없습니다. list를 다시 호출해 확인하십시오. |
{
"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 객체가 아님 | 일부 json 파일 형식 오류 | sourceField/sourceValue/targetValues 전체 객체를 제출하십시오. |
| 404 | ft.SamlMappingFieldAlreadyExists | 현재 워크스페이스의 사용자 지정 규칙에 동일한 sourceField+sourceValue 조합이 이미 있음(수정 시 자기 자신 제외) | 워크스페이스에 동일한 매핑 필드 이름과 필드 값이 이미 있습니다. | 조합을 변경하거나 기존 UUID를 수정하십시오. 과거 오류 코드는 404이며 Saml 접두사를 포함하고, 이 사용자 지정 그룹에 여전히 사용됩니다. |
| 404 | ft.NotFoundRole | 대상/기존 매핑 역할 집합에 일치하는 가시 역할 레코드가 없음([] 포함). 단건 삭제 또는 일괄 삭제 감사에서 이전 역할을 파싱할 때도 트리거될 수 있음 | 지정한 역할을 찾을 수 없거나 역할이 이미 삭제되었습니다. | 먼저 이 워크스페이스의 역할 목록과 매핑 목록에서 확인하십시오. 알 수 없는 역할이 일부 섞여 있으면 필터링됩니다. 과거의 빈/일치 항목 없음 집합을 바로 삭제 가능하다고 가정해서는 안 되며, 관리자가 복구한 후 처리해야 합니다. |
| 500 | ft.InternalServerError | 매핑/역할/데이터베이스 저장 또는 데이터 형식 지정 중 처리되지 않은 예외가 발생했습니다. | 내부 오류 | 먼저 목록에서 규칙이 저장되었는지와 최종 targetValues를 확인한 다음, 특정 필드에 대해 처리하고 traceId를 보관하십시오. |
| 404 | ft.LoginMappingNoExists | 단일 UUID가 이 워크스페이스의 isSystem=false이고 status=0인 매핑에 속하지 않음 | 지정한 Login Mapping을 찾을 수 없습니다. | 이 워크스페이스 목록에서 lgmp_ UUID를 다시 가져오십시오. 시스템 규칙 또는 비활성 레코드는 이 단일 항목 진입점으로 작업할 수 없습니다. |