콘텐츠로 이동

SSO 구성 생성



POST /api/v1/sso/create

개요

워크스페이스 SAML 또는 OIDC IdP를 생성합니다.

호출 전 및 사용 단계

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

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

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/sso/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가 아닙니다.
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/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 IdP URL(wellKnowURL) 파라미터가 유효하지 않음 공식 검색 주소 및 서비스 응답을 확인하고 로그인 페이지 URL로 대체하지 않습니다.
400 ft.SsoVerifyWellKnowURLInvalid 검색 요청 연결/JSON 파싱 등 실패 IdP 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 아이덴티티 다이제스트를 가짐(수정 시 자기 자신 제외) 동일한 메타파일 구성이 이미 존재함 기존 공급자를 확인하고 표시 이름만 바꿔 동일 아이덴티티를 중복 생성하지 않습니다.
500 ft.InternalServerError 동적 config/이메일 요소 형상, 저장 또는 복호화/암호화, 멤버 연결 정리 또는 제출 후 캐시 작업에서 처리되지 않은 예외 발생 내부 오류 먼저 get/list로 구성/허용 목록/멤버 관계를 확인하십시오. 이미 커밋되었을 수 있습니다. traceId를 보존하고 실패 단계에 따라 처리하며 무작정 재생성하지 마십시오.
400 ft.SSOCfgExceedQuantityLimit 추가 후 해당 프로토콜 구성 수가 사이트 상한을 초과함(비활성화되었지만 삭제되지 않은 구성도 포함) SSO 구성 수량이 제한을 초과함 SSO 목록에서 수량 및 삭제 가능한 이력 구성을 확인하십시오. 사이트 기본값은 유형당 10이며 실제로는 상한 구성이 기준입니다.

문서 평가

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