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이며 실제로는 상한 구성이 기준입니다. |