Single Sign-On Server Interfaces

QueryThirdPartyAccountSourceBinding

Query Third Party Account Source Binding

API Request

URLs

GET zstack/v1/account-import/bindings

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" -X GET http://localhost:8080/zstack/v1/account-import/bindings?q=accountUuid=ff0b33166633399aae77ea258d2f7900

Queryable Fields

Run the CLI tool and enter QueryThirdPartyAccountSourceBinding, and press Tab to view all queryable fields and the names of resources available for cross-table queries.

API Response

Response Example

{
  "inventories": [
    {
      "id": 1,
      "credentials": "ou\u003dEmployee,uid\u003dtest",
      "accountSourceUuid": "ff0df349f4d13f4081d57b3715851900",
      "accountUuid": "ff0b33166633399aae77ea258d2f7900"
    }
  ]
}

Name	Type	Description	Starting Version
success	boolean	Whether the request succeeded	4.3.0
error	ErrorCode	For details, see error	4.3.0
inventories	List	For details, see inventories	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code, which globally and uniquely identifies the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Summary description of the error	0.6
details	String	Details of the error	0.6
elaboration	String	Reserved field. The default value is null	0.6
opaque	LinkedHashMap	Reserved field. The default value is null	0.6
cause	ErrorCode	Root error that caused the current error. This field is null if there is no source error	0.6

#inventories

Name	Type	Description	Starting Version
id	Long	Uniquely identifies the relationship	4.3.0
credentials	String	Unique identifier of the user from the import source. For example, for users imported from an LDAP source, this is the UID used for login.	4.3.0
accountSourceUuid	String	Import source server UUID	4.3.0
accountUuid	String	Account UUID	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

SDK Examples

Java SDK

QueryThirdPartyAccountSourceBindingAction action = new QueryThirdPartyAccountSourceBindingAction();
action.conditions = asList("accountUuid=ff0b33166633399aae77ea258d2f7900");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryThirdPartyAccountSourceBindingAction.Result res = action.call();

Python SDK

action = QueryThirdPartyAccountSourceBindingAction()
action.conditions = ["accountUuid=ff0b33166633399aae77ea258d2f7900"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

AddLdapServer

API Request

URLs

POST zstack/v1/ldap/servers

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "miao",
    "description": "miao desc",
    "url": "ldap://localhost:1888",
    "base": "dc\u003dexample,dc\u003dcom",
    "username": "",
    "password": "",
    "encryption": "None",
    "serverType": "WindowsAD",
    "usernameProperty": "cn",
    "filter": "(cn\u003dMicha Kops)",
    "syncCreatedAccountStrategy": "CreateAccount",
    "syncDeletedAccountStrategy": "StaleAccount"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"miao","description":"miao desc","url":"ldap://localhost:1888","base":"dc=example,dc=com","username":"","password":"","encryption":"None","serverType":"WindowsAD","usernameProperty":"cn","filter":"(cn=Micha Kops)","syncCreatedAccountStrategy":"CreateAccount","syncDeletedAccountStrategy":"StaleAccount"}}' \
http://localhost:8080/zstack/v1/ldap/servers

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
name	String	body (enclosed in the `params` structure)	Resource name		4.3.0
description (Optional)	String	body (enclosed in the `params` structure)	Detailed description of the resource		4.3.0
url	String	body (enclosed in the `params` structure)	LDAP server access URL		4.3.0
base	String	body (enclosed in the `params` structure)	LDAP server query BaseDN		4.3.0
username	String	body (enclosed in the `params` structure)	Username for accessing the LDAP server		4.3.0
password	String	body (enclosed in the `params` structure)	Password		4.3.0
encryption	String	body (enclosed in the `params` structure)	Encryption method	None TLS	4.3.0
systemTags (Optional)	List	body	System tags		4.3.0
userTags (Optional)	List	body	User tags		4.3.0
serverType (Optional)	String	body (enclosed in the `params` structure)	LDAP server type	OpenLdap WindowsAD Unknown	4.3.0
usernameProperty (Optional)	String	body (enclosed in the `params` structure)	The field used as the username when a user logs in to the virtualization platform		4.3.0
filter (Optional)	String	body (enclosed in the `params` structure)	The filter used when syncing from the LDAP server, which determines which users need to be synced		4.3.0
syncCreatedAccountStrategy (Optional)	String	body (enclosed in the `params` structure)	The strategy for handling newly created users on the LDAP server during synchronization: create a corresponding account or take no action	NoAction CreateDisabledAccount CreateAccount	4.3.0
syncDeletedAccountStrategy (Optional)	String	body (enclosed in the `params` structure)	The strategy for handling deleted users on the LDAP server during synchronization: delete the corresponding account, mark as stale, or take no action	NoAction StaleAccount DeleteAccount	4.3.0

