GET /ldapClientSettings

Use the GET method to retrieve information about the client settings when an external LDAP server is used for authentication.

Authentication

Authentication with user name and password is required.

Request URL

GET https://<management_server_IP>/ldapClientSettings

Query parameters

Parameters Required / Optional Description
default=<Boolean> Optional Indicates whether default LDAP client settings are returned. This can be one of the following values.
  • true. Default settings are returned.

  • false. (default) Current values are returned.

The following example returns the default LDAP client settings.
GET https://192.0.2.0/ldapClientSettings?default=true

Response codes

Code Description
200 OK. The request completed successfully.
400 Bad request. An argument is missing or is not valid. A descriptive error message will be returned in the body.
500 Internal server error. A descriptive error message will be returned in the body.

Response body

Attributes Type Description
response Array of objects Information about each user account
  bindingMethod 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 String Distinguished name of the client
  clientPw Boolean Indicates if a client password is stored currently. This can be one of the following values.
  • true. There is currently a stored client password.
  • false. There is not currently a stored client password.
  domainName String Domain name used by DNS to locate LDAP servers
  forestName String Forest name used by DNS to locate LDAP servers
  groupNameAttribute String Attribute name that is used to identify the group name that is configured by the LDAP server

The default is uid.

  groupSearchAttribName String Attribute name that is used to identify the groups to which a user belongs

The default is memberOf.

  rootDn String Root distinguished name with the topmost entry in your LDAP directory tree
  serverAddress Array of objects Information about the server address
    address String IP address for the server
    port Integer Port number of the server connection
  serverSelectionMethod 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.
  sslEnabled Boolean Indicates if SSL is enabled. This can be one of the following values.
  • true. SSL is enabled.
  • false. SSL is not enabled.
  userAuthenticationMethod 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.
  userSearchAttribName 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.

The default is cn.

  useServersAsGlobalCatalogs 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.

result String Request results. This can be one of the following values.
  • success. The request completed successfully.
  • failure. The request failed. A descriptive error message was returned.
messages Array of objects Information about one or more messages
  explanation String Additional information to clarify the reason for the message
  id String Message identifier of a returned 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
  text String Message text associated with the message identifier

Response example

{
   "response": {
      "bindingMethod": "configured_credentials",
      "clientDn": "",
      "clientPw": false,
      "domainName": "",
      "forestName": "",
      "groupNameAttribute": "cn",
      "groupSearchAttribName": "memberOf",
      "rootDn": "",
        "serverAddress": [{
            "address": "1.1.1.1",
            "port": 1
        },
        {
            "address": "2.2.2.2",
            "port": 2
        },
        {
            "address": "3.3.3.3",
            "port": 3
        },
        {
            "address": "4.4.4.4",
            "port": 4
        }],
      "serverSelectionMethod": "preconfigured",
      "sslEnabled": true,
      "userAuthenticationMethod": "local",
      "userSearchAttribName": "cn"
   "useServersAsGlobalCatalogs" : true
   },
   "result": "success",
   "messages": [{
      "explanation": "",
      "id": "FQXHMSE0001I",
      "recovery": {
         "text": "Information only; no action is required.",
         "URL": ""
      },
      "text": "The request completed successfully."
   }]
}