매핑 규칙 생성¶
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를 보존하세요. |