콘텐츠로 이동

매핑 규칙 생성



POST /api/v1/sso_mapping/field/add

개요

지정된 SSO 공급자에 대해 속성-역할 매핑을 생성합니다.

호출 전 및 사용 단계

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

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

동일 공급자 내 필드/값 조합은 고유합니다. 생성 시 공급자의 매핑 스위치가 자동으로 켜지지 않습니다. 먼저 규칙을 구성하고 검증한 후 활성화하세요. 성공 시 true만 반환되며, 이후 목록에서 새 UUID를 가져옵니다. 입력한 역할은 필터링되며, 저장 후 targetValues/roleInfos와 ssoInfo를 확인해야 합니다. 제출 후 캐시 새로 고침 작업이 전달되며, 전달에 실패하면 500이 발생할 수 있지만 규칙은 이미 저장된 상태입니다. 무작정 반복 생성하지 마세요. 이 그룹은 SSO 설정 변경 메일을 보내지 않으며, 공유 SSO create/modify의 needNotify 매개변수를 이 페이지에 적용하지 않습니다.

요청 헤더

매개변수 이름 유형 필수 설명
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
예: groups
가져오기 또는 입력 방법: 아이덴티티 공급자 관리자가 제공한 실제 attributes 최상위 필드 이름.
sourceValue string Y 필수이며 비어 있지 않은 값을 권장합니다. 와일드카드/정규식이 아닙니다. 생성 시 길이가 선언되지 않았고, 수정 시 ≤256, 저장 컬럼 256이므로 모두 ≤256을 권장합니다.
null 허용: False
예: engineering
가져오기 또는 입력 방법: 속성의 실제 문자열 또는 문자열 배열의 단일 요소를 사용하며, 전체 배열 텍스트를 입력하지 마세요.
ssoUUID string Y 생성 시 필수로 선언됩니다. 수정 시 선택 사항으로 선언되지만, 구현에서는 생략된 값 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/add' \
  -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를 보존하세요.

문서 평가

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