콘텐츠로 이동

SSO 구성 업데이트



POST /api/v1/sso/{sso_uuid}/modify

개요

기존 SAML/OIDC ID 공급자 구성 및 이메일 허용 목록을 업데이트합니다.

호출 전 및 사용 단계

먼저 get으로 현재 공급자와 허용 목록을 백업하고, 원래 type에 따라 필요한 필드를 전체 업데이트합니다. type은 전환할 수 없습니다. emailDomains/idpName/role은 필수 클레임이며, 허용 목록은 전체 교체되고 []는 비웁니다. remark를 생략하면 비워지고, 두 세션 시간은 생략하면 유지됩니다. config를 생략하거나 {}를 전달하면 기존 값이 유지되고, 비어 있지 않은 값은 전체 교체됩니다. OIDC는 필수 필드를 완전히 다시 채워야 하며, 기존 secret을 유지하려면 get에서 반환된 Base64 별표 값을 전달합니다. SAML에서 비어 있지 않은 config를 업데이트할 때는 유효한 idpData도 함께 다시 채워야 합니다. XML만 변경할 경우 config를 생략해 기존 매핑을 유지할 수 있으며, {}는 기존 config를 비우는 의미가 아닙니다.

생성/수정은 전체 SSO 로그인 검증을 수행하지 않습니다. wellKnowURL을 제공하면 저장 단계에서 동기적으로 실제 GET 서비스 디스커버리를 수행합니다(저장 단계 기본 TLS 검증). 해당 주소가 없으면 명시적인 auth/token/userinfo 세 엔드포인트를 사용할 수 있습니다. 기타 인증, code를 token으로 교환, JWT/UserInfo 프로토콜 세부 사항은 로그인 시에만 사용됩니다. 현재 userinfo가 get이 아니어도 여전히 GET+Body로 전송되므로 POST 엔드포인트의 사용 가능성을 보장하지 않습니다. OIDC 기본 scope는 openid만, 사용자 소스는 origin입니다. email/profile이 필요하면 IdP 권한에 따라 명시적으로 지정하고 실제로 테스트해야 합니다. 클레임 필드 유형 외에도 많은 동적 필드는 저장 시 엄격하게 검증되지 않으므로, 200 응답만으로 전체 흐름의 로그인 가능성을 판단할 수 없습니다.

IdP ID(예: SAML entityID/로그인 서비스 주소, OIDC 인가 주소/clientId)를 수정하면 계정 네임스페이스가 변경되고 멤버 워크스페이스 연결 정리가 트리거될 수 있습니다. 현재 정리는 새 ID 다이제스트를 기준으로 수행되며, "이전 공급자 사용자만 연결 해제"됨을 보장하지 않습니다. 공유 멤버 제거는 역할/개인 Key/구독 등 기존 정리 규칙에도 관련될 수 있으므로, 관련 멤버와 대체 관리자 진입점을 먼저 확인하십시오. 인증서/secret 또는 휴대폰 번호 매핑만 업데이트한다고 해서 해당 ID 다이제스트가 반드시 변경되는 것은 아닙니다.

데이터베이스 커밋 후 워크스페이스/멤버 캐시 새로 고침이 전달되어 기존 SSO 액세스가 다시 인증될 수 있습니다. 구성 응답이 캐시가 모두 새로 고침되었음을 의미하지는 않습니다. needNotify 기본값 true는 워크스페이스 Owner/관리자에게 구성 알림을 보냅니다. false는 메일만 억제하며 감사/캐시는 계속 수행되고, 메일 전송 실패는 기록되지만 구성을 롤백하지 않습니다. 수정 응답에 emails가 항상 포함되는 것은 아니므로 다시 get으로 허용 목록을 검증해야 합니다. 쓰기 응답의 secret은 저장 암호문이며, 상세 get에서만 보존에 사용할 수 있는 별표 마스크를 반환합니다.

경로 파라미터

파라미터명 유형 필수 설명
sso_uuid string Y 수정할 원래 프로토콜 공급자이며, IdP clientId 또는 매핑 fdmp_를 사용하지 않습니다.
예: sso_example
가져오기 또는 입력 방법: 이 워크스페이스의 SSO 목록/get에서 대상 sso_ 구성 UUID를 가져옵니다.

요청 헤더

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

Body 요청 파라미터

