This chapter describes the environment that you must set up to use the Configuration web service and explains how to use it.
The Configuration web services are implemented as REST interfaces over HTTPS. There is no HTTP support.
Configuring REST web services are available on all ACS servers in the deployment, but only the ACS primary instance provides the full service that supports read and write operations. Secondary ACS instances provide read only access to the configuration data.
The Monitoring and Report Viewer displays the messages and audit logs for all REST activities.
Enabling the REST Web Interface on ACS CLI
You must enable the web interface on ACS before you can use the REST web service. To enable the web interface on ACS, from the ACS CLI, enter:
For more information on the acs config-web-interface command, see CLI Reference Guide for Cisco Secure Access Control System 5.6.
Viewing the Status of the REST Web Interface from ACS CLI
To view the status of the web interface, from the ACS CLI, enter:
For more information on the acs config-web-interface command, see CLI Reference Guide for Cisco Secure Access Control System 5.6.
Applications that interact with the ACS configuration REST service may use any administrator account to authenticate to the REST service. Authorization for the used account should be set to allow all activities that are done by the REST client.
The Rest PI in ACS provides services for configuring ACS, and it is organized for each configuration feature. In ACS 5.6, the following five subsets of the ACS configuration are supported:
Table 4-1 lists the supported configuration objects.
The Identity Group object is used to manipulate nodes on the Identity Group hierarchy. The group name defines the full path of the node within the hierarchy. When you add a new node, you should be aware that the name of the node (which includes the full path) specifies where in the hierarchy the node should be attached. For example:
Note You must create the upper level hierarchy (parent node) and then create the leaf node.
For example: To create the hierarchy, All Groups:US:WDC; we must create All Groups:US and then go ahead creating the next level in hierarchy.
In order to retrieve the child of a certain group, you can set a filter as “start” with All groups:CDO”.
The AttributeInfo structure is an array of pairs of attribute names and attribute values.
The attribute name refers to the user dictionary, where the definition of the attribute, such as value type, can be found. The value of the attribute must conform with the dictionary definition.
The following is an example of JAVA representation for a user that has two attributes:
The REST Interface schema shows the association of the user to the Identity group, as a group name property on the user object.
Here is an example of associating a user to an identity group:
The following is an example of a Java representation for the configuration of a network device group and information that is related to creating a network device. It is also a good example of using a GroupInfo object to define device groups.
To create a single IP without mask or ranges, you need to just create the IPSubnetType and associate the subnet to that object, as shown in the above example.
Note It is mandatory to provide information about at least one group to which the network device is associated while updating a network device using the REST interface. The network device may be associated with more than one group. The group information that is not provided will automatically be updated with a default value.
The REST Interface schema exposes a query object to define criteria and other query parameters. The query object is used for Users, Identity Groups, Network Device, Network Device Groups, Internal Hosts, and Maximum User Sessions.
The query object includes parameters that apply to:
You can use the query object to retrieve a filtered result set. You can filter users or identity groups, based on the following criteria:
The following operations are supported for filtering:
Here is an XML-based example for the “And” filter.
Note The XML tag
numberOfItemsInPage
has been changed to numberofItemsInPage
(from upper case "O" to lower case "o") in patch 3. You need to install patch 3 to get this change reflected in ACS.
Here is a Java-based example for the “And” filter:
You can use the query object to sort the results. You can sort based on the following criteria:
You can set the query object with the following paging parameters:
Paging is stateless. That is, the required page is calculated from scratch for every request. This means that paging could skip objects or return them twice, in case objects were added or deleted concurrently.
ACS REST request is composed of:
Table 4-2 lists the URLs for each object.
Objects are identified by name or by object ID. The basic object key is the object name. You can also use the Object ID for the GET and DELETE methods. For POST and PUT, the method gets the object itself, which includes the identifiers.
You can specify the identifier on the URL in the following ways:
For example: REST/Common/AcsVersion
|
|
|
---|---|---|
For some methods, there is additional data on the URL. See Table 4-3 |
||
For some methods, there is additional data on the URL. See Table 4-3 |
||
For some methods, there is additional data on the URL. See Table 4-3 |
||
For some methods, there is additional data on the URL. See Table 4-3 |
||
For some methods, there is additional data on the URL. See Table 4-3 |
HTTP methods are mapped to configuration operations (CRUD - Create, Read, Update, and Delete).
The common intrinsic methods are not specified within the URL, and are determined by the HTTP request method. In other cases, you need to add the configuration operation into the URL. HTTP methods are mapped to ACS operations:
When the HTTP PUT method is used for operations other than CRUD, the URL specifies the required operation. This is also used to distinguish the message from the PUT method for update. The keyword “op” is included in the URL as follows:
Rest/{package}/{ObjectType}/op/{operation}
For example, /Rest/Identity/IdentityGroup/op/query
Table 4-3 describes the primary ACS REST methods and their mapping to HTTP messages.
|
|
|
|
|
---|---|---|---|---|
/{ObjectType}/name/ |
||||
/{ObjectType}/name/ |
||||
update 2 |
||||
Note The GET and DELETE methods using MAC addresses are applicable only for the Host object types. For example,
/Host/macaddress/{macaddress}
. The name attribute in these methods is replaced with MAC addresses. This is because of the Host object, which does not have the name attribute.
Note For the responses on failure, see ACS REST Result.
The response to REST request is a standard HTTP response that includes the HTTP status code and other data that is returned by web servers. In addition, the response can include the ACS REST result object or ACS configuration objects according to the type of request.
You should check the HTTP status code to find out the type of objects that are expected in the response body.
ACS returns the following types of status codes:
ACS does not return the following types of status codes:
The HTTP status code is returned within the HTTP response headers as well as within the REST result object.
Table 4-4 lists the HTTP status codes that are returned by ACS.
The HTTP response for a REST request includes either requested objects or a REST result object. See Table 4-3 for details. ACS result includes:
ACS returns objects for GET method and for query operation. The type of returned object is determined by the request URL.
When a GET method returns multiple objects, these are included in the response. If the returned list is too long, you should use filtering or paging options.
The WADL files contain the object structure (schema) and the methods for every object.
The WADL files are mainly documentation aids. You cannot generate client applications using WADL files.
The WADL file structure is according to W3C specification. For more information, see http://www.w3.org/Submission/wadl/
Step 1 From the ACS user interface, go to System Administration > Downloads > Rest Service
Step 2 Under ACS Rest Service WADL files, click Common or Identity and save the files to your local drive.
ACS is shipped with four XSD files that describe the structure of the objects that are supported on ACS 5.6 REST interfaces.
– ResultResult, RestCreateResult
You can download the schema files in the same way as you download the WADL files. You can use the schema with available tools such as JAXB to generate schema classes.
You can develop HTTP client or use any third-party HTTP client code and integrate it with the schema classes that are generated from the XSD files.
Note It is highly recommended to generate REST client classes from the XSD files rather than coding XML or creating it manually.
ACS provides sample code for client application to help you develop an application that interacts with ACS REST Interface. The sample code can be downloaded in the same way as WADL and schema files.
The sample code is based on Apache HTTP Client http://hc.apache.org/httpcomponents-client-ga/index.html and JAVA code generated by JAXB (xjc command) with the help of the XSD files. It includes sample codes for: