Create SSO Configuration¶
POST /api/v1/sso/create
Overview¶
Enable an SSO.
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| type | string | Y | Type Example: Allow empty: False Allowed values: ['saml', 'oidc'] |
| idpData | string | XML document content (required for saml type) Example: Allow empty: False |
|
| config | json | Access configuration table (required for oidc type, note: clientSecret needs to be base64 encoded when passed to the backend;) Example: Allow empty: False |
|
| emailDomains | array | Y | Email domains Example: ['guance.com'] |
| idpName | string | Y | Provider Example: Default Provider Max length: 64 $matchRegExp: [a-zA-Z_一-龥-]* |
| role | string | Y | Role UUID, supports general, readOnly, and custom roles. Allow empty: False Allow empty string: False |
| remark | string | Remark Allow empty: False Allow empty string: True |
|
| tokenHoldTime | integer | Inactive session hold duration (in seconds, default 7 days, 604800 seconds) Example: 604800 Allow empty: False $minValue: 60 $maxValue: 604800 |
|
| tokenMaxValidDuration | integer | Maximum login session hold duration (in seconds, default 30 days, 604800 seconds) Example: 2592000 Allow empty: False $minValue: 60 $maxValue: 2592000 |
|
| needNotify | boolean | Whether to send SSO configuration change email notification, default true; passing false only suppresses email notification, does not affect configuration change and audit records. Example: True Allow empty: False |
Parameter Supplementary Instructions¶
OIDC Type config Configuration Instructions
When type='oidc', the config field takes effect. Its data structure information is as follows.
1. config Field Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| modeType | enum | easy | Configuration file editing mode. Allowed values are: easy: Simple UI editing mode. In this mode, users only need to configure the basic data required by the OIDC interaction protocol; other data are default values. expert: Expert configuration file mode, requiring users to upload OIDC configuration files. This mode supports users to customize various request information in the OIDC protocol. |
|
| wellKnowURL | string | Y | Standard service discovery address in the OIDC protocol. Example Microsoft AAD |
|
| clientId | string | Y | Client ID created for "Guance" by the "Authentication Service". | |
| clientSecret | string | Y | Client secret corresponding to the client created for "Guance" by the "Authentication Service". | |
| sslVerify | boolean | Whether to enforce SSL verification when requesting service discovery configuration information; Default is determined by the protocol address of the wellKnowURL parameter value: if it's https, default is true; otherwise default is false. |
||
| grantType | string | Y | authorization_code | Client ID created for "Guance" by the "Authentication Service". |
| scope | array | Y | ["openid", "email"] | Accessible data permissions Required value: openid Other optional values, e.g., profile, email This value depends on the scope assigned to "Guance" by the "Authentication Service". |
| authSet | dict | This configuration serves the authentication request address acquisition in the OIDC protocol. Protocol Source |
||
| getTokenSet | dict | This configuration serves the code-for-token exchange request in the OIDC protocol. Protocol Source |
||
| verifyTokenSet | dict | id_token verification configuration. Protocol Source, jwks_urls Data Structure Protocol Source |
||
| getUserInfoSet | dict | This configuration serves the user information acquisition request in the OIDC protocol. Protocol Source |
||
| claimMapping | dict | Field mapping configuration in user information/id_token. Used by "Guance" to obtain corresponding information in the account based on this mapping configuration. |
2. config.authSet Configuration Internal Structure Parameter Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Authentication request address. If not provided, defaults to the authorization_endpoint value from the configuration pointed to by wellKnowURL. |
||
| verify | boolean | Whether to enable SSL verification for this request; if not specified, defaults to enabled when the url uses https protocol, otherwise disabled. | ||
| paramMapping | dict | Mapping of parameter fields in the request, generally used for non-standard OIDC clients to adjust related parameter fields according to their own authentication process. Details are explained below. |
3. config.getTokenSet Configuration Internal Structure Parameter Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code for token. If not provided, defaults to the token_endpoint value from the configuration pointed to by wellKnowURL. |
||
| method | enum | post | Request method, allowed values: post, get. | |
| verify | boolean | Whether to enable SSL verification for this request; if not specified, defaults to enabled when the url uses https protocol, otherwise disabled. | ||
| authMethod | enum | basic | Signature data location and method. Allowed values are: client_secret_basic or basic: Authentication information is in the Authorization header, using basic authentication. client_secret_post: client_id and client_secret are in the body. none: client_id and client_secret are in the query. |
|
| paramMapping | dict | Mapping of parameter fields in the request, generally used for non-standard OIDC clients to adjust related parameter fields according to their own authentication process. Details are explained below. |
4. config.verifyTokenSet Configuration Internal Structure Parameter Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code for token. If not provided, defaults to the token_endpoint value from the configuration pointed to by wellKnowURL. |
||
| verify | boolean | Whether to enable SSL verification for this request; if not specified, defaults to enabled when the url uses https protocol, otherwise disabled. | ||
| keys | array | JWT algorithm data information pointed to by the url. Protocol Source, jwks_urls Data Structure Protocol Source |
5. config.getUserInfoSet Configuration Internal Structure Parameter Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| source | enum | id_token | Source method for obtaining user information. Allowed values are: id_token: Parsed from id_token; origin: Call the "Authentication Service" interface to obtain user information. |
|
| url | string | Request address for obtaining user information. If not provided, defaults to the userinfo_endpoint value from the configuration pointed to by wellKnowURL. This parameter is valid when source=origin. |
||
| verify | boolean | Whether to enable SSL verification for this request; if not specified, defaults to enabled when the url uses https protocol, otherwise disabled. | ||
| method | enum | post | Request method, allowed values: post, get; This parameter is valid when source=origin. |
|
| authMethod | enum | bearer | Signature data location and method. Allowed values are: bearer: HTTP Bearer authentication. client_secret_basic or basic: Authentication information is in the Authorization header, using basic authentication. client_secret_post: client_id and client_secret are in the body. none: client_id and client_secret are in the query. |
|
| paramMapping | dict | Mapping of parameter fields in the request, generally used for non-standard OIDC clients to adjust related parameter fields according to their own authentication process. Details are explained below. |
6. config.claimMapping Configuration Internal Structure Parameter Description
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| string | Y | Field representing the user's email. | ||
| username | string | Y | preferred_username | Field representing the user's username. |
| mobile | string | User's mobile phone number. |
7. Explanation of the paramMapping Parameter Internal Structure in getTokenSet, getTokenSet, getUserInfoSet Configurations
Note: When paramMapping exists, the custom request parameter process will be followed directly.
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| client_id | string | $client_id | Client ID, corresponding to the client_id in the protocol. | |
| scope | string | $scope | Data scope. A space-separated string of data scopes; Note, this is the scope in the request parameters, which differs from the data type in the external configuration. The scope in the external configuration exists as a default configuration and is of array type; Whereas the scope here exists as a request parameter and is of string type. Example: "openid email profile" |
|
| code | string | $code | Code passed by the "Authentication Service" for exchanging tokens. | |
| state | string | $state | Similar to CSRF function. | |
| redirect_uri | string | $redirect_uri | Redirect URI where the response will be sent. | |
| response_type | string | $response_type | Response type, value is code for authorization code flow. |
Request Example¶
curl 'https://openapi.guance.com/api/v1/sso/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
Response¶
{
"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"
}