Skip to content

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
email string Y email 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"
}