콘텐츠로 이동

매핑 규칙 생성(이전 호환 인터페이스)



POST /api/v1/saml/mapping/field/add

개요

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

호출 전 확인 사항 및 사용 단계

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

이 그룹은 특정 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/saml/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를 보존하십시오.

문서 평가

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