API Response

Response Example

{
  "inventory": {
    "uuid": "01b489793e3d31728ccbbc4fdfd99ed0",
    "name": "miao",
    "description": "miao desc",
    "url": "ldap://localhost:1888",
    "base": "dc\u003dexample,dc\u003dcom",
    "username": "",
    "password": "",
    "encryption": "None"
  }
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0
inventory	LdapServerInventory	For details, see inventory	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

#inventory

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource.	4.3.0
name	String	Resource name	4.3.0
type	String	User source type, typically ldap	4.3.0
description	String	Detailed description of the resource	4.3.0
url	String	The URL.	4.3.0
base	String	LDAP server access URL	4.3.0
username	String	Username for accessing the LDAP server	4.3.0
password	String	Password	4.3.0
encryption	String	Encryption method	4.3.0
serverType	String	Server type. Possible values are OpenLdap or WindowsAD. Returns Unknown if the type cannot be determined.	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

SDK Examples

Java SDK

AddLdapServerAction action = new AddLdapServerAction();
action.name = "miao";
action.description = "miao desc";
action.url = "ldap://localhost:1888";
action.base = "dc=example,dc=com";
action.username = "";
action.password = "";
action.encryption = "None";
action.serverType = "WindowsAD";
action.usernameProperty = "cn";
action.filter = "(cn=Micha Kops)";
action.syncCreatedAccountStrategy = "CreateAccount";
action.syncDeletedAccountStrategy = "StaleAccount";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AddLdapServerAction.Result res = action.call();

Python SDK

AddLdapServerAction action = AddLdapServerAction()
action.name = "miao"
action.description = "miao desc"
action.url = "ldap://localhost:1888"
action.base = "dc=example,dc=com"
action.username = ""
action.password = ""
action.encryption = "None"
action.serverType = "WindowsAD"
action.usernameProperty = "cn"
action.filter = "(cn=Micha Kops)"
action.syncCreatedAccountStrategy = "CreateAccount"
action.syncDeletedAccountStrategy = "StaleAccount"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AddLdapServerAction.Result res = action.call()

DeleteLdapServer

API Request

URLs

DELETE zstack/v1/ldap/servers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/ldap/servers/01d547012c9a39cf85964e578842f5a5

Parameter List

Name	Type	Location	Description	Starting Version
uuid	String	url	Resource UUID. Uniquely identifies the resource.	4.3.0
deleteMode (Optional)	String	body	Deletion mode	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

This API returns an empty JSON structure {} on success. On failure, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK

DeleteLdapServerAction action = new DeleteLdapServerAction();
action.uuid = "01d547012c9a39cf85964e578842f5a5";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteLdapServerAction.Result res = action.call();

Python SDK

DeleteLdapServerAction action = DeleteLdapServerAction()
action.uuid = "01d547012c9a39cf85964e578842f5a5"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteLdapServerAction.Result res = action.call()

QueryLdapServer

API Request

URLs

GET zstack/v1/ldap/servers
GET zstack/v1/ldap/servers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/ldap/servers?q=name=ldap server

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/ldap/servers/68ff5ef58b4634dba740b26db67d3b01

Queryable Fields

Run the CLI command line tool, enter QueryLdapServer and press the Tab key to view all queryable fields and cross-table queryable resource names.

API Response

Response Example

{
  "inventories": [
    {
      "uuid": "fea82960cbaa33bb9f3de91c8054af8d",
      "name": "miao",
      "description": "miao desc",
      "url": "ldap://localhost:1888",
      "base": "dc\u003dexample,dc\u003dcom",
      "username": "",
      "password": "",
      "encryption": "None"
    }
  ]
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0
inventories	List	For details, see inventories	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

#inventories

Name	Type	Description	Starting Version
uuid	Long	Resource UUID. Uniquely identifies the resource.	4.3.0
name	String	Resource name	4.3.0
type	String	User source type, typically ldap	4.3.0
description	String	Detailed description of the resource	4.3.0
url	String	The URL.	4.3.0
base	String	LDAP server access URL	4.3.0
username	String	Username for accessing the LDAP server	4.3.0
password	String	Password	4.3.0
encryption	String	Encryption method	4.3.0
serverType	String	Server type. Possible values are OpenLdap or WindowsAD. Returns Unknown if the type cannot be determined.	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

SDK Examples

Java SDK

QueryLdapServerAction action = new QueryLdapServerAction();
action.conditions = asList("name=ldap server");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryLdapServerAction.Result res = action.call();

Python SDK

QueryLdapServerAction action = QueryLdapServerAction()
action.conditions = ["name=ldap server"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryLdapServerAction.Result res = action.call()

UpdateLdapServer

API Request

URLs

PUT zstack/v1/ldap/servers/{ldapServerUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{
  "updateLdapServer": {
    "name": "new name"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateLdapServer":{"name":"new name"}}' \
http://localhost:8080/zstack/v1/ldap/servers/ddd2491867273e6d8fb7c891faf0413f

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
ldapServerUuid	String	url	UUID of the LDAP server		4.3.0
name (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Resource name		4.3.0
description (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Detailed description of the resource		4.3.0
url (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Access URL of the LDAP server		4.3.0
base (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Query BaseDN of the LDAP server		4.3.0
username (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Username for accessing the LDAP server		4.3.0
password (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Password		4.3.0
encryption (Optional)	String	body (enclosed in the `updateLdapServer` structure)	Encryption method	None TLS	4.3.0
systemTags (Optional)	List	body	System tags		4.3.0
userTags (Optional)	List	body	User tags		4.3.0
serverType (Optional)	String	body (enclosed in the `updateLdapServer` structure)	LDAP server type	OpenLdap WindowsAD Unknown	4.3.0
usernameProperty (Optional)	String	body (enclosed in the `updateLdapServer` structure)	The field used as the username when a user logs in to the virtualization platform		4.3.0
filter (Optional)	String	body (enclosed in the `updateLdapServer` structure)	The filter used when syncing from the LDAP server, which determines which users need to be synced		4.3.0
syncCreatedAccountStrategy (Optional)	String	body (enclosed in the `updateLdapServer` structure)	The strategy for handling newly created users on the LDAP server during synchronization: create a corresponding account or take no action	NoAction CreateDisabledAccount CreateAccount	4.3.0
syncDeletedAccountStrategy (Optional)	String	body (enclosed in the `updateLdapServer` structure)	The strategy for handling deleted users on the LDAP server during synchronization: delete the corresponding account, mark as stale, or take no action	NoAction StaleAccount DeleteAccount	4.3.0

API Response

Response Example

{
  "inventory": {
    "uuid": "5c502802c9633f4398e9f286d8187f49",
    "name": "new name",
    "description": "miao desc",
    "url": "ldap://localhost:1888",
    "base": "dc\u003dexample,dc\u003dcom",
    "username": "",
    "password": "",
    "encryption": "None"
  }
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0
inventory	LdapServerInventory	For details, see inventory	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

#inventory

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource.	4.3.0
name	String	Resource name	4.3.0
type	String	User source type, typically ldap	4.3.0
description	String	Detailed description of the resource	4.3.0
url	String	The URL.	4.3.0
base	String	LDAP server access URL	4.3.0
username	String	Username for accessing the LDAP server	4.3.0
password	String	Password	4.3.0
encryption	String	Encryption method	4.3.0
serverType	String	Server type. Possible values are OpenLdap or WindowsAD. Returns Unknown if the type cannot be determined.	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

SDK Examples

Java SDK

UpdateLdapServerAction action = new UpdateLdapServerAction();
action.ldapServerUuid = "ddd2491867273e6d8fb7c891faf0413f";
action.name = "new name";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateLdapServerAction.Result res = action.call();

Python SDK

UpdateLdapServerAction action = UpdateLdapServerAction()
action.ldapServerUuid = "ddd2491867273e6d8fb7c891faf0413f"
action.name = "new name"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateLdapServerAction.Result res = action.call()

CreateLdapBinding

API Request

URLs

POST zstack/v1/ldap/bindings

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "ldapUid": "ou\u003dEmployee,uid\u003dtest",
    "accountUuid": "ed7d933c7a6d37fb9bd444140faeec5c"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"ldapUid":"ou=Employee,uid=test","accountUuid":"ed7d933c7a6d37fb9bd444140faeec5c"}}' \
http://localhost:8080/zstack/v1/ldap/bindings

Parameter List

Name	Type	Location	Description	Starting Version
ldapUid	String	body (enclosed in the `params` structure)	LDAP UID	4.3.0
accountUuid	String	body (enclosed in the `params` structure)	Account UUID	4.3.0
ldapServerUuid (Optional)	String	body (enclosed in the `params` structure)	LDAP server UUID. If not specified, the system selects the UUID of the currently active LDAP server.	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

Response Example

{
  "inventory": {
    "id": 1,
    "credentials": "ou\u003dEmployee,uid\u003dtest",
    "accountSourceUuid": "41006790733e38db9ce810878e19f8a3",
    "accountUuid": "3be58c2832a939bf9bce2ea959e04ce8"
  }
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0
inventory	ImportAccountRefInventory	For details, see inventory	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

#inventory

Name	Type	Description	Starting Version
id	Long	Uniquely identifies the relationship	4.3.0
credentials	String	Unique identifier of the user from the import source. For example, for users imported from an LDAP source, this is the UID used for login.	4.3.0
accountSourceUuid	String	Import source server UUID	4.3.0
accountUuid	String	Account UUID	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

SDK Examples

Java SDK

CreateLdapBindingAction action = new CreateLdapBindingAction();
action.ldapUid = "ou=Employee,uid=test";
action.accountUuid = "ed7d933c7a6d37fb9bd444140faeec5c";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateLdapBindingAction.Result res = action.call();

Python SDK

CreateLdapBindingAction action = CreateLdapBindingAction()
action.ldapUid = "ou=Employee,uid=test"
action.accountUuid = "ed7d933c7a6d37fb9bd444140faeec5c"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreateLdapBindingAction.Result res = action.call()

DeleteLdapBinding

API Request

URLs

DELETE zstack/v1/ldap/bindings/{accountUuid}

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/ldap/bindings/f1fb55eee96c3437991a0055d5d0abaa

Parameter List

Name	Type	Location	Description	Starting Version
accountUuid	String	url	Account UUID	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

This API returns an empty JSON structure {} on success. On failure, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK

DeleteLdapBindingAction action = new DeleteLdapBindingAction();
action.accountUuid = "f1fb55eee96c3437991a0055d5d0abaa";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteLdapBindingAction.Result res = action.call();

Python SDK

DeleteLdapBindingAction action = DeleteLdapBindingAction()
action.accountUuid = "f1fb55eee96c3437991a0055d5d0abaa"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteLdapBindingAction.Result res = action.call()

GetCandidateLdapEntryForBinding

API Request

URLs

GET zstack/v1/ldap/entries/candidates

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/ldap/entries/candidates?ldapFilter=(cn=user_xxx)&limit=2500

Parameter List

Name	Type	Location	Description	Starting Version
ldapFilter	String	query	Query filter	4.3.0
ldapServerUuid (Optional)	String	query	UUID of the LDAP server used for the query. If not specified, the system uses the UUID of the currently active LDAP server.	4.3.0
systemTags (Optional)	List	query	System tags	4.3.0
userTags (Optional)	List	query	User tags	4.3.0
limit (Optional)	Integer	query	Maximum number of records to return, similar to MySQL limit	4.3.0

API Response

Response Example

{
  "inventories": []
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
inventories	List	The inventories.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

SDK Examples

Java SDK

GetCandidateLdapEntryForBindingAction action = new GetCandidateLdapEntryForBindingAction();
action.ldapFilter = "(cn=user_xxx)";
action.limit = 2500;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetCandidateLdapEntryForBindingAction.Result res = action.call();

Python SDK

GetCandidateLdapEntryForBindingAction action = GetCandidateLdapEntryForBindingAction()
action.ldapFilter = "(cn=user_xxx)"
action.limit = 2500
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetCandidateLdapEntryForBindingAction.Result res = action.call()

GetLdapEntry

API Request

URLs

GET zstack/v1/ldap/entry

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/ldap/entry?ldapFilter=(cn=user_xxx)&limit=2500

Parameter List

Name	Type	Location	Description	Starting Version
ldapFilter	String	query	Query filter	4.3.0
ldapServerUuid (Optional)	String	query	UUID of the LDAP server used for the query. If not specified, the system uses the UUID of the currently active LDAP server.	4.3.0
systemTags (Optional)	List	query	System tags	4.3.0
userTags (Optional)	List	query	User tags	4.3.0
limit (Optional)	Integer	query	Maximum number of records to return, similar to MySQL limit	4.3.0

API Response

Response Example

{
  "inventories": []
}

Name	Type	Description	Starting Version
success	boolean	Whether the operation succeeded.	4.3.0
inventories	List	The inventories.	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

SDK Examples

Java SDK

GetLdapEntryAction action = new GetLdapEntryAction();
action.ldapFilter = "(cn=user_xxx)";
action.limit = 2500;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetLdapEntryAction.Result res = action.call();

Python SDK

GetLdapEntryAction action = GetLdapEntryAction()
action.ldapFilter = "(cn=user_xxx)"
action.limit = 2500
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetLdapEntryAction.Result res = action.call()

SyncAccountsFromLdapServer

API Request

URLs

PUT zstack/v1/ldap/servers/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "syncAccountsFromLdapServer": {},
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"syncAccountsFromLdapServer":{}}' \
http://localhost:8080/zstack/v1/ldap/servers/0fdb3f15019f362396cd13645d5e5135/actions

Parameter List

Name	Type	Location	Description	Starting Version
uuid	String	url	UUID of the LDAP server. Uniquely identifies the resource.	4.3.0
createAccountStrategy (Optional)	String	body (enclosed in the `syncAccountsFromLdapServer` structure)	The strategy for handling newly created users on the LDAP server during synchronization: create a corresponding account or take no action	4.3.0
deleteAccountStrategy (Optional)	String	body (enclosed in the `syncAccountsFromLdapServer` structure)	The strategy for handling deleted users on the LDAP server during synchronization: delete the corresponding account, mark as stale, or take no action	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

This API returns an empty JSON structure {} on success. On failure, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK

SyncAccountsFromLdapServerAction action = new SyncAccountsFromLdapServerAction();
action.uuid = "0fdb3f15019f362396cd13645d5e5135";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SyncAccountsFromLdapServerAction.Result res = action.call();

Python SDK

SyncAccountsFromLdapServerAction action = SyncAccountsFromLdapServerAction()
action.uuid = "0fdb3f15019f362396cd13645d5e5135"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
SyncAccountsFromLdapServerAction.Result res = action.call()

CreateSSORedirectTemplate

API Request

URLs

POST zstack/v1/create/sso/redirect/template/

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "test",
    "description": "desc",
    "clientUuid": "64053daa6b56335d843b3fb837fd8133",
    "redirectTemplate": "http://172.24.194.28:5000/oauth1/verify/?username\u003d${username}\u0026sessionId\u003d${sessionId}\u0026userUuid\u003d${userUuid}\u0026accountUuid\u003d${accountUuid}\u0026loginType\u003d${loginType}\u0026userType\u003d${userType}\u0027"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"test","description":"desc","clientUuid":"64053daa6b56335d843b3fb837fd8133","redirectTemplate":"http://172.24.194.28:5000/oauth1/verify/?username=${username}&sessionId=${sessionId}&userUuid=${userUuid}&accountUuid=${accountUuid}&loginType=${loginType}&userType=${userType}'"}}' \
http://localhost:8080/zstack/v1/create/sso/redirect/template/

Parameter List

Name	Type	Location	Description	Starting Version
name	String	body (enclosed in the `params` structure)	Resource name	4.3.0
description	String	body (enclosed in the `params` structure)	Detailed description of the resource	4.3.0
clientUuid	String	body (enclosed in the `params` structure)	UUID of the corresponding SSO client, which is the UUID of the third-party account source	4.3.0
redirectTemplate	String	body (enclosed in the `params` structure)	Redirect template	4.3.0
resourceUuid (Optional)	String	body (enclosed in the `params` structure)	Resource UUID	4.3.0
tagUuids (Optional)	List	body (enclosed in the `params` structure)	Tag UUID list	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

Response Example

{
  "inventory": {
    "uuid": "8b233284793c3da397f6ebd7351c3a54",
    "name": "test",
    "description": "desv",
    "clientUuid": "827d2ea3ae8133bbba0b726c1d8e716d"
  }
}

Name	Type	Description	Starting Version
success	boolean	Whether the creation is successful	4.3.0
inventory	SSORedirectTemplateInventory	For details, see inventory	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0

#inventory

Name	Type	Description	Starting Version
uuid	String	Template UUID. Uniquely identifies the resource.	4.3.0
name	String	Template name	4.3.0
description	String	Detailed description of the template	4.3.0
clientUuid	String	UUID of the corresponding SSO client, which is the UUID of the third-party account source	4.3.0
redirectTemplate	String	Redirect template	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

SDK Examples

Java SDK

CreateSSORedirectTemplateAction action = new CreateSSORedirectTemplateAction();
action.name = "test";
action.description = "desc";
action.clientUuid = "64053daa6b56335d843b3fb837fd8133";
action.redirectTemplate = "http://172.24.194.28:5000/oauth1/verify/?username=${username}&sessionId=${sessionId}&userUuid=${userUuid}&accountUuid=${accountUuid}&loginType=${loginType}&userType=${userType}'";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateSSORedirectTemplateAction.Result res = action.call();

Python SDK

CreateSSORedirectTemplateAction action = CreateSSORedirectTemplateAction()
action.name = "test"
action.description = "desc"
action.clientUuid = "64053daa6b56335d843b3fb837fd8133"
action.redirectTemplate = "http://172.24.194.28:5000/oauth1/verify/?username=${username}&sessionId=${sessionId}&userUuid=${userUuid}&accountUuid=${accountUuid}&loginType=${loginType}&userType=${userType}'"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreateSSORedirectTemplateAction.Result res = action.call()

DeleteSSORedirectTemplate

API Request

URLs

POST zstack/v1/delete/sso/redirect/template

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "uuid": "9df30dceb13a3989aa3bfa20051bae9a",
    "deleteMode": "Permissive"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"uuid":"9df30dceb13a3989aa3bfa20051bae9a","deleteMode":"Permissive"}}' \
http://localhost:8080/zstack/v1/delete/sso/redirect/template

Parameter List

Name	Type	Location	Description	Starting Version
uuid	String	body (enclosed in the `params` structure)	Template UUID. Uniquely identifies the resource.	4.3.0
deleteMode (Optional)	String	body (enclosed in the `params` structure)	Deletion mode (Permissive / Enforcing, Permissive)	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

This API returns an empty JSON structure {} on success. On failure, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK

DeleteSSORedirectTemplateAction action = new DeleteSSORedirectTemplateAction();
action.uuid = "9df30dceb13a3989aa3bfa20051bae9a";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteSSORedirectTemplateAction.Result res = action.call();

Python SDK

DeleteSSORedirectTemplateAction action = DeleteSSORedirectTemplateAction()
action.uuid = "9df30dceb13a3989aa3bfa20051bae9a"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteSSORedirectTemplateAction.Result res = action.call()

UpdateSSORedirectTemplate

API Request

URLs

POST zstack/v1/update/sso/redirectTemplate

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "uuid": "35cc6909f0f23e55a209cd552d8bc938",
    "redirectTemplate": "http://zstack.com/userinfoUrl"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields are optional. They are listed here to show that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"uuid":"35cc6909f0f23e55a209cd552d8bc938","redirectTemplate":"http://zstack.com/userinfoUrl"}}' \
http://localhost:8080/zstack/v1/update/sso/redirectTemplate

Parameter List

Name	Type	Location	Description	Starting Version
uuid	String	body (enclosed in the `params` structure)	Template UUID. Uniquely identifies the resource.	4.3.0
redirectTemplate	String	body (enclosed in the `params` structure)	Redirect template	4.3.0
systemTags (Optional)	List	body	System tags	4.3.0
userTags (Optional)	List	body	User tags	4.3.0

API Response

Response Example

{
  "inventory": {
    "uuid": "43679041066d37b28f676a49851ade69",
    "clientUuid": "3e5541e27b9c320fa4ad0a86777cc5ab",
    "redirectTemplate": "http://zstack.com/code"
  }
}

Name	Type	Description	Starting Version
success	boolean	Whether the update is successful	4.3.0
inventory	SSORedirectTemplateInventory	For details, see inventory	4.3.0
error	ErrorCode	Error code. If not null, the operation has failed. This field is null when the operation succeeds. For details, see error	4.3.0

#inventory

Name	Type	Description	Starting Version
uuid	String	Template UUID. Uniquely identifies the resource.	4.3.0
name	String	Template name	4.3.0
description	String	Detailed description of the template	4.3.0
clientUuid	String	UUID of the corresponding SSO client, which is the UUID of the third-party account source	4.3.0
redirectTemplate	String	Redirect template	4.3.0
createDate	Timestamp	Creation time	4.3.0
lastOpDate	Timestamp	Last modification time	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code number. The globally unique identifier of the error, for example, SYS.1000 or HOST.1001.	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. Default is null.	0.6
opaque	LinkedHashMap	Reserved field. Default is null.	0.6
cause	ErrorCode	Root error. The source error that caused the current error. This field is null if no root error exists.	0.6

SDK Examples

Java SDK

UpdateSSORedirectTemplateAction action = new UpdateSSORedirectTemplateAction();
action.uuid = "35cc6909f0f23e55a209cd552d8bc938";
action.redirectTemplate = "http://zstack.com/userinfoUrl";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateSSORedirectTemplateAction.Result res = action.call();

Python SDK

UpdateSSORedirectTemplateAction action = UpdateSSORedirectTemplateAction()
action.uuid = "35cc6909f0f23e55a209cd552d8bc938"
action.redirectTemplate = "http://zstack.com/userinfoUrl"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateSSORedirectTemplateAction.Result res = action.call()

GetSSOClient

Get SSO Client

API Request

URLs

GET zstack/v1/get/sso/client

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" -X GET http://localhost:8080/zstack/v1/get/sso/client?

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
systemTags (Optional)	List	query	System tags		4.3.0
userTags (Optional)	List	query	User tags		4.3.0

API Response

Response Example

{
  "inventories": [
    {
      "uuid": "ff0df349f4d13f4081d57b3715851900",
      "name": "Test-ldap",
      "description": "some descriptions",
      "type": "OAuth2",
      "createAccountStrategy": "CreateDisabledAccount",
      "updateAccountStrategies": [
        "AccountStateKeepSameWithSource"
      ],
      "deleteAccountStrategy": "StaleAccount",
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}

Name	Type	Description	Starting Version
success	boolean	Whether the get operation succeeded	4.3.0
error	ErrorCode	For details, see error	4.3.0
inventories	List	For details, see inventories	4.3.0

#error

Name	Type	Description	Starting Version
code	String	Error code, which globally and uniquely identifies the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Summary description of the error	0.6
details	String	Details of the error	0.6
elaboration	String	Reserved field. The default value is null	0.6
opaque	LinkedHashMap	Reserved field. The default value is null	0.6
cause	ErrorCode	Root error that caused the current error. This field is null if there is no source error	0.6

SDK Examples

Java SDK

GetSSOClientAction action = new GetSSOClientAction();
GetSSOClientAction.Result res = action.call();

Python SDK

action = GetSSOClientAction()
res = action.call()

GetOAuthClientSecret

API Request

URLs

GET zstack/v1/oauth2/clients/{uuid}/client-secret

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/oauth2/clients/d734cef1f11137e3954f73fc337474ab/client-secret

Parameters

Name	Type	Location	Description	Since
uuid	String	url	OAuth2 client UUID	5.0.0
systemTags (optional)	List	query	System tags	5.0.0
userTags (optional)	List	query	User tags	5.0.0

API Response

Response Example

{
  "clientSecret": "exampleClientSecret"
}

Name	Type	Description	Since
success	boolean	Whether the get operation succeeded	5.0.0
clientSecret	String	Client Secret of the OAuth2 client	5.0.0
error	ErrorCode	Error code. If this field is not null, the operation failed. If the operation succeeds, this field is null. For details, see error	5.0.0

#error

Name	Type	Description	Since
code	String	Error code, a globally unique identifier of the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Brief description of the error	0.6
details	String	Detailed information about the error	0.6
elaboration	String	Reserved field. The default value is null	0.6
opaque	LinkedHashMap	Reserved field. The default value is null	0.6
cause	ErrorCode	Root error, which is the source error that caused the current error. If there is no source error, this field is null	0.6

SDK Example

Java SDK

GetOAuthClientSecretAction action = new GetOAuthClientSecretAction();
action.uuid = "d734cef1f11137e3954f73fc337474ab";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetOAuthClientSecretAction.Result res = action.call();

Python SDK

action = GetOAuthClientSecretAction()
action.uuid = "d734cef1f11137e3954f73fc337474ab"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

PreviousUser Configuration NextSecurity Settings Interfaces