스위치 상태 설정¶
POST /api/v1/login_mapping/set_disable
개요¶
사이트 시스템 로그인 매핑의 전체 스위치 및 적용 모드를 설정합니다.
호출 전 및 사용 단계¶
이 작업은 스위치와 모드를 전체 기록하는 것이며 부분 업데이트가 아닙니다. isDisable과 type을 항상 명시적으로 제공하는 것이 좋습니다. isDisable을 생략하면 기본값 0으로 활성화되고, type을 생략하면 GlobalValid로 재설정됩니다. {}를 전송해도 GlobalValid가 활성화되므로 조회하거나 기존 구성을 유지하는 용도로 사용할 수 없습니다. 먼저 매핑 스위치 및 모드에서 기존 값을 저장한 후, 모드가 기존 사용자의 다음 로그인에 미치는 영향을 평가하십시오. isDisable=true는 시스템 규칙만 비활성화하며, 동시에 워크스페이스 사용자 정의 매핑을 비활성화하지 않고, 기존 역할/Token을 즉시 철회하지도 않습니다. 저장 후 스위치를 다시 읽고, 통제된 테스트 ID로 후속 로그인을 검증하십시오.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 초 문자열을 생성합니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| isDisable | boolean | 선택적 부울 값입니다. 생략하면 실제로 정수 0(활성화)을 사용하며 기존 값을 유지하지 않습니다. null은 유효하지 않습니다. null 허용: False 선택 가능한 값: [True, False] 예: false획득 또는 입력 방법: true를 전달하면 시스템 매핑을 비활성화하고 false를 전달하면 활성화합니다. 변경하지 않으려면 먼저 스위치를 읽고 현재 값을 명시적으로 다시 채워야 합니다. |
|
| type | string | 선택적 문자열입니다. 생략하면 기본값은 GlobalValid이며 기존 모드를 유지하지 않습니다. ValidOnFirstLogin은 과거 워크스페이스 연결을 기준으로 최초 여부를 판단하고, GlobalValid는 로그인할 때마다 교체/정리하며, Append는 시스템 규칙에 추가합니다. 워크스페이스 사용자 정의 매핑이 우선합니다. null 허용: False 선택 가능한 값: ['ValidOnFirstLogin', 'GlobalValid', 'Append'] 예: ValidOnFirstLogin획득 또는 입력 방법: ValidOnFirstLogin, GlobalValid, Append 중에서 예상에 맞게 선택합니다. 기존 계정의 직접 역할 변경을 먼저 평가하십시오. |
매개변수 추가 설명¶
인증 방식은 External API 서명 인증을 참조하십시오. 이 모듈은 사이트 시스템 로그인 매핑(isSystem=1)을 관리하며, OIDC/LDAP 등 공유 로그인 매핑 경로를 사용하는 타사 로그인에서 사용됩니다. 워크스페이스 사용자 정의 매핑이나 독립적인 SAML 설정 API가 아닙니다. 설정을 저장해도 모든 기존 사용자 권한이 즉시 일괄 재계산되지 않으며, 이후 관련 로그인 시에만 모드에 따라 처리됩니다.
시스템 매핑이 활성화되어 있고 대상 워크스페이스에서 사용자 정의 매핑이 비활성화된 경우: ValidOnFirstLogin은 과거에 직접적인 워크스페이스 연결이 전혀 없는 계정에만 시스템 규칙을 적용합니다(과거에는 삭제된 연결도 포함). 이는 이번에 계정이 새로 생성되었는지만 판단하는 것과 같지 않습니다. GlobalValid는 관련 로그인 시마다 규칙에 따라 직접 역할을 교체하며, 일치하지 않을 때 직접 구성원/역할 관계를 제거할 수 있습니다. Append는 일치하는 시스템 역할만 추가하며, 일치하지 않을 때 기존 직접 관계를 정리하지 않습니다. 워크스페이스에서 사용자 정의 매핑을 활성화한 경우 해당 워크스페이스는 사용자 정의 규칙에 따라 교체/미일치 정리를 우선 수행하며, 시스템 Append 또는 최초 로그인 모드의 보존 의미를 적용할 수 없습니다. 시스템 스위치를 비활성화해도 워크스페이스 사용자 정의 규칙은 동시에 비활성화되지 않습니다. 기존 직접 Owner 역할은 매칭 처리 중 유지되며, 이 모듈을 통해 새 Owner가 부여되지 않습니다.
설정은 데이터베이스와 Redis 캐시에 단계적으로 기록됩니다. 실패 후에는 먼저 다시 읽고 관리자가 영속 설정을 검증해야 하며, 모드를 바로 반복 전환하지 마십시오.
요청 예제¶
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 = 'POST'
path = '/api/v1/login_mapping/set_disable'
query = {}
data = {'isDisable': False, 'type': 'ValidOnFirstLogin'}
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 | boolean | 설정이 완료되면 true이며, 설정 후 객체를 반환하지 않습니다. 스위치 조회를 호출하여 다시 읽으십시오. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
확인된 규칙 및 요청 오류는 표에 나열되어 있습니다. 일반 데이터베이스/캐시/감사 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 설정이 이미 커밋된 후 후속 오류가 발생할 수 있으므로 먼저 현재 상태를 읽은 후 재시도하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 | 매개변수 구문 분석 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 JSON 파일 형식 오류 | 매개변수 표에 따라 JSON 객체를 제출하십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 사이트 구성 캐시, 감사 또는 처리되지 않은 과거 데이터 예외 | 내부 오류 | traceId를 보관하고 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인하십시오. 데이터베이스와 캐시/감사는 동일한 트랜잭션이 아니므로 오류가 완전히 저장되지 않았음을 증명하지 않습니다. |