Skip to content

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
Allowed 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
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 Token hold duration, in seconds timestamp, default value 14400
Allow Empty: False
Allow Empty String: False
$minValue: 1800
$maxValue: 86400
tokenMaxValidDuration integer Token maximum validity period, in seconds timestamp, default value 604800
Allow Empty: False
Allow Empty String: False
$minValue: 86400
$maxValue: 604800

Parameter Supplementary Description

OIDC Type config Configuration Explanation

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 as follows:
easy: Simple UI editing mode. In this mode, users only need to configure the basic data required in the OIDC interaction protocol, other data are default values.
expert: Expert configuration file mode, requires 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.
For example, Microsoft AAD
clientId string Y Client ID created by the "Authentication Service" for "Guance"
clientSecret string Y Client secret corresponding to the client created by the "Authentication Service" for "Guance"
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 is https, it defaults to true; otherwise, it defaults to false.
grantType string Y authorization_code Client ID created by the "Authentication Service" for "Guance"
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" to "Guance".
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 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 according to 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, it defaults to 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 defaults to enabled when the URL uses the 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. For details, see the description below.


3. config.getTokenSet Internal Structure Parameter Description

Parameter Name type Required Default Value Description
url string Request address for exchanging code for token.
If not provided, it defaults to the token_endpoint value in 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, it defaults to enabled when the URL uses the https protocol, otherwise disabled.
authMethod enum basic Signature data location and method. Allowed values are as follows:
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. For details, see the description below.


4. config.verifyTokenSet Internal Structure Parameter Description

Parameter Name type Required Default Value Description
url string Request address for exchanging code for token.
If not provided, it defaults to 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 defaults to enabled when the URL uses the 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 Internal Structure Parameter Description

Parameter Name type Required Default Value Description
source enum id_token Source method for obtaining user information. Allowed values are as follows:
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, it defaults to 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 defaults to enabled when the URL uses the 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 as follows:
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. For details, see the description below.


6. config.claimMapping Internal Structure Parameter Description

Parameter Name type Required Default Value Description
email string Y email 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. Internal Structure Description for 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. A space-separated string of data scopes;
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;
Whereas the scope here exists as a 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 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 the authorization code flow.

Request Example

```shell curl 'https://openapi.guance.com/api/v1/sso/saml_create' \ -H 'DF-API-KEY: ' \ -H 'Content-Type: application/json;charset=UTF-8' \ --data-raw '{"idpData":"<?xml version=\\"1.0\\" encoding=\\"UTF-8\\"?>MIIDqDCCApCgAwIBAgIGAXy+xOGoMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXN

Feedback

Is this page helpful? ×