콘텐츠로 이동

매핑 설정 수정



POST /api/v1/login_mapping/field/{lgmp_uuid}/modify

개요

시스템 로그인 매핑의 소스 속성, 대상 워크스페이스 및 역할을 전체 업데이트합니다.

호출 전 준비 및 사용 단계

먼저 시스템 로그인 매핑 목록에서 규칙을 읽고 백업합니다. sourceField, sourceValue, targetValues는 반드시 제공해야 하며, workspaceUUID는 선택 사항으로 선언되어 있지만 실제로도 반드시 제공해야 합니다. 역할만 변경할 때 기존 워크스페이스가 자동으로 유지되는 방식은 지원되지 않습니다. 다른 활성 워크스페이스로 변경할 수 있으며, 역할은 새 워크스페이스의 유효 범위에 속해야 합니다. targetValues는 전체 대상 기준으로 교체되며 기존 목록과 병합되지 않습니다. 동일한 새 워크스페이스/소스 속성 조합은 다른 시스템 규칙과 충돌할 수 없습니다. 변경은 이후 로그인에 영향을 주므로, 워크스페이스를 마이그레이션하기 전에 GlobalValid 등의 모드가 사용자의 기존 직접 관계를 제거하는지 확인해야 합니다.

경로 파라미터

파라미터명 유형 필수 설명
lgmp_uuid string Y 활성 시스템 매핑 UUID이며 워크스페이스 UUID가 아닙니다.
예시: lgmp_example001
가져오기 또는 입력 방법: 시스템 로그인 매핑 목록의 content.data[].uuid에서 가져옵니다.

요청 헤더

파라미터명 유형 필수 설명
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 요청 파라미터

파라미터명 유형 필수 설명
targetValues[*] string 단일 유효 역할 UUID 문자열입니다. 서로 다른 워크스페이스의 사용자 정의 역할을 혼용할 수 없으며, owner는 거부됩니다.
예시: readOnly
가져오기 또는 입력 방법: 대상 워크스페이스의 워크스페이스 역할 목록에서 단일 역할 uuid를 가져옵니다.
sourceField string Y 필수 최상위 속성 이름이며 최대 40자이고 대소문자를 구분합니다. 계정 표준 필드 별칭이나 JSONPath가 아닙니다. 비어 있지 않은 값을 권장합니다.
null 허용: False
최대 길이: 40
예시: department
가져오기 또는 입력 방법: ID 공급자/LDAP의 실제 userinfo 속성 정의에서 가져옵니다. 계정이 최근 로그인한 후 계정 상세의 content.attributes에서 원본 키를 확인하는 데 도움을 받을 수 있습니다.
sourceValue string Y 필수 문자열이며 최대 256자이고 정확히 일치해야 합니다. 빈 문자열은 속성의 빈 문자열에만 일치하며 임의 값을 의미하지 않습니다. 목록 속성은 단일 요소 값으로 입력합니다.
null 허용: False
최대 길이: 256
예시: 研发部
가져오기 또는 입력 방법: 원본 ID 속성의 실제 값을 사용합니다. 계정 상세의 content.attributes 해당 키 또는 IdP/LDAP 속성에서 확인합니다.
targetValues array Y 필수 전체 역할 배열이며 owner를 포함할 수 없고 null은 허용되지 않습니다. []는 저장할 수 있지만 대상 유효 역할이 없습니다. 이를 안전한 "규칙 비활성화" 방법으로 사용해서는 안 되며, 최종 권한 처리는 로그인 모드에 따라 달라집니다. 먼저 중복을 제거하고 비어 있지 않은 역할 목록을 사용하는 것을 권장합니다.
예시: ["readOnly"]
가져오기 또는 입력 방법: 워크스페이스 역할 목록에서 workspaceUUID 기준으로 해당 워크스페이스의 사용 가능한 역할 uuid를 가져옵니다.
workspaceUUID string Y 대상 활성 워크스페이스 UUID입니다. 수정 요청 선언에서는 선택 사항으로 표시되어 있지만 현재 구현에는 기존 값으로의 폴백이 없으므로 실제로는 반드시 명시적으로 제공해야 합니다.
null 허용: False
예시: wksp_example001
가져오기 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 가져온 후, 해당 워크스페이스 기준으로 역할을 조회합니다.

파라미터 추가 설명

