PUT /ldapClientSettings

Use this method to modify the client settings when an external LDAP server is used for authentication..

Authentication

Authentication with username and password is required.

Request URL

PUT https://{management_server_IP}/ldapClientSettings

Query parameters

None

Request body

Attributes		Required / Optional	Type	Description
bindingMethod		Required	String	Method that is used to bind XClarity Administrator to the external authentication server. This can be one of the following values. configured_credentials: Uses the credentials specified in the clientDn and clientPw attributes to bind to the specified LDAP authentication server. login_credentials: Uses the login credentials of the authenticating user to bind to the specified LDAP authentication server. The credentials specified in the existing clientDn and clientPw attributes are used to perform an initial test connection to the authentication server, but these values are not saved.
clientDn		Required if userAuthenticationMethod is set to ldap.	String	Distinguished name of the client
clientPw		Required if userAuthenticationMethod is set to ldap.	String	Client password value Note This attribute is required when userAuthenticationMethod is set to "ldap."
domainName		Required if serverSelectMethod is set to dns	String	Domain name used by DNS to locate LDAP servers
forestName		Optional	String	Forest name used by DNS to locate LDAP servers
groupFilters		Optional	String	Groups search filters to customize the authentication process when configuring XClarity Administrator with an external LDAP server For information about search filter syntax, see How to write LDAP search filters. For search filter examples, see Examples of Common ldapsearches
groupNameAttribute		Optional	String	Attribute name that is used to identify the group name that is configured by the LDAP server The default is uid.
groupSearchAttribName		Optional	String	Attribute name that is used to identify the groups to which a user belongs If this attribute is not specified, the default is memberOf.
rootDn		Optional	String	Root distinguished name with the topmost entry in your LDAP directory tree
searchLimit		Optional	Integer	Maximum number of in-search results that can be retrieved in an LDAP search operation using user and group filters This can be a value from 0 – 5000. The default value is 0, which means that the operation does not time out.
serverAddress		Required if serverSelectMethod is set to preconfigured.	Array of objects	Array of up to four LDAP server addresses and ports
	port	Required for specified entries	Integer	Port number of the server connection
	address	Required for specified entries	String	IP address for the server
serverSelectMethod		Required if userAuthenticationMethod is set to ldap.	String	Specifies how LDAP servers are to be selected. This can be one of the following values. preconfigured. The IP addresses or hostnames will be used for external authentication servers. dns. The domain name and optional forest name will be used to locate the domain controller (DC) and global catalog (GC) servers dynamically. Note This attribute is required when userAuthenticationMethod is set to "ldap."
sslEnabled		Required	Boolean	Indicates if SSL is enabled. This can be one of the following values. true. SSL is enabled. false. SSL is not enabled.
timeout		Optional	Integer	Amount of time, in seconds, to complete an LDAP search operation before timing out This can be a value from 0 – 300 (5 minutes). The default value is 0.
userAuthenticationMethod		Required	String	Type of user authentication. This can be one of the following values. local. Authentication is performed locally. ldap. Authentication is performed by an external LDAP server. ldap_local. Authentication is performed by an external LDAP server first. If that fails, authentication is performed locally. local_ldap. Authentication is performed locally first. If that fails, authentication is performed by an external LDAP server.
userFilters		Optional	String	Users search filters to customize the authentication process when configuring XClarity Administrator with an external LDAP server For information about search filter syntax, see How to write LDAP search filters. For search filter examples, see Examples of Common ldapsearches
userSearchAttribName		Optional	String	Attribute name that is used to identify the user IDs on the LDAP server When the binding method is set to Configured Credentials, the initial bind to the LDAP server is followed by a search request that retrieves specific information about the user, including the user's DN, login permissions, and group membership. This search request must specify the attribute name that represents the user IDs on that server. If this attribute is not specified, the default is cn.
useServersAsGlobalCatalogs		Optional	Boolean	Indicates whether to treat domain controllers as global catalogs. This can be one of the following values. true. (default) XClarity Administrator attempts to connect to the standard global-catalog port (3268 or 3269) on each known domain-controller address. If XClarity Administrator can bind to the port, the domain-controller server is treated as a global catalog, and XClarity Administrator uses the global catalog to locate additional user accounts during the authentication process. When a user account is located in the global catalog, XClarity Administrator connects to the domain-controller server that controls the domain in which the user exists to authenticate the user and obtain any domain local groups. XClarity Administrator can locate domain controllers that are not listed in the DNS as long as they are listed in the global catalog. false. XClarity Administrator does not attempt to connect to the global catalog port on each domain-controller address unless the user explicitly specified the server’s global-catalog port as one of the preconfigured servers in the serverAddress attribute. For example, if you set serverSelectMethod to `preconfigured`, serverAddress to `192.0.2.0` on port `389`, and useServersAsGlobalCatalogs to `false`, XClarity Administrator does not automatically attempt to connect to port 3268 on that server to determine whether it can function as a global catalog. However, if you specify two pre-configured servers in serverAddress, both with the same IP address `192.0.2.0` but different ports `389` and `3268`, XClarity Administrator connects to the second server as a global-catalog server because you explicitly requested XClarity Administrator to attempt to connect to that port. Setting useServersAsGlobalCatalogs to `true` allows you to specify the server only once.

The following example modifies the client LDAP settings.

{
   "bindingMethod": "configured_credentials",
   "clientDn": "userid",
   "clientPw": "Passw0rd",
   "domainName": "lenovo.com",
   "forestName": "forestName",
   "groupNameAttribute": "cn",
   "groupSearchAttribName": "memberOf",
   "rootDn": "rootDn",
   "serverAddress": [{
      "port": 1,
      "address": "1.1.1.1"
   },
   {
      "port": 2,
      "address": "2.2.2.2"
   },
   {
      "port": 3,
      "address": "3.3.3.3"
   },
   {
      "port": 4,
      "address": "4.4.4.4"
   }],
   "serverSelectionMethod": "dns",
   "sslEnabled": true,
   "userAuthenticationMethod": "ldap",
   "userSearchAttribName": "cn"
   "useServersAsGlobalCatalogs" : true
}

Response codes

Code	Description	Comments
200	OK	The request completed successfully.
400	Bad Request	A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body.
409	Conflict	There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500	Internal Server Error	An internal error occurred. A descriptive error message is returned in the response body.

Response body

Attributes			Type	Description
result			String	Results of the request. This can be one of the following values. success. The request completed successfully. failed. The request failed. A descriptive error message was returned. warning. The request completed with a warning. A descriptive error message was returned.
messages			Array of objects	Information about one or more messages
	id		String	Message identifier of a returned message
	text		String	Message text associated with the message identifier
	explanation		String	Additional information to clarify the reason for the message
	recovery		Array of objects	Recovery information
		text	String	User actions that can be taken to recover from the event
		URL	String	Link to the help system for more information, if available

The following example is returned if the request failed.

{
   "result": "failure",
   "messages": [{
      "id": "FQXHMSE0611J",
      "explanation": "The request to change the LDAP configuration could not complete for an unknown
                  reason.",
      "recovery": {
         "text": "Specify valid parameters on the request and try the request again. If the problem
                persists, contact Support.",
         "URL": ""
      },
      "text": "The request to change the LDAP configuration could not be completed successfully."
   }]
}

Give documentation feedback

PUT /ldapClientSettings

Authentication​

Request URL​

Query parameters​

Request body​

Response codes​

Response body​