파라미터명 유형 필수 설명
emailDomains[*] string 비어 있지 않은 문자열을 권장합니다. 공개 배열은 각 항목의 이메일 형식을 엄격히 검증하지 않으며, 잘못된 객체/중첩 배열은 500을 유발할 수 있고 길이는 저장 기준 256으로 제어됩니다.
예: example.com
가져오기 또는 입력 방법: 실제 이메일/도메인 식별자 하나를 사용하며, ID 소스에서 반환되는 email과 일치시킵니다.
config.modeType string 선택 사항: easy/expert, 기본값 easy. 이 필드는 주로 편집 모드를 보존하며, 임의의 전문가 구성을 실행 가능한 것으로 자동 검증하지 않습니다.
예: expert
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.wellKnowURL string 선택적 HTTP(S) 디스커버리 주소입니다. 제공하면 저장 단계에서 실제 GET 후 JSON을 파싱합니다(오프라인 검증 아님). 요청 실패/SSL/HTTP 오류는 이 페이지의 오류로 처리됩니다. 생략하려면 auth/token/userinfo 세 엔드포인트를 명시해야 하며, modeType=expert만 작성해서는 안 됩니다.
예: https://idp.example.com/.well-known/openid-configuration
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.sslVerify boolean 디스커버리 요청 TLS 검증 스위치입니다. 저장 단계 기본값 true이며, 런타임 SDK는 HTTPS 기본 true, HTTP 기본 false로 동작합니다. 각 엔드포인트의 verify를 통합 대체하는 스위치로 간주하지 않습니다.
예: true
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.clientId string OIDC 필수 비어 있지 않은 문자열이며 앞뒤 공백이 없어야 합니다. IdP 클라이언트 등록에서 가져오며 Studio API Key가 아닙니다.
예: client_example
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.clientSecret string OIDC 클라이언트 secret UTF-8 평문을 먼저 Base64로 인코딩합니다(예시는 자리 표시자 평문의 인코딩이며 실제 secret이 아닙니다). 생성 시 디코딩 후 비어 있지 않아야 하고 모두 별표여서는 안 됩니다. Base64는 암호화 전송을 의미하지 않으므로 HTTPS를 사용해야 합니다. 비어 있지 않은 config를 수정할 때 기존 secret을 유지하려면 get에서 반환된 Base64 별표 마스크를 가져옵니다. 생략/빈 문자열은 이후 구성 검증에서 거부되며 유지 지시가 아닙니다. create/modify 응답의 저장 암호문을 다시 전달하지 마십시오.
예: U0VDUkVULVBMQUNFSE9MREVS
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.grantType string 선택 사항 authorization_code/code, 생략 시 런타임 기본값 authorization_code입니다. client_credentials 또는 password 권한 부여가 아닙니다.
예: authorization_code
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.scope array 선택적 문자열 배열입니다. 런타임 SDK 기본값은 [openid]만이며, 이전 설명의 openid/profile/email이 아닙니다. IdP가 계정에 필요한 email 등 클레임을 실제로 제공하는지 확인하십시오. 빈 배열은 빈 scope를 생성하므로 클라이언트가 합리적으로 명시 구성해야 합니다.
예: ["openid", "profile", "email"]
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.scope[*] string IdP가 허용하는 단일 scope이며, 이 워크스페이스의 권한 포인트가 아닙니다.
예: email
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.authSet json 인가 리다이렉트 파라미터 객체이며, 생략 시 디스커버리 문서에서 주소를 채울 수 있습니다.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet json code를 token으로 교환하는 요청 객체이며, 생략 시 엔드포인트를 디스커버리 문서에서 가져옵니다.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet json id_token 서명 검증 JWK 객체이며, 구성을 저장하기 위해 즉시 token 인증을 시작하는 것이 아닙니다.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet json 사용자 정보 소스/요청 객체이며, 기본값 origin으로 이전 설명의 기본 id_token이 아닙니다.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.claimMapping json 계정 필드에서 IdP 실제 속성명으로의 매핑이며 역할 매핑 규칙이 아닙니다. OIDC 저장은 항목별 엄격 검증이 없으므로 실제 콜백을 테스트해야 합니다. SAML 비어 있지 않은 매핑은 비어 있지 않은 username/email을 함께 제공해야 하며 mobile은 선택적 문자열입니다. 빈 객체는 기존 기본값과 호환됩니다.
예: {"username": "preferred_username", "email": "email", "mobile": "phone_number"}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.authSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 authorization_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
예: https://idp.example.com/authorize
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.authSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.authSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
예: $client_id
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 token_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
예: https://idp.example.com/token
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
예: true
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
예: $client_id
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 jwks_uri를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
예: https://idp.example.com/jwks
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
예: true
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 userinfo_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
예: https://idp.example.com/userinfo
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
예: true
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
예: $client_id
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.method string 선택 사항 get/post, 기본값 post, 런타임은 이 두 가지만 지원합니다. 저장 시 이 열거형을 강제하지 않으며 다른 값은 이후 로그인 시 오류가 발생합니다.
예: post
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getTokenSet.authMethod string 선택 사항 basic/client_secret_basic(기본 Basic 헤더), client_secret_post(기본 폼에 ID와 secret 포함), none(기본적으로 client_id만 사용하며 secret을 자동 포함하지 않음). 사용자 정의 paramMapping이 있으면 전체 매핑에 따라 파라미터를 생성하며, Basic 헤더는 여전히 선택한 인증 방식을 따릅니다.
예: client_secret_basic
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.method string 기본값 get입니다. 현재 SDK의 비-get 분기는 여전히 GET을 보내지만 파라미터를 Body에 넣으므로 진정한 POST가 아닙니다. POST가 필요한 IdP는 저장 성공만으로 지원된다고 판단해서는 안 되며, 검증된 GET 엔드포인트 사용을 권장합니다.
예: get
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.authMethod string 기본값 bearer 헤더, client_secret_basic은 Basic 헤더 사용, none은 기본적으로 access_token을 파라미터에 넣습니다. basic 별칭 또는 기타 임의 값을 동일하게 유효한 것으로 간주하지 않습니다.
예: bearer
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.source string origin은 userinfo 호출(기본값), id_token은 id_token 검증 및 읽기, merge는 먼저 id_token 후 userinfo로 동일 키를 덮어씁니다. 저장 시 열거형을 강제하지 않으므로 다른 값은 최종적으로 사용자 정보가 없을 수 있습니다.
예: origin
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.getUserInfoSet.responseInfoPath string 선택적 응답 내 사용자 객체의 점 경로이며 origin 결과에서만 추출합니다. 빈 문자열은 전체 응답을 사용하며 claimMapping의 속성명과 다릅니다.
예: data.user
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.keys array 선택적 IdP 공개 JWK 배열입니다. 비어 있지 않으면 직접 서명 검증에 사용하고, 그렇지 않으면 런타임에 verifyTokenSet.url을 GET하여 keys를 가져옵니다. 개인 키가 아니며 예시 자리 표시자 자료를 실제 서명 검증 구성으로 간주하지 마십시오.
예: []
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.keys[*] json 단일 공개 JWK이며 IdP가 게시한 kty/alg/kid 및 공개 키 파라미터에 따라 전체 구조를 유지합니다.
예: {}
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.keys[*].kty string 공개 키 유형(예: RSA/EC)이며 IdP JWK를 기준으로 합니다.
예: RSA
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].kid string 공개 키 선택에 사용되는 식별자입니다.
예: KEY-ID
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].use string 키 용도입니다.
예: sig
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].alg string 서명 검증 알고리즘 식별자입니다.
예: RS256
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].n string RSA 모듈러스 Base64url입니다.
예: PUBLIC-MODULUS
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].e string RSA 공개 지수 Base64url입니다.
예: AQAB
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].crv string EC 곡선이며 해당 유형에만 적용됩니다.
예: P-256
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].x string EC 공개 x 좌표입니다.
예: PUBLIC-X
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].y string EC 공개 y 좌표입니다.
예: PUBLIC-Y
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].x5c array 공개 인증서 체인 Base64 DER 배열, 선택 사항입니다.
예: ["PUBLIC-CERTIFICATE"]
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].x5c[*] string 단일 공개 인증서이며 개인 키를 포함하지 않습니다.
예: PUBLIC-CERTIFICATE
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.verifyTokenSet.keys[*].其他公开字段 JSON IdP JWK 확장은 라이브러리 프로토콜에 따라 보존하며 d/p/q 등 개인 키 자료를 추가하지 않습니다.
예: VALUE
가져오기 또는 입력 방법: IdP 공식 JWKS에서 전체 공개 값을 가져오며 수동으로 추측해 만들지 않습니다.
config.claimMapping.username string OIDC 기본값 preferred_username, SAML 기본값 username. SAML에서 명시적 비어 있지 않은 claimMapping일 때 비어 있지 않은 문자열이 필수입니다.
예: preferred_username
가져오기 또는 입력 방법: IdP 관리자가 실제 속성명을 제공해야 합니다. 필드 매핑은 휴대폰 번호/email을 값으로 고정 작성하는 것이 아닙니다.
config.claimMapping.email string 기본값 email이며 실제 로그인 시 유효한 이메일을 반드시 얻어야 합니다. SAML에서 명시적 비어 있지 않은 claimMapping일 때 필수이며, OIDC 저장은 값/소스를 검증하지 않지만 콜백에서는 여전히 이메일을 요구합니다.
예: email
가져오기 또는 입력 방법: IdP 관리자가 실제 속성명을 제공해야 합니다. 필드 매핑은 휴대폰 번호/email을 값으로 고정 작성하는 것이 아닙니다.
config.claimMapping.name string OIDC 선택적 표시 이름 속성, 기본값 name. SAML은 현재 name을 고정으로 읽으며 이 매핑 키는 표시 이름 추출을 변경하지 않습니다.
예: name
가져오기 또는 입력 방법: IdP 관리자가 실제 속성명을 제공해야 합니다. 필드 매핑은 휴대폰 번호/email을 값으로 고정 작성하는 것이 아닙니다.
config.claimMapping.mobile string OIDC 기본값 phone_number, SAML 기본값 mobile, 명시적 빈 문자열은 추출하지 않습니다. 번호가 없으면 보충하지 않으며, 기존 휴대폰 번호와 국가 코드는 유지하고 원래 계정에 번호가 없고 IdP 번호가 유효할 때만 보충합니다.
예: phone_number
가져오기 또는 입력 방법: IdP 관리자가 실제 속성명을 제공해야 합니다. 필드 매핑은 휴대폰 번호/email을 값으로 고정 작성하는 것이 아닙니다.
config.authSet.verify boolean 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
예: true
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.method string 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
예: get
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config.verifyTokenSet.authMethod string 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
예: get
가져오기 또는 입력 방법: ID 공급자가 현재 클라이언트에 할당한 공식 OIDC 구성 및 실제 프로토콜 문서에서 가져옵니다.
config json 동적 전체 구성 객체이며 OIDC 생성 시 비즈니스 필수입니다. 수정 시 생략하거나 {}이면 기존 config가 유지되고, 비어 있지 않은 객체는 전체 교체이며 재귀 병합이 아닙니다. OIDC는 clientId/clientSecret/유효한 URL 등을 다시 채워야 합니다. SAML은 비어 있지 않은 config만 제출하고 idpData를 생략할 수 없습니다. 내부 필드 유형이 모두 강력하게 검증되지는 않으므로 저장 통과가 콜백 사용 가능성을 증명하지 않습니다.
null 허용: False
예: {}
가져오기 또는 입력 방법: OIDC는 공급자 client/디스커버리 문서 및 프로토콜 파라미터로 구성하고, SAML은 선택적 claimMapping에만 사용합니다.
emailDomains array Y 필수 배열이며 [] 가능하고 서버 측 set으로 중복 제거합니다. URL, 정규식 또는 @가 포함된 와일드카드가 아닙니다. 최초 진입 검색은 전체 이메일 또는 도메인 등가 매칭을 사용하며, 기존 SSO ID에는 별도의 네임스페이스/워크스페이스 관계 규칙이 있으므로 범용 액세스 제어의 대체물로 사용할 수 없습니다. 수정 시 허용 목록을 전체 교체하며 []는 비웁니다.
예: ["example.com"]
가져오기 또는 입력 방법: 이 공급자의 검색을 허용할 전체 이메일 또는 이메일 도메인을 사용합니다(예: user@guance.com 또는 example.com).
idpData string SAML 생성 시 비즈니스 필수이며 entityID, SSO 서비스 주소 및 키 설명을 포함해야 합니다. 수정 시 생략/빈 문자열이면 기존 XML을 유지합니다. SAML에서 비어 있지 않은 config를 제출할 때는 유효한 XML도 함께 다시 채워야 합니다. OIDC에는 전달하지 마십시오. OIDC에서 idpData만 변경되고 config가 없으면 ID 다이제스트가 None으로 기록되어 500이 발생할 수 있습니다.
null 허용: False
예: <IdP_METADATA_XML>
가져오기 또는 입력 방법: SAML ID 공급자 관리자로부터 전체 유효한 IdP metadata XML을 다운로드하여 원문 문자열로 제출합니다.
idpName string Y 필수 ≤64자, 선언 정규식 [a-zA-Z_一-龥-]; 영문/중국어/밑줄/하이픈만 사용을 권장하며 숫자/공백은 사용하지 마십시오. 현재 정규식은 완전 앵커링이 아니므로 임의의 끝 문자가 안정적으로 거부된다는 의미가 아닙니다. 동일 워크스페이스의 삭제되지 않은 공급자 이름은 중복될 수 없으며, 수정 시 비어 있지 않을 때만 기존 이름을 덮어씁니다.
$matchRegExp: [a-zA-Z_一-龥-]

