Software Developer�s Guide for the Cisco Secure Access Control System 5.3
Using the REST Web Services
Downloads: This chapterpdf (PDF - 159.0KB) The complete bookPDF (PDF - 3.28MB) | Feedback

Using the Configuration Web Services

Table Of Contents

Using the Configuration Web Services

Supported Configuration Objects

Identity Groups

Attribute Info

Group Associations

Query Object

Filtering

Sorting

Paging

Request Structure

URL Path

HTTP Methods

Response Structure

HTTP Status Codes

ACS REST Result

Returned Objects

WADL File

Schema File

Sample Code


Using the Configuration Web Services


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:

acs config-web-interface rest enable

For more information on the acs config-web-interface command, refer to

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_system/5.3/command/
reference/cli_app_a.html#wp1887278
.

Viewing the Status of the REST Web Interface from ACS CLI

To view the status of the web interface, from the ACS CLI, enter:

show acs-config-web-interface

For more information on the show acs-config-web-interface command, refer to

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_system/5.3/command/reference/cli_app_a.html#wp1890877.

Application that interacts with 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 done by the REST client.

Supported Configuration Objects

The Rest PI in ACS provides services for configuring ACS and it is organized for each configuration feature. In ACS 5.3, the following two subsets of the ACS configuration are supported.

Common configuration objects

Identity configuration objects

Table 4-1 lists the supported configuration objects.

Table 4-1 Supported Configuration Objects 

Feature
Main Supported Classes
Comments

Common

Attribute Info

Also known as dynamic attributes or AV pair. Attribute Info is composed within Protocol User.

ACS Version

Supports Get method only.

Service Location

Supports getall method only.

It allows to find the ACS instance that serve as primary and the ACS instance that provide Monitoring and Troubleshooting Viewer.

Error Message

Supports getall method only.

It allows to retrieve all ACS message codes and message texts that are used on the REST Interface.

Identity

Protocol User

Full CRUD (Create, Read, Update, and Delete) and query support.

Identity Group

Full CRUD and query support.

Query is used to retrieve subgroups of a specific node. The list of users for each group is fetched by querying on the users.


This section contains:

Identity Groups

Attribute Info

Group Associations

Identity Groups

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 child of 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:

User user = new User();
        user.setDescription(description);
        user.setPassword(password);
        user.setName(userName);        
                user.setAttributeInfo(new AttributeInfo[]{
        		new AttributeInfo("Department","Dev"),
        		new AttributeInfo("Clock","10 Nov 2008 12:12:34")
        	});

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 user to an identity group:

User user = new User();
        user.setIdenityGroupName("IdentityGroup:All Groups:Foo");
        user.setDescription(description);
        user.setPassword(password);
        user.setName(userName);        

Query Object

The REST Interface schema exposes a query object to define criteria and other query parameters. The query object is used for users and identity groups.

The query object includes parameters that apply to:

Filtering

Sorting

Paging

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

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 the XML based example for the "And" filter.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <ns2:query xmlns:ns2="query.rest.mgmt.acs.nm.cisco.com">
             <criteria 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="ns2:AndFilter">
                    <simpleFilters>
                          <propertyName>name</propertyName>
                          <operation>STARTS_WITH</operation>
                          <value>user</value>
                    </simpleFilters>
                    <simpleFilters>
                          <propertyName>name</propertyName>
                          <operation>ENDS_WITH</operation>
                          <value>1</value>
                    </simpleFilters>
             </criteria>
             <numberOfItemsInPage>100</numberOfItemsInPage>
             <startPageNumber>1</startPageNumber>
     </ns2:query>
 
   

Here is a Java based example for the `And' filter:

 
   
                  Query query = new Query();
                  query.setStartPageNumber(1);
                  query.setNumberOfItemsInPage(100);
 
   
                  SimpleFilter simpleFilter = new SimpleFilter();
                  simpleFilter.setOperation(FilterOperation.STARTS_WITH);
                  simpleFilter.setPropertyName("name");
                  simpleFilter.setValue("user");
 
   
                  SimpleFilter simpleFilter1 = new SimpleFilter();
                  simpleFilter1.setOperation(FilterOperation.ENDS_WITH);
                  simpleFilter1.setPropertyName("name");
                  simpleFilter1.setValue("1");
 
   
                  AndFilter andFilter = new AndFilter();
                  andFilter.setSimpleFilters(new SimpleFilter[] { simpleFilter,
                              simpleFilter1 });
 
   
                  query.setCriteria(andFilter);

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.

Request Structure

ACS REST request is composed of:

URL

HTTP method

Content—Includes ACS objects if applicable to the requested method. The ACS objects are represented in XML.

URL Path

URL includes:

Service name: Rest

Package name: Identity or Common

Object Type: User, Identity Group, and so on

Object Identifier are valid with 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. Basic object key is the object name. You can also use Object ID for GET and Delete method. For POST and PUT, the method gets the object itself that includes the identifiers.

You can specify 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}S

For single instance per object type, no key is required — For example: REST/Commom/AcsVersion

Table 4-2 URL Summary Table 

Object
URL
Comment

ACS Version

../Rest/Common/AcsVersion

Single object exists

Service Location

../Rest/Common/ServiceLocation

Error Message

../Rest/Common/ErrorMessage

User

../Rest/Identity/User/.....

For some methods, there is additional data on the URL. See Table 4-3

Identity Group

../Rest/Identity/IdentityGroup/.....

For some methods, there is additional data on the URL. See Table 4-3


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

Table 4-3 HTTP Method Summary 

Function
HTTP Method
URL
Request content
Response on Success

getAll

GET

/{ObjectType}

None

Collection of Objects

getByName

GET

/{ObjectType}/name/
{name}1

None

An Object

getById

GET

/{ObjectType}/id/{id}

None

An Object

create

POST

/{ObjectType}

Object

Note For create, the Object ID property should not be set.

Rest Response Result, which includes Object ID.

delete

DELETE

/{ObjectType}/name/
{name}1

None

Rest Result

delete

DELETE

/{ObjectType}/ id/{id}

None

Rest Result

update2

PUT

/{ObjectType}

Object

Rest Result

Query

PUT

/{ObjectType}/op/query

QueryObject

List of Objects

1 Names in the URL are full names. ACS REST services does not support wildcards or regular expressions.

2 Update method replaces the entire object with the object provided in the request body, with the exception of sensitive properties.



Note For the responses on failure, see ACS REST Result.


Response Structure

The response to Rest request is a standard HTTP response that includes HTTP status code and other data 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 know the type of objects expected in the response body.

For 4xx HTTPS status codes except for 401 and 404, REST result Object is returned.

For 5xx status codesother than 500, the message content includes a text that describe the server error.

For 500 HTTP status code, REST result is returned.

For 200 and 201 HTTP status code, objects per the specific method or object type is returned.

For 204 HTTP status code, no object is returned.

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.

Table 4-4 Usage of HTTP Status Codes 

Status Code
Message
Usage in ACS
Comment

200

Ok

Successful Get, create and query

204

OK with no content

Successful delete and update

No data is returned in the response body.

400

Bad Request

Request errors: Object validation failure, XML syntax error, and other error in request message

The request contains bad syntax or cannot be executed.

For example, if you try to create an object with a name that already exists, the object validation fails.

Detailed reasons can be found in the REST result object.

401

Unauthorized

Authentication Failure/ Time outs

Similar to 403 error, but specifically for use when authentication failed or credentials are not available.

403

Forbidden

ACS is a secondary and can not fulfill the request or operation is not allowed per administrator authorizations.

The request was valid, but the server refuses to respond to it.

Unlike a 401 error, authenticating will make no difference. Also, this error is displayed when an non-read request was send to a secondary instance.

404

Not Found

For cases where the URL is wrong or the REST Service is not enabled.

410

Gone

A resource is not available anymore

A request was made for an object that does not exist. For example, deleting an object that does not exist.

500

Internal Server Error

For any Server error that has no specific HTTP Code.


ACS REST Result

The HTTP response for a REST request includes either requested objects or 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.

WADL File

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/

To download the WADL files:


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.


Schema File

ACS is shipped with three XSD files that describe the structure of the objects supported on ACS 5.3 REST interfaces.

The three XSD files are:

Common.xsd, that describes the following objects:

Version

AttributeInfo

Error Message

ResultResult, RestCreateResult

BaseObject

Service Location

Status

RestCommonOperationType

Identity.xsd, that describes the following objects:

Users

IdentityGroup

Query.xsd, that describes the structure of query objects.

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 generated from the XSD files.


Note It is highly recommended to generate REST client classes from the XSD files than coding XML or creating it manually.


Sample Code

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:

Get ACS Version

Get all users

Get All Service Locations

Get Filtered list of Users

Get list of Error messages

Get User by ID and by name

Create, Delete, Update user

Create, Delete, and Update identity group

Get IdentityGroup by name or ID

Get sub-tree of IdentityGroups

Get all Users of an Identity Group