콘텐츠로 이동

SSO 구성 조회(레거시 호환 인터페이스)



GET /api/v1/sso/saml_get/{sso_uuid}

개요

단일 SSO 구성, 이메일 허용 목록 및 로그인/콜백 주소를 읽습니다.

호출 전 및 사용 단계

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

현재 워크스페이스의 삭제되지 않은 구성만 조회하며, 비활성화 상태도 조회할 수 있습니다. 이 요청은 IdP에 연결하여 로그인을 검증하지 않습니다. OIDC secret 복호화는 동일한 길이의 별표를 생성한 뒤 Base64로 인코딩하여 반환하는 데에만 사용됩니다. 이 값을 IdP 인증에 사용할 수 없습니다. get 마스크를 create/modify에서 반환되는 저장 암호문과 혼동하지 마십시오. 비어 있지 않은 config를 수정할 때 기존 secret을 유지하려면 이 get의 Base64 별표 마스크를 그대로 다시 전달할 수 있습니다.

SAML은 업로드된 전체 XML과 SP 주소를 반환하고, OIDC는 로그인 및 콜백 주소를 반환합니다. 현재 사이트에서 반환된 URL로 IdP에 등록하며, 주소를 임의로 조합하지 마십시오. config 필드에는 과거의 추가 데이터가 있을 수 있으므로, 수정 시에는 이 페이지의 쓰기 계약에서 지원하는 전체 구성만 제출해야 하며, get 응답 전체를 그대로 Body로 사용해서는 안 됩니다. 이메일 허용 목록의 반환 키 이름은 emails이며, 쓰기 요청에서는 emailDomains를 사용합니다. 필드 매핑은 역할 매핑 규칙과 용도가 다릅니다.

라우트 파라미터

파라미터 이름 유형 필수 설명
sso_uuid string Y 공급자 UUID이며, 매핑 UUID, IdP 다이제스트 또는 클라이언트 ID가 아닙니다.
예: sso_example
가져오기 또는 입력 방법: SSO 목록의 content[].uuid에서 현재 워크스페이스 구성을 가져옵니다.

요청 헤더

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

파라미터 추가 설명

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 --get 'https://openapi.guance.com/api/v1/sso/saml_get/sso_example' \
  -H 'DF-API-KEY: <DF-API-KEY>'

응답

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 XML이며, OIDC에서는 일반적으로 빈 문자열입니다.
content.config object 저장된 구성입니다. OIDC clientSecret은 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 길이의 별표를 나타냅니다. 기존 secret을 유지하려면 수정 시 그대로 다시 전달할 수 있으며, 디코딩하여 실제 secret으로 사용할 수 없습니다. SAML에는 일반적으로 이 필드가 없습니다.
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.emails array<string> 현재 삭제되지 않은 이메일/도메인 허용 목록 값이며, 허용 목록 엔터티를 반환하지 않습니다.
content.emails[] string 단일 전체 이메일 또는 도메인 식별자입니다.
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,
    "uploadData": "",
    "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"
      }
    },
    "emails": [
      "example.com"
    ],
    "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.NotFoundSAML UUID가 현재 워크스페이스의 삭제되지 않은 SSO 구성에 속하지 않음 sso 구성을 찾을 수 없음 SSO 목록에서 sso_ UUID를 다시 가져오며, fdmp_ 매핑이나 idpMd5를 사용하지 않습니다.
500 ft.InternalServerError 구성/데이터베이스/키 복호화, XML 도구 또는 관련 자료 포맷팅 중 처리되지 않은 예외 발생 내부 오류 traceId를 보존하고 현재 구성과 서비스 의존성을 확인하십시오. 읽기는 구성 업데이트를 수행하지 않으며, 해당 실패를 공급자가 존재하지 않는 것으로 간주하지 마십시오.

문서 평가

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