This section contains the following information:
Setting Up Bulk Access for Endpoints and Guest Accounts
The ClearPass Configuration Application Programming Interface (API) is used to read and write a number of configuration elements (known as Entities), either programmatically or by using a script.
The ClearPass Configuration API allows you to configure or modify the entities in ClearPass without logging into the Admin user interface. For example, when you create a new user in the database, you may want to create a guest user automatically. You can use the ClearPass Configuration API to automate this task.
The API is made available through an HTTP POST-based mechanism. The API request is in the form of an XML snippet that is posted to a URL hosted by an administration server on the ClearPass Policy Manager server.
The API response received is also in the form of an XML snippet. Both the XML request and the XML response are structurally defined in an XSD-format file.
, , and operations are supported in the ClearPass Configuration API. These operations are referred to as "methods." You can use these methods to perform the following name-list based operations:
. Returns the list of names for all objects created for an Entity type.
. Receives a list of names of Entity type objects and applies the new order to the list of objects.
. Retrieves the name-list of disabled and enabled entities of a specific type and changes the status of the entities appropriately.
Every XML request must conform to the ClearPass Configuration API XML schema.
Only the configured Admin users can use API access. Rather than using the default user account, it is recommended that you create a separate user for API access.
To create a new user for API access, update the password of the default user account or create a new Admin user with only API access privileges.
This ensures that all API actions are tracked through the page for this user account.
Additionally, restrictions to specific entities can be enforced by defining a custom admin privilege level and creating API admin users with that privilege level. This ensures that the API account included in client scripts secure the confidential information in the system.
The following elements define the structure of XML data:
: The root element is <TipsApiRequest> for a request and <TipsApiResponse> for a response.
: <TipsHeader> describes the version (for example 3.0). The is the container object that can be controlled by adding and modifying attributes. The sub-element in the XML request contains only the version number; the sub-element in the XML response contains the version number, time of execution (exportTime), and entity types.
: Describes the child elements of XML data that are known the . The body contains the elements in the XML request and a list of objects in the XML response.
Figure 1 describes the structure of XML data in an XML request:
Figure 1 Structure of an XML Request
Figure 2 describes the structure of XML data in an XML response:
Figure 2 Structure of an XML Response
Use the element to fetch a list of objects of a specific entity. You can use a filter to perform and operations.
A filter contains a element that includes the following:
: Specifies the name of the field present in XML that needs to be filtered.
: Specifies the string that is used to match the filter during a match of the filter.
: Specifies the operator to be used.
For example, the match operator equals/matches the value of the field in the Entity object using .
The following is an example of an XML request that contains a filter on a Guest user with a criteria to fetch Guest users that match the name .
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiRequest xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader version="3.0" source="Guest"/>
<Filter entity="GuestUser">
<Criteria fieldName="name" filterString="McIntosh" match="equals"/>
</Filter>
</TipsApiRequest>
When you specify multiple filters, the result can be a combination of the list of elements of all of the filter criteria. For criteria, specify the nested criteria as . For match any criteria, multiple filters with criteria can be specified for the Entity type. If a criteria is not specified, then the operation fetches all objects of the Entity type.
|
|
Because the number of entities and the associated tag attributes with each entity can impact performance, the complex query supported in the Advanced Match Operations should be used with care. |
You can use the API to query based on tag attributes when the queries are not repeated.
With the XML request and response examples given in this section, you can use the operation to fetch all objects of an Entity type.
The following example describes the XML request that fetches all network devices with the IP address 192.0.2.10 and vendor IETF:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiRequest xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader version="3.0"/>
<Filter entity="NadClient">
<Criteria fieldName="ipAddress" filterString="192.0.2.10" match="contains">
<MoreFilterConditions fieldName="name" fieldValue="IETF" match="equals"/>
</Criteria>
</Filter>
</TipsApiRequest>
The following entity types support tag attributes:
Endpoint
Device
GuestUser
LocalUser
To filter based on the tag attributes, include an additional attribute called for that filter condition as described in the following example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiRequest xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader version="3.0"/>
<Filter entity="NadClient">
<Criteria fieldName="ipAddress" filterString="192.0.2.10" match="contains">
<MoreFilterConditions fieldName="TagName" fieldValue="TagValue" match="equals"
dataType="ATTRIBUTE"/>
</Criteria>
</Filter>
</TipsApiRequest>
The following match operators are supported in a criteria:
: The value of fieldname matches the filterString exactly.
: The value of fieldname does not exactly match the filterString
: The value of fieldname partially matches with the filterString, whic is case sensitive
: The case insensitive version of .
: The value of fieldname is one of the values specified in the filterString, which can be comma separated in this case.
Depending on the deployment, entities such as Endpoints and Guest users can grow to many thousands. These entities support tag attributes, which are custom key-value pairs added by the system or the Administrator that provide more context to the entity.
|
|
A bulk query to fetch all the details of the endpoints or Guest users in the system can impact system performance. For better query performance and minimal load on the system, we recommends that you use the bulk query cautiously. |
Alternatively, you can primarily use the NameList query followed by a query on individual details for each name present in the NameList. The NameList response depends on the specific endpoint.
Use the following command to fetch the list of MAC addresses for the endpoints present in the system:
The following is an example of the XML request for the Namelist method:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiRequest xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader version="3.0"/>
<EntityNameList entity="Endpoint"/>
</TipsApiRequest>
The following is an example of the Namelist method XML response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiResponse xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader exportTime="Mon Aug 22 13:37:13 PST 2016" version="6.x"/>
<StatusCode>Success</StatusCode>
<EntityNameList entity="Endpoint">
<Name>000c29eff62f</Name>
<Name>001122aabbcc</Name>
</EntityNameList>
</TipsApiResponse>
Use the following command to fetch the list of endpoints for a specific MAC address:
The following is an example of the Namelist method XML response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TipsApiResponse xmlns="http://www.avendasys.com/tipsapiDefs/1.0">
<TipsHeader exportTime="Mon Aug 22 14:50:09 PST 2016" version="6.x"/>
<StatusCode>Success</StatusCode>
<EntityMaxRecordCount>1</EntityMaxRecordCount>
<Endpoints>
<Endpoint macAddress="000c29eff62f" status="Known"/>
<EndpointTags tagValue="true" tagName="Encryption Enabled"/>
<EndpointTags tagValue="PDA 2" tagName="Phone Number"/>
<EndpointTags tagValue="MobileIron" tagName="Source"/>
<EndpointTags tagValue="3fbe0a80-e7d2-4048-bd2e-62aec232a236" tagName="MDM Identifier"/>
<EndpointTags tagValue="Bala" tagName="Display Name"/>
<EndpointTags tagValue="iPad 2" tagName="Model"/>
<EndpointTags tagValue="true" tagName="MDM Enabled"/>
<EndpointTags tagValue="balu" tagName="Owner"/>
<EndpointTags tagValue="Installed" tagName="Required App"/>
<EndpointTags tagValue="b786da8ca3969e0134f058ca5efe94687ab7f31f" tagName="UDID"/>
<EndpointTags tagValue="iOS 9.3" tagName="OS Version"/>
<EndpointTags tagValue="PDA" tagName="Carrier"/>
<EndpointTags tagValue="false" tagName="Compromised"/>
<EndpointTags tagValue="Corporate" tagName="Ownership"/>
<EndpointTags tagValue="false" tagName="Blacklisted App"/>
<EndpointTags tagValue="Apple" tagName="Manufacturer"/>
</Endpoint>
</Endpoints>
</TipsApiResponse>