Software Developer's Guide for Cisco Secure Access Control System 5.6

Identity Groups

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:

• All Groups:CDO:PMBU
• All Groups:CDO
• All Groups:CDO:PMBU:ACS-Dev

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

Attribute Info

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:

Group Associations

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:

Device Info

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.

Filtering

You can use the query object to retrieve a filtered result set. You can filter users or identity groups, based on the following criteria:

• Simple condition—Includes property name, operation, and value. For example, name STARTS_WITH "A".

The following operations are supported for filtering:

• CONTAINS
• DOES_NOT_CONTAIN
• ENDS_WITH
• IS_EMPTY
• EQUALS
• NOT_EMPTY
• NOT_EQUALS
• STARTS_WITH
• And condition— Includes set of simple conditions. All simple condition must be evaluated to be True in order for the and condition to be matched.

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:

Sorting

You can use the query object to sort the results. You can sort based on the following criteria:

• One property to sort by
• Direction of sorting (Ascending/Descending)

Paging

You can set the query object with the following paging parameters:

• Page number, which is the requested page
• Number of objects in a page

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.

URL Path

URL includes:

• Service name: Rest
• Package name: Identity, Common, or Network Device
• Object Type: User, Identity Group, and so on
• Object Identifiers are valid with the GET and DELETE methods.
• Operation name is required for operations other than CRUD, such as query.

Table 4-2 lists the URLs for each object.

Object Identifiers

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:

• Name as the key: Rest/{package}/{ObjectType}/name/{name}
• Object ID as the key: Rest//{package}/{ObjectType}/id/{id}
• For a single instance per object type, no key is required. For example: REST/Common/AcsVersion

HTTP Methods

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:

• HTTP GET—View an object or multiple objects.
• HTTP POST—Create a new object.
• HTTP DELETE—Delete a object.
• HTTP PUT—Update an existing object. PUT is also used to invoke extrinsic methods (other than CRUD).

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.

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.

HTTP Status Codes

ACS returns the following types of status codes:

• 2xx for success
• 4xx for client errors
• 5xx for server errors

ACS does not return the following types of status codes:

• 1xx
• 3xx

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.

ACS REST Result

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:

• HTTP status code
• HTTP status text
• ACS message code
• ACS message
• Object ID for successful CREATE method

Returned Objects

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.