콘텐츠로 이동

SSO 구성 생성(이전 호환 인터페이스)



POST /api/v1/sso/saml_create

개요

워크스페이스 SAML 또는 OIDC ID 공급자를 생성합니다.

호출 전 및 사용 단계

이것은 이전 주소 호환 인터페이스이며 현재 소스 코드에 여전히 실제 등록되어 있습니다. 과거 “2026-05-31 지원 종료” 주석은 현재 요청이 금지되었음을 의미하지 않습니다. 신규 연동에는 SSO 구성 생성을 우선 사용하십시오. 이전 경로는 동일한 컨트롤러/요청 필드/응답을 사용하며, saml 접두사 때문에 OIDC가 제외되지는 않습니다.

생성 전에 IdP에서 Guance용 클라이언트/애플리케이션을 등록하고, 공식 엔드포인트와 이 워크스페이스의 기본 역할을 확인하십시오. SAML은 실제 전체 metadata XML을 제출하고, OIDC는 Base64로 인코딩된 clientSecret 및 전체 구성을 제출합니다. 기본적으로 status=0 및 isOpenSAMLMapping=0으로 생성되며, 성공 후 공급자는 즉시 로그인 검색에 사용할 수 있게 될 수 있습니다. 이 Body에서는 활성화/비활성화 필드를 전달하지 않습니다. 역할 매핑으로 액세스를 제어하려면 매핑을 별도로 구성하고 활성화해야 합니다.

생성/수정은 전체 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에서만 보존에 사용할 수 있는 별표 마스크가 반환됩니다.

요청 헤더

매개변수명 유형 필수 설명
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
획득 또는 입력 방법: 조직의 로그인 세션 최대 수명에 따라 초를 선택합니다.
type string Y 생성 시 필수입니다. 수정 시 유형은 기존 구성을 따르며 type을 받아 프로토콜을 변경하지 않습니다.
null 허용: False
선택 가능한 값: ['saml', 'oidc']
예: oidc
획득 또는 입력 방법: ID 공급자 프로토콜에 따라 saml 또는 oidc를 선택합니다.

매개변수 추가 설명

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/saml_create' \
  -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":"U0VDUkVULVBMQUNFSE9MREVS","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,"type":"oidc"}'

응답

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.emails array<string> 생성 후 중복 제거된 허용 목록 값 배열입니다.
content.emails[] string 전체 이메일 또는 도메인 값입니다.
content.declaration object 외부 공통 선언입니다.
{
  "code": 200,
  "content": {
    "id": null,
    "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": {},
    "emails": [
      "example.com"
    ]
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

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

curl --request POST '<Endpoint>/api/v1/sso/saml_create' \
  -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,"type":"saml"}'

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

{
  "code": 200,
  "content": {
    "id": null,
    "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": {},
    "emails": [
      "example.com"
    ]
  },
  "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.InvalidOIDC OIDC 생성에 비어 있지 않은 config가 없음 유효하지 않은 OIDC 구성 전체 클라이언트 및 엔드포인트 구성을 제출하십시오.
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를 보존하고 실패 단계에 따라 처리하며 무작정 재생성하지 마십시오.
400 ft.SSOCfgExceedQuantityLimit 추가 후 해당 프로토콜 구성 수가 사이트 상한을 초과함(비활성화되었지만 삭제되지 않은 것도 포함) SSO 구성 수가 제한을 초과함 SSO 목록에서 수량과 삭제 가능한 이력 구성을 확인하십시오. 사이트 기본값은 유형당 10이며 실제로는 상한 구성이 기준입니다.

문서 평가

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