Create SAML Configuration¶
POST /api/v1/sso/saml_create
Overview¶
Enable a SAML
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 domains Example: ['truewatch.com'] |
| idpName | string | Y | Provider Example: Default provider Max length: 64 $matchRegExp: [a-zA-Z_一-龥-]* |
| role | string | Y | Role Allow empty: False Optional values: ['general', 'readOnly'] |
| remark | string | Remark Allow empty: False Allow empty string: True |
|
| tokenHoldTime | integer | Token hold duration, in seconds, default value 14400 Allow empty: False Allow empty string: False $minValue: 1800 $maxValue: 86400 |
|
| tokenMaxValidDuration | integer | Maximum token validity duration, in seconds, default value 604800 Allow empty: False Allow empty string: False $minValue: 86400 $maxValue: 604800 |
Additional 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: easy: Simple UI editing mode. In this mode, users only need to configure the basic data required for the OIDC interaction protocol, other data are default values. expert: Expert configuration file mode, requiring users to upload OIDC configuration files. This mode supports customizing 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 by the "Authentication Service" for "TrueWatch" | |
| clientSecret | string | Y | Client secret corresponding to the client created by the "Authentication Service" for "TrueWatch" | |
| sslVerify | boolean | Whether to enforce SSL verification when requesting service discovery configuration information; Default is based on the protocol address of the wellKnowURL parameter value, if it is https, the default is true; otherwise, the default is false. |
||
| grantType | string | Y | authorization_code | Client ID created by the "Authentication Service" for "TrueWatch" |
| scope | array | Y | ["openid", "email"] | Accessible data permissions Required value: openid Other optional values, e.g., profile, email This value depends on the scope allocated by the "Authentication Service" for "TrueWatch" |
| authSet | dict | This configuration serves the authentication request address in the OIDC protocol. Protocol Source |
||
| getTokenSet | dict | This configuration serves the code exchange token 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 request in the OIDC protocol. Protocol Source |
||
| claimMapping | dict | Field mapping configuration in user information/id_token. Used by "TrueWatch" to obtain corresponding information in the account based on this mapping configuration. |
2. config.authSet Internal Structure Parameter Description
| Parameter Name | Type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Authentication request address. If not provided, the default is the authorization_endpoint value in the configuration pointed to by wellKnowURL. |
||
| verify | boolean | Whether to enable SSL verification for this request; if not specified, it is enabled by default when the url uses the https protocol, otherwise it is 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. See the description below for details. |
3. config.getTokenSet Internal Structure Parameter Description
| Parameter Name | Type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for code exchange token. If not provided, the default is the token_endpoint value in the configuration pointed to by wellKnowURL. |
||
| method | enum | post | Request method, optional values: post, get. | |
| verify | boolean | Whether to enable SSL verification for this request; if not specified, it is enabled by default when the url uses the https protocol, otherwise it is disabled. | ||
| authMethod | enum | basic | Signature data location and method. Optional values: client_secret_basic or basic: Authentication information is located in the Authorization in the request header, using 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 parameter fields in the request, generally used for non-standard OIDC clients to adjust related parameter fields according to their own authentication process. See the description below for details. |
4. config.verifyTokenSet Internal Structure Parameter Description
| Parameter Name | Type | Required | Default Value | Description |
|---|---|---|---|---|
| url | string | Request address for code exchange token. If not provided, the default is the token_endpoint value in the configuration pointed to by wellKnowURL. |
||
| verify | boolean | Whether to enable SSL verification for this request; if not specified, it is enabled by default when the url uses the https protocol, otherwise it is disabled. | ||
| keys | array | JWT algorithm data information pointed to by the url. Protocol Source, jwks_urls Data Structure Protocol Source |
5. config.getUserInfoSet Internal Structure Parameter Description
| Parameter Name | Type | Required | Default Value | Description |
|---|---|---|---|---|
| source | enum | id_token | Source method for obtaining user information. Optional values: id_token: Parse data 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 default is the userinfo_endpoint value in 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, it 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 location and method. Optional values: bearer: HTTP Bearer authentication. client_secret_basic or basic: Authentication information is located in the Authorization in the request header, using 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 parameter fields in the request, generally used for non-standard OIDC clients to adjust related parameter fields according to their own authentication process. See the description below for details. |
6. config.claimMapping 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 number. |
7. Description of the Internal Structure of the paramMapping Parameter in getTokenSet, getTokenSet, getUserInfoSet Configurations
Note, when paramMapping exists, it will directly follow the custom request parameter process.
| 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. String separated by spaces; Note, this is the scope in the request parameter, which is different from the data type in the external configuration. The scope in the external configuration exists as a default configuration and is an array type; The scope here exists as a request parameter and is a string type. Example: "openid email profile" |
|
| code | string | $code | Code passed by the "Authentication Service" for exchanging tokens. | |
| state | string | $state | Similar to the role of CSRF. | |
| redirect_uri | string | $redirect_uri | Redirect URI to which the response will be sent. | |
| response_type | string | $response_type | Response type, the value for the authorization code flow is code. |
Request Example¶
curl 'https://openapi.truewatch.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\nA1UECAwKQ2FsaWZvcm5iYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMTEwMjYyMjQxMjZaFw0zMTEwMjYyMjQyMjZaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5iYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG\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\nA1UECAwKQ2FsaWZvcm5iYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi0zODQzNjMzODEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMTEwMjYyMjQxMjZaFw0zMTEwMjYyMjQyMjZaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5iYTEWMBQGA1UEBwwNU2Fu IEZyYW5jaXNjbzENMAsG\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"
}