최대 길이: 64
예: ExampleIdP
가져오기 또는 입력 방법: 현재 워크스페이스 ID 공급자를 업무적으로 구분하는 이름입니다.
needNotify boolean 생성/수정 시 선택 사항, 기본값 true입니다. false는 구성 알림 메일만 억제하며 구성 저장, 캐시 새로 고침 또는 감사를 막지 않습니다. SSO를 끄거나 사용자 로그인을 금지하는 것이 아닙니다.
null 허용: False
예: false
가져오기 또는 입력 방법: 워크스페이스 Owner/관리자에게 구성 변경을 알릴지 여부이며, 일괄 사전 검토에서는 절차에 따라 명시적으로 false로 설정할 수 있습니다.
remark string 선택 사항이며 빈 문자열 허용. 생성 시 생략하면 응답이 null로 구성될 수 있고 데이터베이스 열에는 빈 문자열 기본값이 있습니다. 명시적 빈 문자열 또는 유효한 텍스트를 권장합니다. 수정 시 생략하면 빈 문자열("")로 비워지며 유지가 아닙니다. 저장 열은 512이며 공개적으로 통합 상한이 선언되지 않았습니다.
빈 문자열 허용: True
null 허용: False
예: 企业登录
가져오기 또는 입력 방법: 비즈니스 담당자가 용도 메모를 작성합니다.
role string Y 필수 general/readOnly 또는 이 워크스페이스에서 표시되는 활성 사용자 정의 역할입니다. owner/wsAdmin은 금지됩니다. 매핑이 꺼져 있을 때 새 역할 관계 생성에 사용되며 기존 멤버의 모든 이전 역할을 강제로 덮어쓴다고 보장하지 않습니다. 역할 매핑이 켜져 있으면 매핑 일치에 따라 액세스가 결정됩니다.
빈 문자열 허용: False
null 허용: False
예: general
가져오기 또는 입력 방법: 이 워크스페이스의 역할 목록에서 기본 로그인 역할을 선택합니다.
tokenHoldTime integer 선택 사항 60..604800초, 생성 시 생략하면 사이트 기본값(저장소 기준 604800=7일), 수정 시 생략하면 기존 값을 유지합니다. 캐시 code 유효 시간이 아니며, 이 값으로 일회성 인증 code 소비 창을 확대하지 않습니다.
null 허용: False
$maxValue: 604800
$minValue: 60
예: 604800
가져오기 또는 입력 방법: 조직의 비활성 세션 유지 정책에 따라 초를 선택합니다.
tokenMaxValidDuration integer 선택 사항 60..2592000초, 생성 시 생략하면 사이트 기본값(저장소 기준 2592000=30일), 수정 시 생략하면 유지됩니다. 이전 설명의 "30일=604800"은 올바르지 않으며, 비활성 유지 시간을 대체하지 않습니다.
null 허용: False
$maxValue: 2592000
$minValue: 60
예: 2592000
가져오기 또는 입력 방법: 조직의 로그인 세션 최대 수명에 따라 초를 선택합니다.

