콘텐츠로 이동

매핑 설정 추가



POST /api/v1/login_mapping/field/add

개요

ID 속성을 대상 워크스페이스 역할에 매핑하는 시스템 로그인 매핑을 생성합니다.

호출 전 준비 및 사용 단계

먼저 실제 ID 속성 이름/값, 활성 워크스페이스, 역할 UUID를 준비하고, 매핑 스위치 및 모드를 읽어 스위치와 모드를 확인한 후 생성합니다. 성공하면 규칙 스냅샷이 반환되며, 이후 목록에서 uuid로 확인합니다. 동일 워크스페이스, 소스 필드 이름, 소스 필드 값에는 활성 시스템 규칙을 하나만 허용합니다. 여러 역할은 동일한 targetValues 배열에 넣습니다. 규칙을 저장한다고 해서 기존 사용자에게 즉시 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 요청 파라미터

파라미터 이름 타입 필수 설명
targetValues[*] string 단일 유효 역할 UUID 문자열입니다. 서로 다른 워크스페이스의 사용자 지정 역할을 혼용할 수 없으며, owner는 거부됩니다.
예시: readOnly
획득 또는 입력 방법: 대상 워크스페이스의 워크스페이스 역할 목록에서 단일 역할 uuid를 가져옵니다.
sourceField string Y 필수 최상위 속성 이름으로, 최대 40자이며 대소문자를 구분합니다. 계정 표준 필드 별칭이나 JSONPath가 아닙니다. 비어 있지 않은 값을 권장합니다.
null 허용: False
최대 길이: 40
예시: department
획득 또는 입력 방법: IdP/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/add'
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.id integer 또는 null 레코드 일련번호입니다. 생성 스냅샷에서는 null일 수 있으며, 작업에는 uuid를 사용합니다.
content.uuid string 매핑 레코드 UUID로, 일반적으로 lgmp_ 접두사를 가집니다.
content.status integer 규칙 상태이며 활성은 0입니다. 목록 필터는 3이지만 이력상 다른 상태가 포함될 수 있고, 실제 로그인 소비 및 수정/삭제는 0만 처리합니다.
content.creator string 생성 주체이며 External은 보통 sys입니다.
content.updator string 수정 주체이며, 수정되지 않은 경우 비어 있을 수 있습니다.
content.createAt integer 생성 Unix 초입니다.
content.deleteAt integer 삭제 Unix 초이며, 삭제되지 않은 경우 보통 -1입니다.
content.updateAt integer 수정 Unix 초이며, 아직 수정되지 않은 경우 보통 -1입니다.
content.sourceField string 매칭된 원본 userinfo 최상위 속성 이름입니다.
content.sourceValue string 매칭된 속성 문자열 값입니다.
content.targetValues 문자열 배열 저장된 대상 역할 UUID 목록이며, 이력 목록 항목만으로 역할이 여전히 유효하다고 단정할 수 없습니다.
content.targetValues[] string 개별 대상 역할 UUID입니다.
content.workspaceUUID string 이 규칙의 대상 워크스페이스 UUID입니다.
content.isSystem integer 또는 boolean 이 모듈은 시스템 매핑이므로 1 또는 true입니다. 워크스페이스 사용자 지정 규칙이 아닙니다.
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "lgmp_example001",
    "status": 0,
    "creator": "sys",
    "updator": "",
    "createAt": 1785427200,
    "deleteAt": -1,
    "updateAt": -1,
    "sourceField": "department",
    "sourceValue": "研发部",
    "targetValues": [
      "readOnly"
    ],
    "workspaceUUID": "wksp_example001",
    "isSystem": 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.LoginMappingFieldAlreadyExists 동일 대상 워크스페이스에 동일한 sourceField와 sourceValue를 가진 활성 시스템 규칙이 이미 존재함 워크스페이스에 동일한 매핑 필드 이름과 필드 값이 이미 존재함 기존 규칙을 조회하여 수정하거나 다른 속성과 값을 사용합니다. 이 오류의 HTTP는 404이므로 규칙이 생성되지 않았다고 오판하여 무한 재시도하지 마십시오.
406 ft.InvalidRoleUuidBelongsWSKP targetValues에 유효하지 않거나, 삭제되었거나, 대상 워크스페이스 허용 범위에 속하지 않는 역할 UUID가 포함됨 현재 설정된 TargetValues에 유효하지 않은 역할 UUID가 존재함 대상 워크스페이스 역할 목록에서 유효한 uuid를 가져옵니다. 다른 워크스페이스의 사용자 지정 역할을 복사할 수 없습니다.
500 ft.InternalServerError 데이터베이스, 사이트 설정 캐시, 감사 또는 처리되지 않은 이력 데이터 예외 내부 오류 traceId를 보존하고, 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인합니다. 데이터베이스와 캐시/감사는 동일 트랜잭션이 아니므로, 오류가 완전히 저장되지 않았음을 증명하지 않습니다.

문서 평가

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