SSO 설정 조회(레거시 호환 인터페이스)¶
GET /api/v1/sso/saml_list
개요¶
현재 워크스페이스의 SSO 공급자 및 연결된 멤버 수를 읽습니다.
호출 전 및 사용 단계¶
이는 레거시 주소 호환 인터페이스이며 현재 소스 코드에서도 실제로 등록되어 있습니다. 과거 “2026-05-31 종료” 주석은 현재 요청이 금지되었음을 의미하지 않습니다. 신규 연동에서는 SSO 설정 조회를 우선 사용하십시오. 레거시 경로는 동일한 컨트롤러/요청 필드/응답을 따르며, saml 접두사 때문에 OIDC가 제외되지는 않습니다.
이 워크스페이스의 삭제되지 않은 공급자 배열을 updateAt 내림차순으로 반환하며 페이지네이션하지 않습니다. saml/oidc로 필터링할 수 있습니다. 이 공개 라우트는 항상 멤버 수 집계를 활성화하며 showMemberCount를 전달해 재정의할 수 없습니다. memberCount는 현재 워크스페이스의 활성 관계에 있는 삭제되지 않은 계정 네임스페이스를 기준으로 집계되며, 최근 로그인 수, 온라인 인원 수 또는 현재 매핑에서 허용된 전체 인원 수를 의미하지 않습니다.
목록은 의도적으로 uploadData/config를 반환하지 않으며, 목록에서 clientSecret이나 전체 XML을 읽지 않습니다. 상세 조회를 사용하십시오. updatorInfo는 현재 사용 가능한 ID 요약으로, 계정, API Key 또는 시스템/AI ID일 수 있으며 누락 시 {}입니다. 여기서 email을 일괄적으로 이메일 주소로 간주할 수 없습니다. 설정의 status와 isOpenSAMLMapping은 별개의 스위치이며, 비활성화된 설정도 목록/get에서 읽을 수 있습니다. 읽을 수 있다고 해서 해당 설정으로 로그인할 수 있다는 의미는 아닙니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| type | string | 선택 사항이며, 생략하면 삭제되지 않은 모든 유형을 가져옵니다. 빈 문자열은 유효한 필터 열거형 값이 아니므로 생략하는 것을 권장합니다. null 허용: False 선택 가능 값: ['saml', 'oidc'] 예: oidc획득 또는 입력 방법: 공급자의 실제 프로토콜에 따라 saml/oidc를 선택합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/sso/saml_list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode type=oidc
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | array<object> | 공급자 배열이며 비어 있으면 []입니다. |
| content[].id | integer 또는 null | 현재 레코드 번호이며, 신규 생성 제출 전 구성 결과에서는 null일 수 있습니다. |
| content[].uuid | string | sso_ 설정 UUID입니다. |
| content[].type | string | saml/oidc입니다. |
| content[].workspaceUUID | string | 소속 워크스페이스입니다. |
| content[].idpName | string | 공급자 표시 이름입니다. |
| content[].remark | string 또는 null | 비고이며, 기존/신규 생성 이력에서는 null일 수 있습니다. |
| content[].role | string | 기본 역할 식별자입니다. |
| content[].idpMd5 | string | 공급자 ID/계정 네임스페이스 요약이며, 클라이언트 키나 쓰기 가능한 ID가 아닙니다. |
| content[].tokenHoldTime | integer | 유휴 세션 유지 시간(초)입니다. |
| content[].tokenMaxValidDuration | integer | 로그인 세션 최대 시간(초)입니다. |
| content[].isOpenSAMLMapping | integer 또는 boolean | 역할 매핑 스위치 1/0이며 SSO 설정 status와 동일하지 않습니다. |
| content[].status | integer | 0 활성화, 2 비활성화이며, 삭제되지 않은 읽기에는 다른 이력 상태가 포함될 수 있습니다. |
| content[].creator | string | 생성 ID입니다. |
| content[].updator | string | 업데이트 ID입니다. |
| content[].createAt | integer | 생성 Unix 초입니다. |
| content[].updateAt | integer | 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1일 수 있습니다. |
| content[].deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content[].memberCount | integer | 현재 워크스페이스의 연결된 계정 네임스페이스 수입니다. |
| content[].updatorInfo | object | 업데이트 ID 요약이며 계정/Key/시스템/AI일 수 있습니다. 누락 시 {}이며, 필드는 ID에 따라 달라집니다. |
| content[].updatorInfo.uuid | string | 조건부 반환, 업데이트 ID UUID이며 시스템 ID는 빈 문자열일 수 있습니다. |
| content[].updatorInfo.name | string | 조건부 반환, 표시 이름입니다. |
| content[].updatorInfo.email | string | 조건부 반환, 사람 ID는 이메일일 수 있으며, API Key ID는 Key UUID, 시스템/AI ID는 표시 레이블이므로 유효한 이메일 주소로 사용할 수 없습니다. |
| content[].updatorInfo.username | string | 조건부 반환, 로그인 이름입니다. |
| content[].updatorInfo.status | integer | 조건부 반환, ID 상태이며 계정/API Key/시스템 ID별로 각각 해석되며 공급자 status와 동일하지 않습니다. |
| content[].updatorInfo.wsAccountStatus | integer | 조건부 반환, 해당 ID의 워크스페이스 관계/호환 상태이며 ID 유형에 따라 해석되며 일반 멤버 관계임을 보장하지 않습니다. |
| content[].updatorInfo.iconUrl | string | 조건부 반환, 아바타입니다. |
| content[].updatorInfo.mobile | string | 조건부 반환, 휴대폰 번호입니다. |
| content[].updatorInfo.countryCode | string | 조건부 반환, 휴대폰 번호 국가 코드입니다. |
| content[].updatorInfo.acntWsNickname | string | 조건부 반환, 워크스페이스 닉네임입니다. |
| content[].declaration | object | 비어 있지 않은 각 객체의 공통 선언입니다. |
{
"code": 200,
"content": [
{
"id": 1,
"uuid": "sso_example",
"type": "oidc",
"workspaceUUID": "wksp_example",
"idpName": "ExampleIdP",
"remark": "企业登录",
"role": "general",
"idpMd5": "IDP-IDENTITY-HASH",
"tokenHoldTime": 604800,
"tokenMaxValidDuration": 2592000,
"isOpenSAMLMapping": 0,
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"deleteAt": -1,
"memberCount": 2,
"updatorInfo": {},
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하세요. |
| 500 | ft.InternalServerError | 설정/데이터베이스/키 복호화, XML 도구 또는 관련 자료 포맷팅 중 처리되지 않은 예외가 발생했습니다 | 내부 오류 | traceId를 보관하고 현재 설정과 서비스 종속성을 확인하세요. 조회는 설정 업데이트를 수행하지 않으므로, 조회 실패를 공급자가 존재하지 않는 것으로 간주하지 마세요. |