인증 방식은 External API 서명 인증을 참조합니다. 이 모듈은 사이트 시스템 로그인 매핑(isSystem=1)을 관리하며, OIDC/LDAP 등 공유 로그인 매핑 경로를 사용하는 서드파티 로그인에서 사용됩니다. 워크스페이스 사용자 정의 매핑이나 독립적인 SAML 설정 API가 아닙니다. 설정 저장은 모든 기존 사용자 권한을 즉시 일괄 재계산하지 않으며, 이후 관련 로그인 시점에 모드에 따라 처리됩니다.

sourceField는 ID 서비스 원본 userinfo의 최상위 키를 읽으며, 대소문자와 키 이름이 반드시 일치해야 하고 JSONPath 또는 중첩 경로는 지원하지 않습니다. 계정의 customAttributes는 이 매칭의 소스가 아니며, 계정 attributes를 수정해도 ID 서비스의 다음 userinfo는 변경되지 않습니다. sourceValue는 문자열화된 속성 값과 정확히 일치해야 하며, 정규식이나 포함 매칭이 아닙니다. 속성이 목록인 경우 요소별로 매칭하며, 어느 한 요소가 sourceValue와 같으면 됩니다. 여러 매칭 규칙은 동일 워크스페이스에서 유효 역할을 병합합니다. ID 측에서 안정적인 문자열 속성을 제공하는 것을 권장합니다. 숫자는 문자열로 매칭되고, 불리언은 True/False, null은 None, 객체는 JSON이 아닌 내부 문자열 형태로 처리되므로 객체 값을 사용해 규칙을 구성하는 것은 권장하지 않습니다.

시스템 매핑이 켜져 있고 대상 워크스페이스의 사용자 정의 매핑이 꺼져 있는 경우: 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 = 'POST'
path = '/api/v1/login_mapping/field/lgmp_example001/modify'
query = {}
data = {'workspaceUUID': 'wksp_example001', 'sourceField': 'department', 'sourceValue': '研发部', 'targetValues': ['readOnly']}
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이며 규칙 상세는 반환하지 않습니다. 목록에서 uuid로 다시 조회합니다.
{
  "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 객체를 제출합니다.
401 ft.WKSPNotExistOrReleased 대상 workspaceUUID가 활성 워크스페이스에 해당하지 않거나, 수정 시 이 실제 필수 파라미터를 생략함 워크스페이스가 존재하지 않음/또는 이미 해제됨 워크스페이스 목록에서 활성 uuid를 가져와 수정 요청에 명시적으로 포함합니다.
400 ft.LoginMappingNotSupportSetOwner targetValues에 owner 포함 소유자 역할로의 매핑은 지원되지 않음 공식 Owner 인계 절차를 통해 처리하며, 이 API는 허용된 다른 역할만 매핑합니다.
404 ft.LoginMappingNoExists UUID가 존재하지 않거나, 삭제되었거나, 활성 status=0이 아니거나, 시스템 매핑이 아님 지정된 Login Mapping을 찾을 수 없음 이 모듈의 시스템 매핑 목록에서 유효한 uuid를 다시 선택하며, 워크스페이스 사용자 정의 규칙 UUID를 사용하지 않습니다.
404 ft.LoginMappingFieldAlreadyExists 동일한 대상 워크스페이스에 동일한 sourceField와 sourceValue를 가진 활성 시스템 규칙이 이미 존재함 워크스페이스에 동일한 매핑 필드 이름과 필드 값이 이미 존재함 기존 규칙을 조회하여 수정하거나, 다른 속성과 값을 사용합니다. 이 오류의 HTTP 상태는 404이므로 규칙이 생성되지 않았다고 오해하고 무한 재시도해서는 안 됩니다.
406 ft.InvalidRoleUuidBelongsWSKP targetValues에 유효하지 않거나, 삭제되었거나, 대상 워크스페이스의 허용 범위에 속하지 않는 역할 UUID가 포함됨 현재 설정된 TargetValues에 유효하지 않은 역할 UUID가 존재함 대상 워크스페이스 역할 목록에서 유효한 uuid를 가져옵니다. 다른 워크스페이스의 사용자 정의 역할을 복사할 수 없습니다.
500 ft.InternalServerError 데이터베이스, 사이트 설정 캐시, 감사 또는 처리되지 않은 이력 데이터 예외 내부 오류 traceId를 보존하고, 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인합니다. 데이터베이스와 캐시/감사는 동일한 트랜잭션이 아니므로 오류가 완전히 저장되지 않았음을 증명하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?