스위치 상태 정보 조회¶
GET /api/v1/login_mapping/switch/get
개요¶
사이트 시스템 로그인 매핑 스위치 및 적용 모드를 조회합니다.
호출 전 및 사용 단계¶
r 또는 w 권한의 External 자격 증명이 필요합니다. 요청 본문이나 Query를 전달하지 않으면 사이트 수준 시스템 매핑 설정을 읽습니다. 설정이 없으면 기본값은 isDisable=true, type=GlobalValid입니다. 여기서 GlobalValid는 모드 기본값이며 기능이 활성화되었음을 의미하지 않습니다. 반환값은 특정 워크스페이스의 사용자 정의 매핑 스위치가 아닙니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417가져오기 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 API에는 r 또는 w 자격 증명을 사용할 수 있으며, 쓰기 API에는 w 자격 증명이 필요합니다. 예: <external-access-key>가져오기 또는 입력 방법: 사이트 관리자가 External API AK를 할당하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9가져오기 또는 입력 방법: 요청할 때마다 uuid.uuid4().hex를 다시 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 구합니다. 예: <hmac-sha256-hex>가져오기 또는 입력 방법: External API 서명 인증에 따라 함께 제공되는 SK로 계산하며, 전체 실행 가능한 템플릿은 아래에서 확인할 수 있습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다. 예: 1785427200가져오기 또는 입력 방법: 전송 시 str(int(time.time()))를 사용하여 현재 Unix 초 문자열을 생성합니다. |
파라미터 추가 설명¶
인증 방식은 External API 서명 인증을 참고하십시오. 이 모듈은 사이트 시스템 로그인 매핑(isSystem=1)을 관리하며, OIDC/LDAP 등 공유 로그인 매핑 경로를 사용하는 타사 로그인에서 사용됩니다. 워크스페이스 사용자 정의 매핑 또는 독립형 SAML 설정 API가 아닙니다. 설정을 저장해도 기존 모든 사용자 권한을 즉시 일괄 재계산하지 않으며, 이후 관련 로그인 시에만 모드에 따라 처리됩니다.
시스템 매핑이 활성화되어 있고 대상 워크스페이스에서 사용자 정의 매핑이 비활성화된 경우: ValidOnFirstLogin은 과거에 직접적인 워크스페이스 연결이 없는 계정에만 시스템 규칙을 적용합니다(과거에는 삭제된 연결도 포함). 이는 이번에 계정이 새로 생성되었는지만 판단하는 것과 동일하지 않습니다. GlobalValid는 관련 로그인마다 규칙에 따라 직접 역할을 교체하며, 일치하지 않는 경우 직접 구성원/역할 관계를 제거할 수 있습니다. Append는 일치하는 시스템 역할만 추가하며, 일치하지 않아도 기존 직접 관계를 정리하지 않습니다. 워크스페이스에서 사용자 정의 매핑을 활성화한 경우 해당 워크스페이스는 사용자 정의 규칙에 따라 교체/불일치 정리를 우선 수행하며, 시스템 Append 또는 최초 로그인 모드의 보존 의미를 적용할 수 없습니다. 시스템 스위치를 꺼도 워크스페이스 사용자 정의 규칙이 동시에 꺼지지는 않습니다. 기존 직접 Owner 역할은 매칭 처리에서 유지되며, 이 모듈을 통해 Owner를 새로 부여하지 않습니다.
요청 예시¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/login_mapping/switch/get'
query = {}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, application/json 공통 래퍼입니다. External은 declaration을 자동으로 주입하지 않으며, 목록 페이지네이션은 content.pageInfo에 있습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.isDisable | boolean 또는 integer | true/1은 비활성화, false/0은 활성화입니다. 빈 쓰기 요청의 기존 값은 정수 0으로 저장될 수 있습니다. |
| content.type | string | 시스템 매핑 모드: ValidOnFirstLogin, GlobalValid, Append. 생략되면 GlobalValid가 보충됩니다. |
{
"code": 200,
"content": {
"isDisable": true,
"type": "GlobalValid"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
확인된 규칙 및 요청 오류는 표에 나열되어 있습니다. 일반 데이터베이스/캐시/감사 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 설정이 이미 커밋된 후에 후속 오류가 발생할 수 있으므로, 먼저 현재 상태를 읽은 후 다시 시도하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 500 | ft.InternalServerError | 데이터베이스, 사이트 설정 캐시, 감사 또는 처리되지 않은 기존 데이터 예외 | 내부 오류 | traceId를 보존하고 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인하십시오. 데이터베이스와 캐시/감사는 동일한 트랜잭션이 아니므로 오류가 완전히 저장되지 않았음을 증명하지는 않습니다. |