매핑 규칙 수정¶
POST /api/v1/sso_mapping/field/{fdmp_uuid}/modify
개요¶
SSO 속성 매핑 및 공급자 바인딩을 전체적으로 업데이트합니다.
호출 전 및 사용 단계¶
이 그룹은 특정 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/sso_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_가 아닙니다. |