사용자 정의 매핑 규칙 목록¶
GET /api/v1/login_mapping/field/list
개요¶
이 워크스페이스의 배포 플랜 사용자 정의 로그인 매핑 규칙을 페이지 단위로 조회합니다.
호출 전 및 사용 단계¶
이 그룹은 현재 워크스페이스에서 isSystem=false인 배포 플랜 사용자 정의 로그인 속성 매핑을 관리하며, ssoUUID로 ID 공급자를 바인딩하는 SAML 매핑 및 External/Inner 시스템 매핑과 다릅니다. 실제로 적용되려면 워크스페이스에서 isOpenCustomMappingRule을 활성화해야 합니다. 사용자 정의 매핑에서 스위치를 구성하고 로그인 정책을 확인할 수 있습니다. 저장/삭제는 규칙만 변경하며, 기존 구성원의 역할을 즉시 변경하지 않고 기존 세션을 취소하지 않습니다. 이후 LDAP/OIDC 공유 로그인 흐름은 실제 userinfo를 기준으로 다시 매칭합니다.
매칭은 userinfo 최상위 속성을 사용합니다. 배열은 각 요소를 str(value)로 비교하고, 그 외 값은 Python 문자열 형식으로 비교합니다. 필드와 값에는 데이터베이스의 동등 비교 의미를 사용하며(대소문자/정렬 규칙은 배포 데이터베이스에서 결정), 정규식/포함 또는 중첩 경로 추출은 수행하지 않습니다. ID 소스의 안정적인 문자열만 사용하는 것이 좋습니다. 여러 매칭 규칙의 역할은 합집합으로 계산한 뒤 사용 가능한 역할을 필터링합니다. 워크스페이스 사용자 정의 스위치가 활성화되면 시스템 규칙보다 우선합니다. 매칭이 있으면 일반적으로 역할을 재설정하고, 매칭이 없으면 기존 연결이 지워질 수 있습니다. 기존 Owner 역할에는 보호 로직이 있습니다. 먼저 전용 테스트 ID로 실제 권한을 검증해야 하며, 이번 HTTP 성공만으로 다음 로그인 시 역할이 올바르다고 판단해서는 안 됩니다.
현재 워크스페이스의 삭제되지 않은 사용자 정의 규칙만 조회하며, 기본적으로 최근 업데이트(업데이트되지 않은 경우 생성 시간) 내림차순으로 정렬합니다. 검색은 소스 필드, 소스 값 또는 역할 표시 이름을 동시에 매칭하며, 역할 이름 검색에는 표시되는 삭제되지 않은 역할을 사용합니다. roleInfos에는 status=0인 역할만 채워지므로, 검색에 일치하더라도 roleInfos에 모든 이전 역할이 포함된다고 보장할 수 없습니다. ssoUUID로 필터링하지 않으며, 이 그룹은 특정 ID 공급자에 바인딩되지 않습니다.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 선택 사항이며 기본값은 1이고 >=1입니다. null 허용: False $minValue: 1 예시: 1가져오기 또는 입력 방법: 첫 페이지는 1이며, 이후 pageInfo에 따라 페이지를 넘깁니다. |
|
| pageSize | integer | 선택 사항이며 기본값은 10이고 단위는 건입니다. null 허용: False $maxValue: 100 $minValue: 1 예시: 10가져오기 또는 입력 방법: 필요한 페이지 크기에 따라 1..100을 선택합니다. |
|
| search | string | 선택 사항이며, trim 후 키워드가 없으면 필터링하지 않습니다. OR 매칭이며 SQL 와일드카드 문자가 LIKE 의미에 영향을 줄 수 있습니다. null 허용: False 예시: engineering가져오기 또는 입력 방법: 소스 속성명, 소스 값 또는 대상 역할 표시 이름의 키워드를 사용합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/login_mapping/field/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=10
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.data | array<object> | 현재 페이지의 규칙 배열입니다. |
| content.data[].id | integer | 레코드 번호입니다. |
| content.data[].uuid | string | lgmp_ 매핑 UUID입니다. 수정/삭제 시 이 필드를 사용하며 fdmp_가 아닙니다. |
| content.data[].workspaceUUID | string | 소속 워크스페이스입니다. |
| content.data[].isSystem | integer 또는 boolean | 이 그룹은 0/false로 고정되어 시스템 매핑과 구분됩니다. |
| content.data[].sourceField | string | 로그인 속성의 최상위 필드 이름입니다. |
| content.data[].sourceValue | string | 기대하는 속성 문자열 값입니다. |
| content.data[].targetValues | array<string> | 저장된 역할 집합입니다. 상태 2이거나 이후에 무효화된 이력 값을 포함할 수 있으며, 현재 적용 중인 역할과 동일하지 않습니다. |
| content.data[].targetValues[] | string | 단일 저장 역할 식별자입니다. |
| content.data[].roleInfos | array<object> | 현재 이 워크스페이스에서 표시되고 status=0인 역할 요약이며, 무효 항목은 생략됩니다. |
| content.data[].roleInfos[].uuid | string | 유효한 역할 식별자입니다. |
| content.data[].roleInfos[].name | string | 역할 표시 이름입니다. |
| content.data[].status | integer | 매핑 레코드 상태입니다. 목록에서는 3만 제외하며, 다른 이력 상태를 포함할 수 있습니다. 단일 항목 작업에서는 0만 허용합니다. |
| content.data[].creator | string | 생성자입니다. |
| content.data[].updator | string | 수정자입니다. |
| content.data[].createAt | integer | 생성 Unix 초입니다. |
| content.data[].updateAt | integer | 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1일 수 있습니다. |
| content.data[].deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.declaration | object | 외부 공통 선언이며 data의 각 항목에 재귀적으로 첨부되지 않습니다. |
| pageInfo.pageIndex | integer | 현재 페이지입니다. |
| pageInfo.pageSize | integer | 페이지 크기입니다. |
| pageInfo.count | integer | 현재 페이지의 건수입니다. |
| pageInfo.totalCount | integer | 검색 후 일치하는 총 개수입니다. |
{
"code": 200,
"content": {
"data": [
{
"id": 1,
"uuid": "lgmp_example",
"workspaceUUID": "wksp_example",
"isSystem": false,
"sourceField": "department",
"sourceValue": "engineering",
"targetValues": [
"general"
],
"roleInfos": [
{
"uuid": "general",
"name": "标准成员"
}
],
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"deleteAt": -1
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 타입 및 값을 확인하세요. |
| 500 | ft.InternalServerError | 매핑/역할/데이터베이스 저장 또는 데이터 형식 지정 중 처리되지 않은 예외 발생 | 내부 오류 | 필터로 특정 규칙까지 범위를 좁혀 확인하고, 이전 targetValues 형태를 점검하세요. 계속 실패하면 traceId를 보관하세요. |