Create SSO Configuration¶
POST /api/v1/sso/create
Overview¶
Enable an SSO
Request Body Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Y | Type Example: Allow Empty: False Available values: ['saml', 'oidc'] |
| idpData | string | XML document content (required for SAML type) Example: Allow Empty: False |
|
| config | json | Access configuration (required for OIDC type. Note that clientSecret must be base64-encoded when passed to the backend); SAML supports config.claimMapping: username/email are required non-empty attribute names, mobile is optional. If missing, it falls back to the default mobile; an explicit empty string is not extracted. When no mapping is configured, legacy attribute names are compatible. When modifying SAML, a valid idpData must be submitted together with a non-empty config. For SAML/OIDC, if a mobile number exists at login, the mobile number and country code are retained; only when no number exists is a valid IdP number filled in. Example: Allow Empty: False |
|
| emailDomains | array | Y | Email domains Example: ['truewatch.com'] |
| idpName | string | Y | Provider Example: Default provider Maximum 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 | Idle session retention duration (in seconds; default 7 days, 604800 seconds) Example: 604800 Allow Empty: False $minValue: 60 $maxValue: 604800 |
|
| tokenMaxValidDuration | integer | Maximum login session retention duration (in seconds; default 30 days, 604800 seconds) Example: 2592000 Allow Empty: False $minValue: 60 $maxValue: 2592000 |
|
| needNotify | boolean | Whether to send an email notification for SSO configuration changes; defaults to true. Passing false only suppresses the email notification and does not affect the configuration change or audit records. Example: True Allow Empty: False |
Supplementary Parameter Notes¶
OIDC Type config Configuration Notes
When type='saml', config can store claimMapping; username/email are required and mobile is optional. When modifying, idpData must be carried at the same time. Existing mobile numbers will not be overwritten or cleared by SAML/OIDC login.
When type='oidc', the config field takes effect. Its data structure is as follows:
1. Description of config Fields
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| modeType | enum | easy | Configuration file editing mode. Available values: easy: Simple UI editing mode. In this mode, users only need to configure the basic data required by the OIDC interaction protocol; all other data uses default values. expert: Expert configuration file mode, which requires users to upload an OIDC configuration file. This mode supports customizing 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 | The client ID created by the "authentication service" for "TrueWatch" | |
| clientSecret | string | Y | The 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; by default, this depends 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 | The 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 assigned by the "authentication service" to "TrueWatch" |
| authSet | dict | This configuration is used for the authorization request address in the OIDC protocol. Protocol source |
||
| getTokenSet | dict | This configuration is used for the code-to-token request in the OIDC protocol. Protocol source |
||
| verifyTokenSet | dict | Validation configuration for id_token. Protocol source, jwks_urls data structure protocol source |
||
| getUserInfoSet | dict | This configuration is used for the user info request in the OIDC protocol. Protocol source |
||
| claimMapping | dict | Field mapping configuration in user info/id_token. Used by "TrueWatch" to obtain the corresponding account information based on this mapping. |
2. Description of config.authSet Internal Structure Parameters
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| url | string | Authorization request address. If not provided, the authorization_endpoint value in the configuration pointed to by wellKnowURL is used by default. |
||
| verify | boolean | Whether to enable SSL verification for this request; when unspecified, it is enabled by default if the url uses the https protocol, otherwise it is disabled. | ||
| paramMapping | dict | Mapping of parameter fields in the request, generally used by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication flow. See the notes below for details. |
3. Description of config.getTokenSet Internal Structure Parameters
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code for token. If not provided, the token_endpoint value in the configuration pointed to by wellKnowURL is used by default. |
||
| method | enum | post | Request method. Available values: post, get | |
| verify | boolean | Whether to enable SSL verification for this request; when unspecified, it is enabled by default if the url uses the https protocol, otherwise it is disabled. | ||
| authMethod | enum | basic | Location and method of the signing data. Available values: client_secret_basic or basic: The 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 by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication flow. See the notes below for details. |
4. Description of config.verifyTokenSet Internal Structure Parameters
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| url | string | Request address for exchanging code for token. If not provided, the token_endpoint value in the configuration pointed to by wellKnowURL is used by default. |
||
| verify | boolean | Whether to enable SSL verification for this request; when unspecified, it is enabled by default if 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. Description of config.getUserInfoSet Internal Structure Parameters
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| source | enum | id_token | Source method for obtaining user information. Available values: id_token: Data is parsed from the id_token. origin: Call the "authentication service" API to obtain user information. |
|
| url | string | Request address for obtaining user information. If not provided, the userinfo_endpoint value in the configuration pointed to by wellKnowURL is used by default. This parameter takes effect when source=origin. |
||
| verify | boolean | Whether to enable SSL verification for this request; when unspecified, it is enabled by default if the url uses the https protocol, otherwise it is disabled. | ||
| method | enum | post | Request method. Available values: post, get. This parameter takes effect when source=origin. |
|
| authMethod | enum | bearer | Location and method of the signing data. Available values: bearer: HTTP Bearer authentication. client_secret_basic or basic: The 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 by non-standard OIDC customers to adjust relevant parameter fields according to their own authentication flow. See the notes below for details. |
6. Description of config.claimMapping Internal Structure Parameters
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| string | Y | The field representing the user's email | ||
| username | string | Y | preferred_username | The field representing the user's username |
| mobile | string | The user's mobile number |
7. Description of the Internal Structure of the paramMapping Parameter in the getTokenSet, getTokenSet, and getUserInfoSet Configurations
Note: When paramMapping is present, the custom request parameter flow is used directly.
| Parameter | type | Required | Default | Description |
|---|---|---|---|---|
| client_id | string | $client_id | Client ID, corresponding to the client_id in the protocol. | |
| scope | string | $scope | Data scope. A string of data scopes separated by spaces. Note: This is the scope in the request parameters, and its data type differs from that in the external configuration. The scope in the external configuration exists as the default configuration and is an array type; the scope here exists as a request parameter and is a string type. For example: "openid email profile" |
|
| code | string | $code | The code passed by the "authentication service" for exchanging a token. | |
| state | string | $state | Serves a role similar to CSRF. | |
| redirect_uri | string | $redirect_uri | The redirect URI to which the response will be sent. | |
| response_type | string | $response_type | Response type. Its value in the authorization code flow is code. |
Request Example¶
curl 'https://openapi.truewatch.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"
}