매핑 설정 추가¶
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를 보존하고, 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인합니다. 데이터베이스와 캐시/감사는 동일 트랜잭션이 아니므로, 오류가 완전히 저장되지 않았음을 증명하지 않습니다. |