Create SAML Configuration¶
POST /api/v1/sso/saml_create
Overview¶
Enable a SAML configuration
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| type | string | Y | Type Example: Allow empty: False Optional values: ['saml', 'oidc'] |
| idpData | string | Y | XML document content (Required for saml type) Example: Allow empty: False |
| config | json | Access configuration table (Required for oidc type) Example: Allow empty: False |
|
| emailDomains | array | Y | Email domain Example: ['guance.com'] |
| idpName | string | Y | Provider Example: Default provider Maximum length: 64 $matchRegExp: [a-zA-Z_一-龥-]* |
| role | string | Y | Role Allow empty: False Optional values: ['general', 'readOnly'] |
| remark | string | Note Allow empty: False Allow empty string: True |
|
| tokenHoldTime | integer | Token retention duration, in seconds, default value 14400 Allow empty: False Allow empty string: False $minValue: 1800 $maxValue: 86400 |
|
| tokenMaxValidDuration | integer | Maximum validity period of the token, in seconds, default value 604800 Allow empty: False Allow empty string: False $minValue: 86400 $maxValue: 604800 |
Supplementary Parameter Description¶
OIDC Type config Configuration Description
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. Optional 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 user-defined various request information in the OIDC protocol |
|
| wellKnowURL | string | Y | Standard service discovery address in the OIDC protocol. For example, Microsoft AAD |
|
| clientId | string | Y | Client ID created by «authentication service» for «Guance» | |
| clientSecret | string | Y | Secret key corresponding to the client created by «authentication service» for «Guance» | |
| sslVerify | boolean | Whether SSL certification is enforced when requesting service discovery configuration information; By default, it distinguishes based on the protocol address of the wellKnowURL parameter; if it is https, the default is true; otherwise, the default is false |
||
| grantType | string | Y | authorization_code | Client ID created by «authentication service» for «Guance» |
| scope | array | Y | ["openid", "email"] | Accessible data permissions One of the required values is: openid Other optional values, such as profile, email This value depends on the scop allocated by «authentication service» for «Guance» |
| authSet | dict | This configuration serves the authentication request address in the OIDC protocol. Protocol source |
||
| getTokenSet | dict | This configuration serves the code-to-token request in the OIDC protocol. Protocol source |
||
| verifyTokenSet | dict | ID_token validation configuration. Protocol source, jwks_urls data structure protocol source |
||
| getUserInfoSet | dict | This configuration serves the user information request in the OIDC protocol. Protocol source |
||
| claimMapping | dict | User information/id_token field mapping configuration. Used by «Guance» to obtain corresponding information in the account based on this mapping configuration |
2. Internal Structure Parameter Description of config.authSet
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Authentication request address. If not provided, the authorization_endpoint value in the wellKnowURL pointing configuration will be used by default. |
||
| verify | boolean | Whether SSL verification needs to be enabled for this request; If not specified, SSL verification is enabled by default when the URL uses the https protocol, otherwise it is disabled. | ||
| paramMapping | dict | Mapping of parameters in the request, generally used by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication process. See detailed explanation below |
3. Internal Structure Parameter Description of config.getTokenSet
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code with token. If not provided, the token_endpoint value in the wellKnowURL pointing configuration will be used by default. |
||
| method | enum | post | Request method, optional values: post, get | |
| verify | boolean | Whether SSL verification needs to be enabled for this request; If not specified, SSL verification is enabled by default when the URL uses the https protocol, otherwise it is disabled. | ||
| authMethod | enum | basic | Signature data position and method. Optional values are as follows client_secret_basic or basic: Authentication information is located in the Authorization of the request header, which is basic authentication client_secret_post: client_id and client_secret are located in the body none: client_id and client_secret are located in the query |
|
| paramMapping | dict | Mapping of parameters in the request, generally used by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication process. See detailed explanation below |
4. Internal Structure Parameter Description of config.verifyTokenSet
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code with token. If not provided, the token_endpoint value in the wellKnowURL pointing configuration will be used by default. |
||
| verify | boolean | Whether SSL verification needs to be enabled for this request; If not specified, SSL verification is enabled by default when the URL uses the https protocol, otherwise it is disabled. | ||
| keys | array | URL pointing to JWT algorithm data information Protocol source, jwks_urls data structure protocol source |
5. Internal Structure Parameter Description of config.getUserInfoSet
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| source | enum | id_token | Method of obtaining user information. Optional values are as follows id_token: Data 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, the userinfo_endpoint value in the wellKnowURL pointing configuration will be used by default. This parameter is valid when source=origin. |
||
| verify | boolean | Whether SSL verification needs to be enabled for this request; If not specified, SSL verification is enabled by default when the URL uses the https protocol, otherwise it is disabled. | ||
| method | enum | post | Request method, optional values: post, get; This parameter is valid when source=origin |
|
| authMethod | enum | bearer | Signature data position and method. Optional values are as follows: bearer: HTTP Bearer authentication client_secret_basic or basic: Authentication information is located in the Authorization of the request header, which is basic authentication client_secret_post: client_id and client_secret are located in the body none: client_id and client_secret are located in the query |
|
| paramMapping | dict | Mapping of parameters in the request, generally used by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication process. See detailed explanation below |
6. Internal Structure Parameter Description of config.claimMapping
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| string | Y | Represents the user's email field | ||
| username | string | Y | preferred_username | Represents the user's username field |
| mobile | string | User's phone number |
7. Internal Structure Parameter Description of paramMapping in getTokenSet, getTokenSet, and getUserInfoSet Configurations
Note: When paramMapping exists, it directly follows the custom request parameter process.
| Parameter Name | type | Required | Default Value | Description |
|---|---|---|---|---|
| client_id | string | $client_id | Client ID, corresponds to the client_id in the protocol | |
| scope | string | $scope | Data scope. Space-separated data scope string; Note that this is the scope in the request parameter, its data type differs from the one in the external configuration. The scope in the external configuration serves as the default configuration and is an array type; while the scope here serves as the request parameter and is a string type. For example: “openid email profile” |
|
| code | string | $code | Code passed by the «authentication service» for exchanging tokens | |
| state | string | $state | Similar to CSRF | |
| redirect_uri | string | $redirect_uri | Redirect URI where the response will be sent to. | |
| response_type | string | $response_type | Response type, value for authorization code flow is code |
Request Example¶
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
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"
}