콘텐츠로 이동

매핑 규칙 활성화/비활성화



POST /api/v1/sso_mapping/set_disable

개요

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

호출 전 및 사용 단계

본 API 그룹은 특정 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/sso_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를 보존하십시오.

문서 평가

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