콘텐츠로 이동

매핑 규칙 활성화/비활성화(레거시 호환 API)



POST /api/v1/saml/mapping/set_disable

개요

단일 SSO 구성에 대해 역할 매핑 스위치를 활성화하거나 비활성화합니다.

호출 전 및 사용 단계

이 API는 레거시 주소 호환 API이며, 현재 소스 코드에도 실제로 등록되어 있습니다. 과거 “2026-05-31 지원 중단” 주석은 현재 요청이 금지되었음을 의미하지 않습니다. 신규 연동 시에는 매핑 규칙 활성화/비활성화를 우선 사용하십시오. 레거시 경로는 동일한 컨트롤러/요청 필드/응답을 사용하며, saml 접두사 때문에 OIDC를 제외하지 않습니다.

이 그룹은 특정 SSO 공급자의 로그인 attributes를 현재 워크스페이스 역할에 매핑하며, 배포 플랜 LDAP/OIDC의 custom_login_mapping 및 시스템 매핑과는 다릅니다. 규칙을 생성해도 매핑이 자동으로 활성화되지는 않습니다. 해당 SSO 구성에서 isOpenSAMLMapping(이 그룹의 set_disable)을 활성화해야 하며, SSO 구성 자체도 활성화되어 있어야 합니다.

속성 이름 매칭은 소문자로 비교하며, 값은 정규식/포함 매칭이 아닙니다. 문자열 배열은 각 값을 개별적으로 매칭합니다. 배열이 아닌 객체/숫자/null 등은 먼저 json.dumps로 문자열로 변환하며, 배열 요소는 일괄적으로 문자열로 변환되지 않습니다. 따라서 ID 소스에서 안정적인 문자열 속성과 문자열 배열을 우선 사용하십시오. 여러 역할이 매칭되면 합집합을 사용합니다. SSO 매핑을 활성화한 후 규칙이 없거나 매칭되는 규칙이 없으면 계정이 이 공간에 들어오는 것을 금지할 수 있으며, 이후 로그인/전환 시 기존 연결을 삭제합니다. 기본 역할을 단순히 추가하는 방식이 아닙니다. 저장 후 공간 및 멤버 캐시를 비동기로 새로 고치므로 기존 SSO 세션의 후속 액세스에 영향을 줄 수 있으며, 다음 로그인 때만 적용된다고 보장할 수 없습니다.

isDisable=true이면 매핑을 비활성화하고 공급자 기본 역할 로직으로 돌아갑니다. 이후 로그인 시 기존 역할 연결이 있으면 유지하며, 기존 역할 연결이 없을 때만 기본 role을 보충합니다. 기존 매핑 역할을 일괄적으로 기본값으로 재설정하지는 않습니다. 비활성화하기 전에 해당 기본 역할을 먼저 검증합니다. general/readOnly 또는 이 공간에서 유효한 사용자 정의 역할은 허용되며, Owner/wsAdmin은 허용되지 않습니다. isDisable=false이면 매핑을 활성화합니다. 현재 구현은 워크스페이스에 임의의 활성 매핑이 있는지 여부만 확인하고 대상 ssoUUID를 제한하지 않으므로, true라고 해서 해당 공급자에 매칭 가능한 규칙이 이미 있다는 것을 증명할 수는 없습니다. 먼저 이 그룹의 list?ssoUUID로 규칙과 대상 역할을 확인하여, 활성화 후 계정에 권한이 없게 되는 상황을 피하십시오.

이 작업은 SSOSetting.isOpenSAMLMapping만 변경하며, SSOSetting.status를 변경하거나 매핑 행을 일괄 비활성화하지 않습니다. SSO 구성 자체가 비활성화된 경우 매핑을 활성화해도 로그인이 함께 활성화되지는 않습니다. 제출 후 공간/멤버 캐시를 비동기로 새로 고치며, SSO 구성 변경 이메일은 전송하지 않습니다. 성공이 모든 사용자의 권한 부여가 올바르다는 것을 보장하지는 않습니다.

요청 헤더

파라미터명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
가져오거나 입력하는 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터명 유형 필수 설명
isDisable boolean Y 필수 불리언, isOpenSAMLMapping=1/0을 반대로 제어하며, 공급자 자체의 시작/중지를 의미하지 않습니다.
null 허용: False
예시: false
가져오거나 입력하는 방법: false이면 매핑을 활성화하고, true이면 비활성화합니다.
ssoUUID string Y 필수이며, 이 작업은 이 공간에서 삭제되지 않은 공급자(비활성화된 구성 포함)가 존재하는지 검증합니다.
예시: sso_example
가져오거나 입력하는 방법: 이 공간의 SSO 구성 목록에서 대상 공급자 UUID를 가져옵니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/saml/mapping/set_disable' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"ssoUUID":"sso_example","isDisable":false}'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content boolean 성공 시 true이며, 스위치 제출 및 캐시 작업 디스패치가 성공했음을 나타낼 뿐입니다.
{
  "code": 200,
  "content": true,
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인하십시오.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정하십시오.
400 ft.JsonFormatError Body가 객체가 아님 일부 JSON 파일 형식 오류 ssoUUID/isDisable 객체를 제출하십시오.
406 ft.NotFoundSAML 대상 공급자가 이 공간의 삭제되지 않은 구성에 속하지 않음 SSO 구성을 찾을 수 없음 SSO 목록에서 유효한 UUID를 다시 가져오십시오.
404 ft.NotFoundSSOMappingEnableFailed 활성화 시 워크스페이스에 활성 매핑이 없음 활성화 실패, 역할 매핑 규칙을 찾을 수 없음 먼저 대상 공급자에서 실제로 사용 가능한 매핑을 생성한 후 활성화하십시오.
400 ft.InvalidSsoRoleCfg 비활성화 시 기본 역할이 Owner 또는 wsAdmin임 관리자, 소유자 역할 구성은 지원되지 않음 먼저 SSO 기본 역할을 허용되는 값으로 수정하십시오.
400 ft.InvalidCustomRole 비활성화 시 기본 사용자 정의 역할을 사용할 수 없거나 현재 공간에 표시되는 활성 역할이 아님 유효하지 않은 사용자 정의 역할 이 공간의 역할 목록에서 사용 가능한 기본 역할을 선택하십시오.
500 ft.InternalServerError 저장된 JSON 형태, 데이터베이스 또는 제출 후 작업 디스패치 중 처리되지 않은 예외 발생 내부 오류 데이터베이스는 커밋되었지만 캐시 작업 디스패치가 실패했을 수 있으므로, 먼저 목록에서 규칙/SSO 스위치를 다시 읽은 후 처리하고 traceId를 보관하십시오.

문서 평가

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