파라미터 추가 설명

OIDC 사용자 정의 파라미터 매핑은 단계별로 사용됩니다.

단계 지원되는 변수 값
authSet $state, $client_id, $client_secret, $redirect_uri, $scope, $response_type(code), $grant_type; secret을 브라우저 URL에 넣지 마십시오
getTokenSet $state, $code, $client_id, $client_secret, $redirect_uri, $scope, $grant_type; 기타 키가 콜백 파라미터명과 일치하면 해당 값을 사용할 수 있고, 그렇지 않으면 고정 텍스트로 처리합니다
getUserInfoSet $client_id, $client_secret, $redirect_uri, $scope, $access_token

매핑 객체가 비어 있지 않으면 기본 요청 파라미터를 대체하며, 누락된 redirect_uri/code/scope 등 필수 항목을 자동으로 보충하지 않습니다. 저장은 일부 URL/client 필드만 검증하고 전체 인증 흐름을 수행하지 않습니다. 전용 테스트 ID에서 실제 콜백과 최종 워크스페이스 액세스를 검증해야 합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/sso/sso_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"emailDomains":["example.com"],"idpName":"ExampleIdP","role":"general","remark":"企业登录","config":{"modeType":"expert","clientId":"client_example","clientSecret":"KioqKioqKioq","scope":["openid","profile","email"],"grantType":"authorization_code","authSet":{"url":"https://idp.example.com/authorize"},"getTokenSet":{"url":"https://idp.example.com/token","method":"post","authMethod":"client_secret_basic"},"verifyTokenSet":{"url":"https://idp.example.com/jwks"},"getUserInfoSet":{"url":"https://idp.example.com/userinfo","method":"get","authMethod":"bearer","source":"origin"},"claimMapping":{"username":"preferred_username","email":"email","mobile":"phone_number"}},"tokenHoldTime":604800,"tokenMaxValidDuration":2592000,"needNotify":false}'

응답

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

