매핑 규칙 목록 조회(레거시 호환 API)¶
GET /api/v1/saml/mapping/field/list
개요¶
공급자 및 키워드 기준으로 SSO 역할 매핑 규칙을 페이지 단위로 조회합니다.
호출 전 및 사용 단계¶
이 API는 이전 주소 호환 API이며 현재 소스 코드에도 실제로 등록되어 있습니다. 과거 “2026-05-31 종료” 주석은 현재 요청이 금지되었음을 의미하지 않습니다. 신규 연동에서는 매핑 규칙 목록 조회를 우선 사용하십시오. 이전 경로는 동일한 컨트롤러/요청 필드/응답을 따르며, saml 접두사 때문에 OIDC가 제외되지는 않습니다.
본 그룹은 특정 SSO 공급자의 로그인 attributes를 현재 워크스페이스 역할에 매핑하며, 배포 플랜 LDAP/OIDC의 custom_login_mapping 및 시스템 매핑과는 다릅니다. 규칙을 생성해도 매핑이 자동으로 활성화되지는 않습니다. 해당 SSO 설정에서 isOpenSAMLMapping(본 그룹의 set_disable)을 활성화해야 하며, SSO 설정 자체도 활성화되어 있어야 합니다.
속성 이름 매칭은 소문자로 비교하며, 값은 정규식/포함 매칭이 아닙니다. 문자열 배열은 각 값을 개별적으로 매칭합니다. 배열이 아닌 객체/숫자/null 등은 먼저 json.dumps로 문자열로 변환하지만, 배열 요소는 일괄적으로 문자열로 변환하지 않으므로 ID 소스에서 안정적인 문자열 속성과 문자열 배열을 우선 사용하십시오. 여러 역할이 매칭되면 합집합을 사용합니다. SSO에서 매핑을 활성화한 뒤 규칙이 없거나 매칭되는 항목이 없으면 해당 계정이 이 워크스페이스에 진입하는 것을 차단할 수 있으며, 이후 로그인/전환 시 기존 연결을 삭제합니다. 단순히 기본 역할을 추가하는 것이 아닙니다. 저장 후 워크스페이스 및 멤버 캐시를 비동기적으로 새로 고치므로 기존 SSO 세션의 이후 액세스에 영향을 줄 수 있으며, 다음 로그인에서만 적용된다고 보장할 수 없습니다.
현재 워크스페이스의 삭제되지 않은 규칙만 대상으로 하며, 기본적으로 updateAt 내림차순으로 정렬되고 서로 다른 공급자의 규칙이 함께 나열될 수 있습니다. search는 소스 필드, 소스 값, 역할 이름 간 OR 조건이며 ssoUUID 필터와는 AND 조건입니다. ssoInfo={}는 현재 워크스페이스에서 삭제되지 않은 공급자를 찾지 못했음을 의미하지만, 이 API가 해당 매핑을 자동으로 삭제/복구하지는 않습니다. 반환되는 것은 설정이며, 특정 계정에서 현재 실제로 적용되는 역할이 아닙니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 후 부분 일치하고, SQL 와일드카드 문자가 LIKE에 영향을 줄 수 있습니다. null 허용: False 예: engineering가져오기 또는 입력 방법: 속성 이름/값 또는 역할 표시 이름의 키워드를 사용합니다. |
|
| ssoUUID | string | 선택 사항이며 ≤48자입니다. trim 후 빈 값이면 필터링하지 않고, 비어 있지 않으면 정확히 필터링합니다. 공급자의 존재 여부는 검증하지 않습니다. null 허용: False 최대 길이: 48 예: sso_example가져오기 또는 입력 방법: 현재 워크스페이스의 SSO 목록에서 공급자 UUID를 가져옵니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/saml/mapping/field/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode ssoUUID=sso_example \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=10
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여 줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> | 현재 페이지의 매핑 배열입니다. |
| content.data[].id | integer | 데이터베이스 레코드 번호입니다. |
| content.data[].uuid | string | fdmp_매핑 UUID이며 수정/삭제에 사용합니다. |
| content.data[].workspaceUUID | string | 현재 워크스페이스입니다. |
| content.data[].ssoUUID | string | 저장된 공급자 UUID입니다. 여전히 존재하거나 현재 워크스페이스에 속해 있음을 보장하지 않습니다. |
| content.data[].sourceField | string | 속성 필드 이름입니다. |
| content.data[].sourceValue | string | 매칭 필드 값입니다. |
| content.data[].targetValues | array<string> | 저장된 역할 식별자 배열이며, 더 이상 유효하지 않은 이전 값이 포함될 수 있습니다. |
| content.data[].targetValues[] | string | 개별 역할 식별자입니다. |
| content.data[].roleInfos | array<object> | 현재 워크스페이스에서 조회 가능하고 status=0인 역할 요약이며, 유효하지 않은 역할은 생략됩니다. |
| content.data[].roleInfos[].uuid | string | 역할 UUID입니다. |
| content.data[].roleInfos[].name | string | 역할 이름입니다. |
| content.data[].ssoInfo | object | 현재 워크스페이스의 삭제되지 않은 공급자 요약이며, 유효한 매칭이 없으면 {}입니다. |
| content.data[].ssoInfo.uuid | string | 공급자 UUID이며 생략될 수 있습니다. |
| content.data[].ssoInfo.idpName | string | 공급자 이름이며 생략될 수 있습니다. |
| content.data[].status | integer | 삭제되지 않은 레코드 상태이며 일반적으로 0이고, 이전 데이터에서는 2일 수 있습니다. |
| 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": "fdmp_example",
"workspaceUUID": "wksp_example",
"ssoUUID": "sso_example",
"sourceField": "groups",
"sourceValue": "engineering",
"targetValues": [
"general"
],
"roleInfos": [
{
"uuid": "general",
"name": "标准成员"
}
],
"ssoInfo": {
"uuid": "sso_example",
"idpName": "ExampleIdP"
},
"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 | 조회된 이전 JSON 구조, 데이터베이스 또는 역할/공급자 정보 포맷팅에 예외가 발생했습니다. | 내부 오류 | 특정 공급자/규칙으로 범위를 좁혀 이전 targetValues 형태를 확인하고, 계속 실패하면 traceId를 보관하십시오. |