콘텐츠로 이동

SSO 구성 업데이트(이전 호환 인터페이스)



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

개요

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

호출 전 및 사용 단계

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

먼저 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의 non-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 필수 배열이며 []일 수 있고 서버 세트에서 중복을 제거합니다. 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/saml_modify/sso_example' \
  -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의 non-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/saml_modify/sso_example' \
  -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 출처 멤버는 삭제할 수 없음 네임스페이스 대상을 확인하고 관리자에게 문의하여 기존 연결을 처리하세요. 정리를 무작정 재시도하지 마세요.

문서 평가

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