매핑 규칙 목록 조회¶
GET /api/v1/sso_mapping/field/list
개요¶
제공자 및 키워드 기준으로 SSO 역할 매핑 규칙을 페이지 단위로 조회합니다.
호출 전 및 사용 단계¶
이 그룹은 특정 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/sso_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를 보관하십시오. |