SSO 설정 생성¶
POST /api/v1/sso/saml_create
개요¶
SSO 활성화
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| type | string | Y | 유형 예시: 빈 값 허용: False 선택 값: ['saml', 'oidc'] |
| idpData | string | XML 문서 내용(saml 유형 필수) 예시: 빈 값 허용: False |
|
| config | json | 접근 구성표(oidc 유형 필수, clientSecret은 백엔드로 전달 시 base64로 인코딩 필요) 예시: 빈 값 허용: False |
|
| emailDomains | array | Y | 이메일 도메인 예시: ['guance.com'] |
| idpName | string | Y | 공급업체 예시: 기본 공급업체 최대 길이: 64 $matchRegExp: [a-zA-Z_一-龥-]* |
| role | string | Y | 역할 UUID, general, readOnly 및 사용자 정의 역할 지원 빈 값 허용: False 빈 문자열 허용: False |
| remark | string | 비고 빈 값 허용: False 빈 문자열 허용: True |
|
| tokenHoldTime | integer | 비활성 세션 유지 시간(초 단위, 기본값 7일, 604800초) 예시: 604800 빈 값 허용: False $minValue: 60 $maxValue: 604800 |
|
| tokenMaxValidDuration | integer | 로그인 세션 최대 유지 시간(초 단위, 기본값 30일, 604800초) 예시: 2592000 빈 값 허용: False $minValue: 60 $maxValue: 2592000 |
|
| needNotify | boolean | SSO 구성 변경 이메일 알림 전송 여부, 기본값 true; false 전송 시 이메일 알림만 억제, 구성 변경 및 감사 기록에는 영향 없음 예시: True 빈 값 허용: False |
파라미터 추가 설명¶
OIDC 유형 config 구성 설명
type='oidc'인 경우 config 필드가 적용됩니다. 데이터 구조 정보는 다음과 같습니다.
1. config 필드 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| modeType | enum | easy | 구성 파일 편집 모드. 선택 값: easy: 간편 UI 편집 모드. 이 모드에서는 사용자가 OIDC 상호작용 프로토콜에 필요한 기본 데이터만 구성하면 되며, 다른 데이터는 기본값을 사용합니다. expert: 전문가 구성 파일 모드. 사용자가 OIDC 구성 파일을 업로드해야 합니다. 이 모드는 사용자가 OIDC 프로토콜의 다양한 요청 정보를 사용자 정의할 수 있도록 지원합니다. |
|
| wellKnowURL | string | Y | OIDC 프로토콜의 표준 서비스 디스커버리 주소. 예: Microsoft AAD |
|
| clientId | string | Y | "인증 서비스"가 "Guance"을 위해 생성한 클라이언트 ID | |
| clientSecret | string | Y | "인증 서비스"가 "Guance"을 위해 생성한 클라이언트에 해당하는 시크릿 | |
| sslVerify | boolean | 서비스 디스커버리 구성 정보 요청 시 SSL 인증을 강제할지 여부; 기본값은 wellKnowURL 파라미터 값의 프로토콜 주소에 따라 구분되며, https인 경우 기본값은 true, 그렇지 않으면 기본값은 false입니다. |
||
| grantType | string | Y | authorization_code | "인증 서비스"가 "Guance"을 위해 생성한 클라이언트의 권한 부여 유형 |
| scope | array | Y | ["openid", "email"] | 액세스 가능한 데이터 권한 필수 값: openid 기타 선택 값: profile, email 등 이 값은 "인증 서비스"가 "Guance"에 할당한 scope에 따라 결정됩니다. |
| authSet | dict | OIDC 프로토콜의 인증 요청 주소 획득을 위한 구성입니다. 프로토콜 출처 |
||
| getTokenSet | dict | OIDC 프로토콜의 code를 token으로 교환하는 요청을 위한 구성입니다. 프로토콜 출처 |
||
| verifyTokenSet | dict | id_token 검증 구성입니다. 프로토콜 출처, jwks_urls 데이터 구조 프로토콜 출처 |
||
| getUserInfoSet | dict | OIDC 프로토콜의 사용자 정보 요청 획득을 위한 구성입니다. 프로토콜 출처 |
||
| claimMapping | dict | 사용자 정보/id_token의 필드 매핑 구성입니다. "Guance"이 이 매핑 구성을 사용하여 계정에서 해당 정보를 가져오는 데 사용됩니다. |
2. config.authSet 내부 구조 파라미터 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| url | string | 인증 요청 주소. 제공되지 않은 경우 기본적으로 wellKnowURL이 가리키는 구성의 authorization_endpoint 값을 사용합니다. |
||
| verify | boolean | 해당 요청에 대해 SSL 검증을 활성화할지 여부; 지정되지 않은 경우 url이 https 프로토콜을 사용하면 기본적으로 활성화되고, 그렇지 않으면 비활성화됩니다. | ||
| paramMapping | dict | 요청 파라미터 필드의 매핑입니다. 일반적으로 비표준 OIDC 고객이 자체 인증 흐름에 따라 관련 파라미터 필드를 조정하는 데 사용됩니다. 자세한 내용은 아래 설명을 참조하세요. |
3. config.getTokenSet 내부 구조 파라미터 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| url | string | code를 token으로 교환하는 요청 주소. 제공되지 않은 경우 기본적으로 wellKnowURL이 가리키는 구성의 token_endpoint 값을 사용합니다. |
||
| method | enum | post | 요청 메서드, 선택 값: post, get | |
| verify | boolean | 해당 요청에 대해 SSL 검증을 활성화할지 여부; 지정되지 않은 경우 url이 https 프로토콜을 사용하면 기본적으로 활성화되고, 그렇지 않으면 비활성화됩니다. | ||
| authMethod | enum | basic | 서명 데이터 위치 및 방법. 선택 값: client_secret_basic 또는 basic: 인증 정보는 요청 헤더의 Authorization에 있으며, basic 인증입니다. client_secret_post: client_id와 client_secret이 body에 있습니다. none: client_id와 client_secret이 query에 있습니다. |
|
| paramMapping | dict | 요청 파라미터 필드의 매핑입니다. 일반적으로 비표준 OIDC 고객이 자체 인증 흐름에 따라 관련 파라미터 필드를 조정하는 데 사용됩니다. 자세한 내용은 아래 설명을 참조하세요. |
4. config.verifyTokenSet 내부 구조 파라미터 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| url | string | code를 token으로 교환하는 요청 주소. 제공되지 않은 경우 기본적으로 wellKnowURL이 가리키는 구성의 token_endpoint 값을 사용합니다. |
||
| verify | boolean | 해당 요청에 대해 SSL 검증을 활성화할지 여부; 지정되지 않은 경우 url이 https 프로토콜을 사용하면 기본적으로 활성화되고, 그렇지 않으면 비활성화됩니다. | ||
| keys | array | url이 가리키는 JWT 알고리즘 데이터 정보 프로토콜 출처, jwks_urls 데이터 구조 프로토콜 출처 |
5. config.getUserInfoSet 내부 구조 파라미터 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| source | enum | id_token | 사용자 정보를 가져오는 소스 방법. 선택 값: id_token: id_token에서 데이터를 파싱하여 가져옴; origin: "인증 서비스" 인터페이스를 호출하여 사용자 정보를 가져옴. |
|
| url | string | 사용자 정보를 가져오는 요청 주소. 제공되지 않은 경우 기본적으로 wellKnowURL이 가리키는 구성의 userinfo_endpoint 값을 사용합니다. source=origin인 경우 이 파라미터가 유효합니다. |
||
| verify | boolean | 해당 요청에 대해 SSL 검증을 활성화할지 여부; 지정되지 않은 경우 url이 https 프로토콜을 사용하면 기본적으로 활성화되고, 그렇지 않으면 비활성화됩니다. | ||
| method | enum | post | 요청 메서드, 선택 값: post, get; source=origin인 경우 이 파라미터가 유효합니다. |
|
| authMethod | enum | bearer | 서명 데이터 위치 및 방법. 선택 값: bearer: HTTP Bearer 인증 client_secret_basic 또는 basic: 인증 정보는 요청 헤더의 Authorization에 있으며, basic 인증입니다. client_secret_post: client_id와 client_secret이 body에 있습니다. none: client_id와 client_secret이 query에 있습니다. |
|
| paramMapping | dict | 요청 파라미터 필드의 매핑입니다. 일반적으로 비표준 OIDC 고객이 자체 인증 흐름에 따라 관련 파라미터 필드를 조정하는 데 사용됩니다. 자세한 내용은 아래 설명을 참조하세요. |
6. config.claimMapping 내부 구조 파라미터 설명
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| string | Y | 사용자 이메일 필드를 나타냅니다. | ||
| username | string | Y | preferred_username | 사용자 이름 필드를 나타냅니다. |
| mobile | string | 사용자 휴대폰 번호 |
7. getTokenSet, getTokenSet, getUserInfoSet 구성의 paramMapping 파라미터 내부 구조 설명
paramMapping이 존재하는 경우 사용자 정의 요청 파라미터 흐름을 직접 사용합니다.
| 파라미터명 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| client_id | string | $client_id | 클라이언트 ID, 프로토콜의 client_id에 해당합니다. | |
| scope | string | $scope | 데이터 범위. 공백으로 구분된 데이터 범위 문자열입니다. 참고: 이는 요청 파라미터의 scope이며, 외부 구성의 데이터 유형과 다릅니다. 외부 구성의 scope는 기본 구성으로 배열 유형입니다. 여기의 scope는 요청 파라미터로 문자열 유형입니다. 예: "openid email profile" |
|
| code | string | $code | "인증 서비스"에서 token 교환을 위해 전달된 code | |
| state | string | $state | CSRF와 유사한 역할 | |
| redirect_uri | string | $redirect_uri | 응답이 전송될 리디렉션 URI | |
| response_type | string | $response_type | 응답 유형, 인증 코드 흐름의 값은 code |
요청 예시¶
curl 'https://openapi.guance.com/api/v1/sso/saml_create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"idpData":"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?><md:EntityDescriptor entityID=\\\"http://www.okta.com/exk4snorvlVZsqus25d7\\\" xmlns:md=\\\"urn:oasis:names:tc:SAML:2.0:metadata\\\"><md:IDPSSODescriptor WantAuthnRequestsSigned=\\\"false\\\" protocolSupportEnumeration=\\\"urn:oasis:names:tc:SAML:2.0:protocol\\\"><md:KeyDescriptor use=\\\"signing\\\"><ds:KeyInfo xmlns:ds=\\\"http://www.w3.org/2000/09/xmldsig#\\\"><ds:X509Data><ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAXy+xOGoMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMTEwMjYyMjQxMjZaFw0zMTEwMjYyMjQyMjZaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG\nA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEc\nMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAKBt7aed/3A+gHtfmNSATeaaNo1LR/WPH9TIso3foT5dMXYRtlW57/YPNzBpii8+Gs/I6xL7\nkXzbRy9lnhpbBVTCLstWpuxYNr7zXuxICoSCW/b+5bYNkvKFmYd1dGkd0j7L8ZbHDKFzGkCS4a/D\nKUn6Ac/HlmML9GIOzPNyz514c6cAGd4zcpYiXFhlpzFLpElUOEedWVU4eZ48k91pPLf2guWpU/OD\nmKQisIOL5uqQqLsK1DXV+miSfB8Mm4jXSPLBE73mD7EfYidY1FQELqsrLshkXJGbhlkNnoEocCLH\nz9COzi9+jeecGvZGUw+l8hkxMsqH+0U3wM7ueVLMtgECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA\nUQrFTpRmneWUuok3L1CWgTeuwakErxB2NZtvpGkD5HrJE/eeyCEp81atOH6EU6mJamSLuFtJu5wl\nArV9c7lfFliArtg3+d0NM9mV/6E+RYn5ELDK44Qc3M1wkf4BhcQWNVUR4tiTIS3EeFVEdo1e/xqg\n2sqj7WE+6BMMae4mjmXzrQ57+a+WzWKjKQfIuVzdy2ss+8ZnOpiU+sntd1DwXKCl1jMlDYQi9NYU\nHKIqtVkLsv0ooOoXygw7t9PD8iLHBEzAsoAyON15oUIEw4mahstkOA14yERzQQyII3gilZeANebf\npkg8N9/m3HBhfHh65KpQTHh9MTU41Bcvf2KZRg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat><md:SingleSignOnService Binding=\\\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\\\" Location=\\\"https://dev-38436338.okta.com/app/dev-38436338__5/exk4snorvlVZsqus25d7/sso/saml\\\"></md:SingleSignOnService><md:SingleSignOnService Binding=\\\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\\\" Location=\\\"https://dev-38436338.okta.com/app/dev-38436338__5/exk4snorvlVZsqus25d7/sso/saml\\\"></md:SingleSignOnService></md:IDPSSODescriptor></md:EntityDescriptor>","emailDomains":["qq.com"],"role":"general","remark":"","tokenHoldTime":1800,"tokenMaxValidDuration":604800}' \
--compressed \
--insecure
응답¶
{
"code": 200,
"content": {
"assertionURL": "http://testing-ft2x-auth.cloudcare.cn/saml/assertion/sso_xxxx32",
"createAt": 1678020614,
"creator": "acnt_xxxx32",
"deleteAt": -1,
"emails": [
"qq.com"
],
"entiryID": "http://testing-ft2x-auth.cloudcare.cn/saml/metadata.xml",
"id": null,
"idpMd5": "54a3b7441fba3bdb555ae854745f576f",
"idpName": null,
"isOpenSAMLMapping": 0,
"loginURL": "http://testing-ft2x-auth.cloudcare.cn/saml/login/sso_xxxx32",
"metadataURL": "http://testing-ft2x-auth.cloudcare.cn/saml/metadata/sso_xxxx32",
"remark": "",
"role": "general",
"status": 0,
"tokenHoldTime": 1800,
"tokenMaxValidDuration": 604800,
"type": "saml-1",
"updateAt": 1678020614,
"updator": "acnt_xxxx32",
"uploadData": "<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?><md:EntityDescriptor entityID=\\\"http://www.okta.com/exk4snorvlVZsqus25d7\\\" xmlns:md=\\\"urn:oasis:names:tc:SAML:2.0:metadata\\\"><md:IDPSSODescriptor WantAuthnRequestsSigned=\\\"false\\\" protocolSupportEnumeration=\\\"urn:oasis:names:tc:SAML:2.0:protocol\\\"><md:KeyDescriptor use=\\\"signing\\\"><ds:KeyInfo xmlns:ds=\\\"http://www.w3.org/2000/09/xmldsig#\\\"><ds:X509Data><ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAXy+xOGoMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMTEwMjYyMjQxMjZaFw0zMTEwMjYyMjQyMjZaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG\nA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEc\nMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAKBt7aed/3A+gHtfmNSATeaaNo1LR/WPH9TIso3foT5dMXYRtlW57/YPNzBpii8+Gs/I6xL7\nkXzbRy9lnhpbBVTCLstWpuxYNr7zXuxICoSCW/b+5bYNkvKFmYd1dGkd0j7L8ZbHDKFzGkCS4a/D\nKUn6Ac/HlmML9GIOzPNyz514c6cAGd4zcpYiXFhlpzFLpElUOEedWVU4eZ48k91pPLf2guWpU/OD\nmKQisIOL5uqQqLsK1DXV+miSfB8Mm4jXSPLBE73mD7EfYidY1FQELqsrLshkXJGbhlkNnoEocCLH\nz9COzi9+jeecGvZGUw+l8hkxMsqH+0U3wM7ueVLMtgECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA\nUQrFTpRmneWUuok3L1CWgTeuwakErxB2NZtvpGkD5HrJE/eeyCEp81atOH6EU6mJamSLuFtJu5wl\nArV9c7lfFliArtg3+d0NM9mV/6E+RYn5ELDK44Qc3M1wkf4BhcQWNVUR4tiTIS3EeFVEdo1e/xqg\n2sqj7WE+6BMMae4mjmXzrQ57+a+WzWKjKQfIuVzdy2ss+8ZnOpiU+sntd1DwXKCl1jMlDYQi9NYU\nHKIqtVkLsv0ooOoXygw7t9PD8iLHBEzAsoAyON15oUIEw4mahstkOA14yERzQQyII3gilZeANebf\npkg8N9/m3HBhfHh65KpQTHh9MTU41Bcvf2KZRg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat><md:SingleSignOnService Binding=\\\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\\\" Location=\\\"https://dev-38436338.okta.com/app/dev-38436338__5/exk4snorvlVZsqus25d7/sso/saml\\\"></md:SingleSignOnService><md:SingleSignOnService Binding=\\\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\\\" Location=\\\"https://dev-38436338.okta.com/app/dev-38436338__5/exk4snorvlVZsqus25d7/sso/saml\\\"></md:SingleSignOnService></md:IDPSSODescriptor></md:EntityDescriptor>",
"uuid": "sso_xxxx32",
"workspaceUUID": "wksp_xxxx32"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "12755949048553864357"
}