필드 유형 설명
content.id integer 또는 null 현재 레코드 번호이며, 신규 제출 전 구성 결과는 null일 수 있습니다.
content.uuid string sso_ 구성 UUID입니다.
content.type string saml/oidc입니다.
content.workspaceUUID string 소속 워크스페이스입니다.
content.idpName string 공급자 표시 이름입니다.
content.remark string 또는 null 비고이며, 기존/신규 생성 이력에서 null일 수 있습니다.
content.role string 기본 역할 식별자입니다.
content.idpMd5 string 공급자 ID/계정 네임스페이스 다이제스트이며 클라이언트 키 또는 쓰기 가능한 ID가 아닙니다.
content.tokenHoldTime integer 비활성 세션 유지 초입니다.
content.tokenMaxValidDuration integer 로그인 세션 최대 초입니다.
content.isOpenSAMLMapping integer 또는 boolean 역할 매핑 스위치 1/0이며 SSO 구성 status와 동일하지 않습니다.
content.status integer 0 활성화, 2 비활성화이며, 삭제되지 않은 읽기에는 다른 이력 상태가 포함될 수 있습니다.
content.creator string 생성 주체입니다.
content.updator string 업데이트 주체입니다.
content.createAt integer 생성 Unix 초입니다.
content.updateAt integer 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1일 수 있습니다.
content.deleteAt integer 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다.
content.uploadData string SAML에 저장된 전체 IdP metadata XML이며 OIDC는 일반적으로 빈 문자열입니다.
content.config object 저장 후 전체 구성입니다. OIDC 쓰기 응답에는 여전히 저장 암호문이 포함되며 get의 Base64 별표 마스크가 아니므로 직접 인증하거나 다시 채우는 데 사용할 수 없습니다.
content.config.modeType string 선택 사항: easy/expert, 기본값 easy. 이 필드는 주로 편집 모드를 보존하며, 임의의 전문가 구성을 실행 가능한 것으로 자동 검증하지 않습니다.
content.config.wellKnowURL string 선택적 HTTP(S) 디스커버리 주소입니다. 제공하면 저장 단계에서 실제 GET 후 JSON을 파싱합니다(오프라인 검증 아님). 요청 실패/SSL/HTTP 오류는 이 페이지의 오류로 처리됩니다. 생략하려면 auth/token/userinfo 세 엔드포인트를 명시해야 하며, modeType=expert만 작성해서는 안 됩니다.
content.config.sslVerify boolean 디스커버리 요청 TLS 검증 스위치입니다. 저장 단계 기본값 true이며, 런타임 SDK는 HTTPS 기본 true, HTTP 기본 false로 동작합니다. 각 엔드포인트의 verify를 통합 대체하는 스위치로 간주하지 않습니다.
content.config.clientId string OIDC 필수 비어 있지 않은 문자열이며 앞뒤 공백이 없어야 합니다. IdP 클라이언트 등록에서 가져오며 Studio API Key가 아닙니다.
content.config.clientSecret string OIDC 쓰기 응답은 서버 저장 암호문이므로 Base64 평문/마스크로 다시 전달할 수 없습니다. secret을 유지하려면 먼저 get을 호출해 마스크를 가져옵니다.
content.config.grantType string 선택 사항 authorization_code/code, 생략 시 런타임 기본값 authorization_code입니다. client_credentials 또는 password 권한 부여가 아닙니다.
content.config.scope array 선택적 문자열 배열입니다. 런타임 SDK 기본값은 [openid]만이며, 이전 설명의 openid/profile/email이 아닙니다. IdP가 계정에 필요한 email 등 클레임을 실제로 제공하는지 확인하십시오. 빈 배열은 빈 scope를 생성하므로 클라이언트가 합리적으로 명시 구성해야 합니다.
content.config.scope[] string IdP가 허용하는 단일 scope이며, 이 워크스페이스의 권한 포인트가 아닙니다.
content.config.authSet json 인가 리다이렉트 파라미터 객체이며, 생략 시 디스커버리 문서에서 주소를 채울 수 있습니다.
content.config.getTokenSet json code를 token으로 교환하는 요청 객체이며, 생략 시 엔드포인트를 디스커버리 문서에서 가져옵니다.
content.config.verifyTokenSet json id_token 서명 검증 JWK 객체이며, 구성을 저장하기 위해 즉시 token 인증을 시작하는 것이 아닙니다.
content.config.getUserInfoSet json 사용자 정보 소스/요청 객체이며, 기본값 origin으로 이전 설명의 기본 id_token이 아닙니다.
content.config.claimMapping json 계정 필드에서 IdP 실제 속성명으로의 매핑이며 역할 매핑 규칙이 아닙니다. OIDC 저장은 항목별 엄격 검증이 없으므로 실제 콜백을 테스트해야 합니다. SAML 비어 있지 않은 매핑은 비어 있지 않은 username/email을 함께 제공해야 하며 mobile은 선택적 문자열입니다. 빈 객체는 기존 기본값과 호환됩니다.
content.config.authSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 authorization_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
content.config.authSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
content.config.authSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
content.config.getTokenSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 token_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
content.config.getTokenSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
content.config.getTokenSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
content.config.getTokenSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
content.config.verifyTokenSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 jwks_uri를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
content.config.verifyTokenSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
content.config.getUserInfoSet.url string 선택적 명시적 HTTP(S) URL이며, 제공하지 않으면 디스커버리 문서의 userinfo_endpoint를 사용하고 값이 있으면 런타임 엔드포인트를 덮어씁니다. 디스커버리 문서가 없으면 auth/token/userinfo 세 가지가 필수이며, 서명 검증 소스는 별도로 JWK 사용 가능성을 보장해야 합니다.
content.config.getUserInfoSet.verify boolean 선택 사항이며, 이 엔드포인트는 HTTPS 기본 true, HTTP 기본 false입니다. 각각 구성하며 sslVerify가 통합 대체하지 않습니다.
content.config.getUserInfoSet.paramMapping json 선택적 비표준 요청 파라미터 매핑입니다. 비어 있지 않으면 해당 기본 파라미터 집합을 대체하며 필수 항목을 완전히 유지해야 합니다. 키는 IdP 파라미터명이고 값은 이 페이지에서 허용된 $변수 또는 고정 문자열일 수 있습니다. clientSecret을 인가 리다이렉트 URL에 매핑하지 마십시오.
content.config.getUserInfoSet.paramMapping.目标参数名 string 동적 IdP 파라미터 값입니다. 허용되는 변수 범위는 단계에 따라 다르며 아래 표를 참조하십시오. 알 수 없는 문자열은 상수로 유지되며 임의의 내부 컨텍스트를 자동으로 가져오지 않습니다.
content.config.getTokenSet.method string 선택 사항 get/post, 기본값 post, 런타임은 이 두 가지만 지원합니다. 저장 시 이 열거형을 강제하지 않으며 다른 값은 이후 로그인 시 오류가 발생합니다.
content.config.getTokenSet.authMethod string 선택 사항 basic/client_secret_basic(기본 Basic 헤더), client_secret_post(기본 폼에 ID와 secret 포함), none(기본적으로 client_id만 사용하며 secret을 자동 포함하지 않음). 사용자 정의 paramMapping이 있으면 전체 매핑에 따라 파라미터를 생성하며, Basic 헤더는 여전히 선택한 인증 방식을 따릅니다.
content.config.getUserInfoSet.method string 기본값 get입니다. 현재 SDK의 비-get 분기는 여전히 GET을 보내지만 파라미터를 Body에 넣으므로 진정한 POST가 아닙니다. POST가 필요한 IdP는 저장 성공만으로 지원된다고 판단해서는 안 되며, 검증된 GET 엔드포인트 사용을 권장합니다.
content.config.getUserInfoSet.authMethod string 기본값 bearer 헤더, client_secret_basic은 Basic 헤더 사용, none은 기본적으로 access_token을 파라미터에 넣습니다. basic 별칭 또는 기타 임의 값을 동일하게 유효한 것으로 간주하지 않습니다.
content.config.getUserInfoSet.source string origin은 userinfo 호출(기본값), id_token은 id_token 검증 및 읽기, merge는 먼저 id_token 후 userinfo로 동일 키를 덮어씁니다. 저장 시 열거형을 강제하지 않으므로 다른 값은 최종적으로 사용자 정보가 없을 수 있습니다.
content.config.getUserInfoSet.responseInfoPath string 선택적 응답 내 사용자 객체의 점 경로이며 origin 결과에서만 추출합니다. 빈 문자열은 전체 응답을 사용하며 claimMapping의 속성명과 다릅니다.
content.config.verifyTokenSet.keys array 선택적 IdP 공개 JWK 배열입니다. 비어 있지 않으면 직접 서명 검증에 사용하고, 그렇지 않으면 런타임에 verifyTokenSet.url을 GET하여 keys를 가져옵니다. 개인 키가 아니며 예시 자리 표시자 자료를 실제 서명 검증 구성으로 간주하지 마십시오.
content.config.verifyTokenSet.keys[] json 단일 공개 JWK이며 IdP가 게시한 kty/alg/kid 및 공개 키 파라미터에 따라 전체 구조를 유지합니다.
content.config.verifyTokenSet.keys[].kty string 공개 키 유형(예: RSA/EC)이며 IdP JWK를 기준으로 합니다.
content.config.verifyTokenSet.keys[].kid string 공개 키 선택에 사용되는 식별자입니다.
content.config.verifyTokenSet.keys[].use string 키 용도입니다.
content.config.verifyTokenSet.keys[].alg string 서명 검증 알고리즘 식별자입니다.
content.config.verifyTokenSet.keys[].n string RSA 모듈러스 Base64url입니다.
content.config.verifyTokenSet.keys[].e string RSA 공개 지수 Base64url입니다.
content.config.verifyTokenSet.keys[].crv string EC 곡선이며 해당 유형에만 적용됩니다.
content.config.verifyTokenSet.keys[].x string EC 공개 x 좌표입니다.
content.config.verifyTokenSet.keys[].y string EC 공개 y 좌표입니다.
content.config.verifyTokenSet.keys[].x5c array 공개 인증서 체인 Base64 DER 배열, 선택 사항입니다.
content.config.verifyTokenSet.keys[].x5c[] string 단일 공개 인증서이며 개인 키를 포함하지 않습니다.
content.config.verifyTokenSet.keys[].其他公开字段 JSON IdP JWK 확장은 라이브러리 프로토콜에 따라 보존하며 d/p/q 등 개인 키 자료를 추가하지 않습니다.
content.config.claimMapping.username string OIDC 기본값 preferred_username, SAML 기본값 username. SAML에서 명시적 비어 있지 않은 claimMapping일 때 비어 있지 않은 문자열이 필수입니다.
content.config.claimMapping.email string 기본값 email이며 실제 로그인 시 유효한 이메일을 반드시 얻어야 합니다. SAML에서 명시적 비어 있지 않은 claimMapping일 때 필수이며, OIDC 저장은 값/소스를 검증하지 않지만 콜백에서는 여전히 이메일을 요구합니다.
content.config.claimMapping.name string OIDC 선택적 표시 이름 속성, 기본값 name. SAML은 현재 name을 고정으로 읽으며 이 매핑 키는 표시 이름 추출을 변경하지 않습니다.
content.config.claimMapping.mobile string OIDC 기본값 phone_number, SAML 기본값 mobile, 명시적 빈 문자열은 추출하지 않습니다. 번호가 없으면 보충하지 않으며, 기존 휴대폰 번호와 국가 코드는 유지하고 원래 계정에 번호가 없고 IdP 번호가 유효할 때만 보충합니다.
content.config.authSet.verify boolean 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
content.config.verifyTokenSet.method string 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
content.config.verifyTokenSet.authMethod string 기존 데이터 호환을 위해 저장할 수 있지만 현재 OIDC SDK는 이 키를 사용하지 않으므로 이를 근거로 요청/TLS를 제어할 수 없습니다. 이 페이지에서 실제로 읽는 해당 필드를 사용하십시오.
content.loginURL string 해당 공급자의 로그인 진입점이며 배포 사이트에서 반환합니다. DF-API-KEY로 액세스하는 현재 OpenAPI 경로가 아닙니다.
content.callbackURL string OIDC 콜백 URL만 해당하며 IdP의 허용 콜백 목록에 등록해야 합니다.
content.metadataURL string SAML SP metadata 주소만 해당합니다.
content.entiryID string SAML SP entity ID만 해당합니다. 프로토콜의 실제 철자인 entiryID를 유지하며 entityID로 변경하지 않습니다.
content.assertionURL string SAML ACS/assertion 콜백 주소만 해당하며 실제 반환값에 따라 등록합니다.
content.declaration object 외부 공통 선언입니다.
{
  "code": 200,
  "content": {
    "id": 1,
    "uuid": "sso_example",
    "type": "oidc",
    "workspaceUUID": "wksp_example",
    "idpName": "ExampleIdP",
    "remark": "企业登录",
    "role": "general",
    "idpMd5": "IDP-IDENTITY-HASH",
    "tokenHoldTime": 604800,
    "tokenMaxValidDuration": 2592000,
    "isOpenSAMLMapping": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427200,
    "deleteAt": -1,
    "config": {
      "modeType": "expert",
      "clientId": "client_example",
      "clientSecret": "STORED-CIPHERTEXT-PLACEHOLDER",
      "scope": [
        "openid",
        "profile",
        "email"
      ],
      "grantType": "authorization_code",
      "authSet": {
        "url": "https://idp.example.com/authorize"
      },
      "getTokenSet": {
        "url": "https://idp.example.com/token",
        "method": "post",
        "authMethod": "client_secret_basic"
      },
      "verifyTokenSet": {
        "url": "https://idp.example.com/jwks"
      },
      "getUserInfoSet": {
        "url": "https://idp.example.com/userinfo",
        "method": "get",
        "authMethod": "bearer",
        "source": "origin"
      },
      "claimMapping": {
        "username": "preferred_username",
        "email": "email",
        "mobile": "phone_number"
      }
    },
    "uploadData": "",
    "loginURL": "https://sso.example.com/oidc/login/sso_example",
    "callbackURL": "https://sso.example.com/oidc/callback/sso_example",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

SAML 요청 예시: 먼저 <IdP_METADATA_XML>을 관리자가 제공한 전체 유효 XML로 바꿉니다(이 자리 표시자 텍스트를 그대로 저장할 수 없음). 수정 대상은 원래 SAML이어야 합니다.

curl --request POST '<Endpoint>/api/v1/sso/sso_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"emailDomains":["example.com"],"idpName":"ExampleSAML","role":"general","remark":"SAML登录","idpData":"<IdP_METADATA_XML>","config":{"claimMapping":{"username":"uid","email":"mail","mobile":"telephone"}},"needNotify":false}'

OIDC 구성 성공 응답 예시(secret은 저장 암호문 자리 표시자이며 다시 전달할 수 없음):

{
  "code": 200,
  "content": {
    "id": 1,
    "uuid": "sso_example",
    "type": "oidc",
    "workspaceUUID": "wksp_example",
    "idpName": "ExampleIdP",
    "remark": "企业登录",
    "role": "general",
    "idpMd5": "IDP-IDENTITY-HASH",
    "tokenHoldTime": 604800,
    "tokenMaxValidDuration": 2592000,
    "isOpenSAMLMapping": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427200,
    "deleteAt": -1,
    "config": {
      "modeType": "expert",
      "clientId": "client_example",
      "clientSecret": "STORED-CIPHERTEXT-PLACEHOLDER",
      "scope": [
        "openid",
        "profile",
        "email"
      ],
      "grantType": "authorization_code",
      "authSet": {
        "url": "https://idp.example.com/authorize"
      },
      "getTokenSet": {
        "url": "https://idp.example.com/token",
        "method": "post",
        "authMethod": "client_secret_basic"
      },
      "verifyTokenSet": {
        "url": "https://idp.example.com/jwks"
      },
      "getUserInfoSet": {
        "url": "https://idp.example.com/userinfo",
        "method": "get",
        "authMethod": "bearer",
        "source": "origin"
      },
      "claimMapping": {
        "username": "preferred_username",
        "email": "email",
        "mobile": "phone_number"
      }
    },
    "uploadData": "",
    "loginURL": "https://sso.example.com/oidc/login/sso_example",
    "callbackURL": "https://sso.example.com/oidc/callback/sso_example",
    "declaration": {}
  },
  "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 객체가 아님 일부 json 파일 형식 오류 이 페이지 필드를 포함한 전체 객체를 제출합니다.
406 ft.ParameterValidationFailed SAML claimMapping 구조가 유효하지 않거나 클레임 필드 유형/열거형/범위가 일치하지 않음 파라미터 파싱 실패 비어 있지 않은 SAML 매핑에는 비어 있지 않은 username/email을 함께 제공하고 mobile은 문자열이어야 합니다. 공개 파라미터 표에 따라 수정합니다.
400 ft.InvalidSsoRoleCfg 기본 역할이 owner/wsAdmin임 관리자, 소유자 역할 구성은 지원되지 않음 general/readOnly 또는 이 워크스페이스의 활성 사용자 정의 역할을 사용합니다.
400 ft.InvalidCustomRole 기본 사용자 정의 역할이 존재하지 않거나 비활성화/삭제되었거나 현재 워크스페이스 표시 범위에 없음 유효하지 않은 사용자 정의 역할 현재 워크스페이스 역할 목록에서 유효한 역할을 가져오며 표시 이름을 사용하지 않습니다.
406 ft.InvalidSAML SAML에 유효한 XML이 없거나 metadata에 엔터티/서비스/키 설명이 없거나, 비어 있지 않은 config 수정 시 유효한 idpData를 다시 채우지 않음 유효하지 않은 saml 구성 IdP에서 실제 전체 metadata XML을 다운로드하고, 필드 매핑 업데이트 시 기존 유효 XML도 함께 다시 채웁니다.
400 ft.SsoModeTypeInvalid OIDC modeType이 easy/expert가 아님 modeType 파라미터가 유효하지 않음 이 페이지의 열거형에 따라 선택합니다.
400 ft.SsoClientIdInvalid clientId가 비어 있거나 문자열이 아니거나 앞뒤 공백이 있음 clientId 파라미터가 유효하지 않음 IdP가 할당한 원래 클라이언트 ID를 사용합니다.
400 ft.SsoClientSecretInvalid clientSecret이 유효한 Base64 UTF-8이 아니거나, 생성 시 디코딩 후 비어 있거나 모두 별표이거나, 비어 있지 않은 config 내에 유효한 clientSecret 문자열이 없음 clientSecret 파라미터가 유효하지 않음 생성 시 실제 secret을 인코딩해 사용하고, 수정 시 기존 값을 유지하려면 get에서 반환된 Base64 별표 마스크를 사용하며 저장 암호문을 다시 전달하지 않습니다.
400 ft.SsoSSLVerifyInvalid 저장 시 디스커버리 문서 요청의 SSL 검증 실패 SSL 검증 예외: {} 인증서 체인/도메인과 신뢰를 확인하고 조직 정책에 따라 sslVerify를 구성합니다.
400 ft.SsoWellKnowURLInvalid wellKnowURL이 유효한 HTTP(S) 주소가 아니거나 디스커버리 요청 HTTP>=400 ID 공급자 URL(wellKnowURL) 파라미터가 유효하지 않음 공식 디스커버리 주소와 서비스 응답을 확인하며 로그인 페이지 URL로 대체하지 않습니다.
400 ft.SsoVerifyWellKnowURLInvalid 디스커버리 요청 연결/JSON 파싱 등 실패 ID 공급자 URL(wellKnowURL) 파라미터 검증 실패, err:{} 주소, 네트워크 및 JSON 응답을 확인하고 traceId를 보존하며 동일한 잘못된 구성을 반복 제출하지 않습니다.
400 ft.SsoAuthSetInvalid 명시적 authSet.url이 유효한 HTTP(S) 주소가 아님 {} 파라미터가 유효하지 않음 공식 authorization_endpoint를 사용합니다.
400 ft.SsoTokenEndPointInvalid 명시적 getTokenSet.url이 유효하지 않음 {} 파라미터가 유효하지 않음 공식 token_endpoint를 사용합니다.
400 ft.SsoVerifyTokenSetInvalid 명시적 verifyTokenSet.url이 유효하지 않음 {} 파라미터가 유효하지 않음 공식 JWKS 주소를 사용합니다.
400 ft.SsoUserInfoEndPointInvalid 명시적 getUserInfoSet.url이 유효하지 않음 {} 파라미터가 유효하지 않음 공식 userinfo_endpoint를 사용합니다.
400 ft.SsoOIDCUrlsInvalid wellKnowURL이 없고 auth/token/userinfo 세 엔드포인트가 완전하지 않음 url 파라미터가 유효하지 않음 세 공식 주소를 모두 채웁니다. 저장이 전체 프로토콜 검증을 의미하지는 않습니다.
400 ft.SsoGrantTypeInvalid grantType이 authorization_code/code가 아님 grantType이 유효하지 않음. 현재 code, authorization_code만 지원 지원되는 권한 부여 방식으로 변경합니다.
400 ft.SSOEsistsSameSupplier 동일 워크스페이스의 삭제되지 않은 공급자 이름이 중복됨(수정 시 자신 제외) 동일한 이름의 공급자가 이미 존재함 기존 UUID로 수정하거나 고유한 이름을 선택합니다.
400 ft.SSOEsistsSameIdp 동일 워크스페이스의 삭제되지 않은 구성이 동일한 IdP ID 다이제스트를 가짐(수정 시 자신 제외) 동일한 메타데이터 파일 구성이 이미 존재함 기존 공급자를 확인하고 표시 이름만 바꿔 동일 ID를 중복 생성하지 않습니다.
500 ft.InternalServerError 동적 config/이메일 요소 형상, 저장 또는 복호화/암호화, 멤버 연결 정리 또는 커밋 후 캐시 작업에서 처리되지 않은 예외 발생 내부 오류 먼저 get/list로 구성/허용 목록/멤버 관계를 확인합니다. 이미 커밋되었을 수 있으므로 traceId를 보존하고 실패 단계에 따라 처리하며 무작정 재생성하지 않습니다.
406 ft.NotFoundSAML UUID가 현재 워크스페이스의 삭제되지 않은 SSO 구성에 속하지 않음 sso 구성을 찾을 수 없음 SSO 목록에서 sso_ UUID를 다시 가져오며 fdmp_ 매핑 또는 idpMd5를 사용하지 않습니다.
400 ft.InvalidActionForbiddenRemovalOwner ID 변경으로 트리거된 멤버 정리 대상에 이 워크스페이스 Owner가 포함됨 유효하지 않은 작업, 소유자를 제거할 수 없음 먼저 연결된 계정과 예비 관리자 진입점을 확인하며, 실패를 구성/멤버 모두 변경되지 않은 것으로 간주하지 않습니다.
400 ft.AgentMemberCanNotDelete ID 변경으로 공유 멤버 정리가 트리거되어 삭제할 수 없는 에이전트 멤버에 해당 agent 소스 멤버는 삭제할 수 없음 네임스페이스 대상을 확인하고 관리자에게 기존 연결 처리를 요청하며 정리를 무작정 재시도하지 않습니다.

문서 평가

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