콘텐츠로 이동

SSO 구성 가져오기



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

개요

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

호출 전 및 사용 단계

현재 워크스페이스의 삭제되지 않은 구성만 읽으며, 비활성화 상태도 조회할 수 있습니다. 이 요청은 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/sso_example/get' \
  -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를 보관하고 현재 구성과 서비스 종속성을 확인하십시오. 읽기는 구성 업데이트를 수행하지 않으며, 해당 실패를 제공자가 존재하지 않는 것으로 간주하지 마십시오.

문서 평가

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