Software Developer s Guide for Cisco Secure Access Control System 5.3

Transcription

1 Software Developer s Guide for Cisco Secure Access Control System 5.3 November 2012 Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax: Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface vii Audience vii How This Guide Is Organized vii Conventions iii-viii Documentation Updates ix Related Documentation ix Obtaining Documentation and Submitting a Service Request x CHAPTER 1 Overview 1-1 Understanding Web Services 1-2 Understanding WSDL 1-3 Understanding WADL 1-3 CHAPTER 2 Using the UCP Web Service 2-1 Understanding the Methods in the UCP Web Service 2-2 User Authentication 2-2 User Change Password 2-3 Using the WSDL File 2-4 Downloading the WSDL File 2-4 UCP WSDL File 2-4 Request and Response Schemas 2-7 User Authentication Request 2-7 User Authentication Response 2-7 User Change Password Request 2-7 User Change Password Response 2-7 Working with the UCP Web Service 2-7 Sample Client Code 2-8 CHAPTER 3 Using the Monitoring and Report Viewer Web Services 3-1 Understanding the Methods in the Viewer Web Services 3-2 Get Version 3-2 Get Authentication Status By Date 3-3 Get Authentication Status By Time Unit 3-3 iii

4 Contents Get Failure Reasons 3-4 Get RADIUS Accounting 3-4 Get API Version 3-5 Understanding the WSDL Files 3-5 Downloading the WSDL Files 3-6 Viewer WSDL Files 3-6 Integrating the Viewer Web Services with Your Application 3-9 Working with the Viewer Web Services 3-10 Required Files 3-11 Supported SOAP Clients 3-11 Connecting to the Viewer Web Services 3-11 Sample Client Code 3-12 CHAPTER 4 Using the Configuration Web Services 4-1 Supported Configuration Objects 4-1 Identity Groups 4-2 Attribute Info 4-3 Group Associations 4-3 Query Object 4-3 Filtering 4-3 Sorting 4-4 Paging 4-5 Request Structure 4-5 URL Path 4-5 HTTP Methods 4-6 Response Structure 4-7 HTTP Status Codes 4-7 ACS REST Result 4-9 Returned Objects 4-9 WADL File 4-9 Schema File 4-9 Sample Code 4-11 CHAPTER 5 Using the Scripting Interface 5-1 Understanding Import and Export in ACS 5-2 Importing ACS Objects Through the CLI 5-2 Exporting ACS Objects Through the CLI 5-3 Viewing the Status of Import and Export Processes 5-4 iv

5 Contents Terminating Import and Export Processes 5-5 Supported ACS Objects 5-5 Creating Import Files 5-7 Downloading the Template from the Web Interface 5-7 Understanding the CSV Templates 5-8 Creating the Import File 5-9 Adding Records to the ACS Internal Store 5-9 Updating the Records in the ACS Internal Store 5-10 Deleting Records from the ACS Internal Store 5-10 Using Shell Scripts to Perform Bulk Operations 5-11 Sample Shell Script 5-11 APPENDIX A Monitoring and Report Viewer Database Schema A-1 Configuring a Remote Database in ACS A-1 Understanding the Monitoring and Report Viewer Database Schema A-2 Raw Tables A-3 Aggregated Tables A-3 Microsoft SQL Server Schema A-4 Oracle Schema A-24 I NDEX v

6 Contents vi

7 Preface Welcome to the Software Developer Guide for the Cisco Secure Access Control System 5.3! This document provides details about the interfaces that Cisco Secure Access Control System (ACS) offers that you can use to interact with external customer-developed applications. This includes several web services for application access and scriptable access for bulk provisioning using the command-line interface (CLI). It also allows you to create a replica of the Monitoring and Troubleshooting database for application development. Audience This guide is intended for software engineers and programmers who create custom applications to interact with ACS. The software engineers and programmers must be familiar with: Web Services Description Language (WSDL) File Web Application Description Language (WADL) File Web Services Tools REST Services Tools How This Guide Is Organized Table 1 describes the contents of each chapter in this document. Table 1 Organization Chapter/ Appendix Title Description 1 Overview Provides an overview of the ACS 5.3 features in the form of web services. It also gives CLI commands that you can use in your custom applications to interact with ACS. 2 Using the UCP Web Service Describes the User Change Password web service, the methods that it provides, and how you can use it in your application. vii

8 Conventions Preface Table 1 Organization (continued) Chapter/ Appendix Title Description 3 Using the Monitoring and Report Viewer Web Services 4 Using the Configuration Web Services Describes the web services that the Monitoring and Report Viewer component of ACS provides, and it also explains how to use these web services in your application. Describes the Configuration Web Services, the CRUD methods that it provides, and explains how to use it in your application. 5 Using the Scripting Interface Describes the scripting interface that ACS provides. This interface allows you to perform bulk create, update, and delete operations on various ACS objects. A Monitoring and Report Viewer Database Schema Provides the Monitoring and Report Viewer database schema that allows you to create custom reporting applications. Conventions Table 2 describes the conventions followed in this document. Table 2 Conventions Convention bold font italic font Description Commands and keywords. Variables for which you supply values. [ ] Keywords or arguments that appear within square brackets are optional. {x y z } A choice of required keywords appears in braces separated by vertical bars. You must select one. [ x y z ] Optional alternative keywords are grouped in brackets separated by vertical bars. string Nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks. courier font Examples of information displayed on the screen. bold courier font Examples of information you must enter. < > Nonprinting characters, such as passwords, appear in angle brackets. [ ] Default responses to system prompts appear in square brackets.!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line. Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the manual. viii

9 Preface Conventions Timesaver Means the described action saves time. You can save time by performing the action described in the paragraph. Documentation Updates Table 3 Updates to the Software Developer s Guide for the Cisco Secure Access Control System 5.3 Date Description 10/04/2011 Cisco Secure Access Control System Release 5.3. Related Documentation Table 4 lists a set of related technical documentation available on Cisco.com. To find end-user documentation for all products on Cisco.com, go to: Note We sometimes update the printed and electronic documentation after original publication. Therefore, you should also review the documentation on Cisco.com for any updates. Table 4 Product Documentation Document Title Release Notes for the Cisco Secure Access Control System 5.3 User Guide for Cisco Secure Access Control Sytem, 5.3 Migration Guide for the Cisco Secure Access Control System 5.3 CLI Reference Guide for the Cisco Secure Access Control System 5.3 Installation and Upgrade Guide for the Cisco Secure Access Control System 5.3 Supported and Interoperable Devices and Softwares for the Cisco Secure Access Control System 5.3 Regulatory Compliance and Safety Information for Cisco Identity Services Engine, Cisco 1121 Secure Access Control System, Cisco NAC Appliance, Cisco NAC Guest Server, and Cisco NAC Profiler Available Formats prod_release_notes_list.html products_user_guide_list.html prod_installation_guides_list.html prod_command_reference_list.html prod_installation_guides_list.html products_device_support_tables_list.html cisco_secure_access_control_system/5.1/ regulatory/compliance/csacsrcsi.html ix

10 Conventions Preface Table 4 Product Documentation (continued) Document Title License and Documentation Guide for the Cisco Secure Access Control System 5.3 Open Source and Third Party Licenses used in Cisco Secure Access Control System, 5.3 Available Formats products_documentation_roadmaps_list.html products_licensing_information_listing.html Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: Subscribe to the What s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS Version 2.0. x

11 CHAPTER 1 Overview The Cisco Secure Access Control System (ACS) is a policy-based access control system and an integration point for network access control and identity management. ACS 5.3 provides web services and command-line interface (CLI) commands that allow software developers and system integrators to programmatically access some ACS features and functions. ACS 5.3 also enables you to access to the Monitoring and Report Viewer database that you can use to create custom applications to monitor and troubleshoot ACS. You can use these web service and CLI commands to: Integrate external applications directly with ACS. View and modify the information stored in ACS. The User Change Password (UCP) web service allows users, defined in the ACS internal database, to first authenticate and then change their own password. ACS exposes the UCP web service to allow you to create custom web-based applications that you can deploy in your enterprise. The Monitoring and Report Viewer web services allow you to create custom applications to track and troubleshoot events in ACS. ACS REST web services allows you to manage the entities such as users and user groups only on your own management applications and use ACS PI to transfer these entities into ACS. This allows you to define these entities and use them on your own systems and on ACS. The scripting interface in ACS allows you to perform create, read, update, and delete (CRUD) operations on ACS objects. You can create an automated shell script to perform bulk operations. ACS allows you to export data from the Monitoring and Report Viewer database. You can use this data to create custom reporting applications. Appendix A, Monitoring and Report Viewer Database Schema in this document contains the Monitoring and Report Viewer database schema to help you create your custom application. ACS 5.3 provides: UCP web service to perform the following operations: Authenticate User Change User Password Monitoring and Report Viewer web services that provide: Monitoring and Report Viewer version Monitoring and Report Viewer web services version Authentication status of a user by date Authentication status of a user by time 1-1

12 Understanding Web Services Chapter 1 Overview A list of records that give the reasons for failures A list of RADIUS accounting records Configuration web services to perform the following operations: Create, read, update and delete objects, including creating and removing any associations to the objects Get a list of objects of the same type (For example, a list of all Users) Retrieve associated objects, including filtering capabilities Execute queries CLI commands to perform bulk operations on ACS objects for the following functions: Import Export You can perform bulk operations on the following ACS objects users, hosts, network devices, identity groups, network device groups (NDGs), downloadable access control lists (DACLs), and command sets. Before you begin to use the ACS web services and CLI commands in scripts, you must have a working knowledge of: Web Services Description Language (WSDL) File Web Application Description Language (WADL) File Web Services Tools This chapter contains the following sections: Understanding Web Services, page 1-2 Understanding WSDL, page 1-3 Understanding Web Services Web services are a subset of web-based applications that use the XML protocol to exchange data between the client and the server. Web services use: Hyper Transfer Protocol Secure (HTTPS) Transports messages between client applications and the web service server. Simple Object Access Protocol (SOAP) Encodes messages in a common XML format so that they can be understood at either end (web service consumer and web service server) of a network connection. SOAP standardizes the format of the requests to the web service server. Any client application can interface with the ACS web server using SOAP over HTTPS. WSDL file Describes the web service, its location, and its operations. ACS 5.3 exposes the following WSDL files: UCP WSDL Monitoring and Report Viewer WSDL Representational State Transfer (REST) REST is a software architecture style for distributed systems. ACS Configuration web services are built using the REST architecture. This service provides a uniform set of operations for all resources. 1-2

13 Chapter 1 Overview Understanding WSDL RESTful web services typically map the four main HTTP methods; POST, GET, PUT, and DELETE to common operations; that is, create, retrieve, update, and delete, respectively. WADL file Describes the REST interface. This includes description of objects and methods for the REST interface. Understanding WSDL The Web Services Definition Language (WSDL) is an XML format that describes network services as a collection of ports that operate on messages. WSDL is extensible to allow the description of endpoints and their messages, regardless of the message formats or network protocols that you use. For more information on WSDL documentation and software downloads, refer to the World Wide Web Consortium website. Note You can use any third-party applications to transform your WSDL file. Understanding WADL The Web Application Description Language (WADL) file describes REST Interface schema (object structure), HTTP methods, and URLs that are available for each object to invoke REST request. The WADL files are designed to provide a machine processable description of HTTP based web applications. They are supplemented with XML schema for XML based data formats. ACS also provides XSD files that describe the objects structure. You can generate object classes out of XSD files, using third party tools. 1-3

14 Understanding WADL Chapter 1 Overview 1-4

15 CHAPTER 2 Using the UCP Web Service This chapter describes the environment that you must set up to use the User Change Password (UCP) web service and explains how you can use it. The UCP web service allows you to authenticate an internal user and change the internal user password. You can use this web service interface to integrate ACS with your in-house portals and allow users in your organization to change their own passwords. The UCP web service allows only the users in your organization to change their passwords. They can do so on the primary or secondary ACS servers. The UCP web service compares the new password that you provide with the password policy that is configured in ACS for users. If the new password conforms to the defined criteria, your new password takes effect. After your password is changed on the primary ACS server, ACS replicates it to all the secondary ACS servers. The Monitoring and Report Viewer provides a User_Change_Password_Audit report that is available under the ACS Instance catalog. You can generate this report to track all changes made to user passwords in the internal database, including the changes made through the UCP web service. You can use this report to monitor usage and failed authentications. Enabling the Web Interface on ACS CLI You must enable the web interface on ACS before you can use the UCP web service. To enable the web interface on ACS, from the ACS CLI, enter: acs config-web-interface ucp enable For more information on the acs config-web-interface command, refer to reference/cli_app_a.html#wp Viewing the Status of the 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 reference/cli_app_a.html#wp This following sections describe how to use the UCP web service: Understanding the Methods in the UCP Web Service, page 2-2 Using the WSDL File, page 2-4 Working with the UCP Web Service, page

16 Understanding the Methods in the UCP Web Service Chapter 2 Using the UCP Web Service Understanding the Methods in the UCP Web Service The UCP web service comprises the following methods: User Authentication, page 2-2 User Change Password, page 2-3 User Authentication The User Authentication method authenticates a user against an internal database. Input Parameters Username Password Purpose Use the authenticateuser method for applications that require a two-step procedure to change a user password. For example, a ACS user interface application that prompts the user to change the password, does it in two steps: 1. It authenticates the user 2. It changes the user password. To change a password: Step 1 Step 2 Connect to the UCP web application A login page appears. Enter the username and password. The authenticateuserweb service function is invoked. If your credentials match the data in the ACS internal store, your authentication succeeds. Note This method does not perform any change and does not authorize you to perform any task. You use this method only to verify if the password is correct. However, after a successful authentication, you can move to the change password page to use the User Change Password method. Output Parameters The response from the User Authentication method could be one of the following: Authentication Succeeded Authentication Failed Exceptions This method displays an error message if: The authentication fails due to incorrect username or password. The user is disabled. 2-2

17 Chapter 2 Using the UCP Web Service Understanding the Methods in the UCP Web Service A web service connection error occurs, such as network disconnection or request timeout error. A system failure occurs, such as the database being down and unavailable. User Change Password The User Change Password method authenticates a user against an internal database and changes the user password. Input Parameters Username Current password New password Purpose Use the changeuserpassword method for applications that require a single-step procedure to change the user password. Changing a user password is normally a two-step procedure. The first step is to authenticate the user and the second step is to change the user password. The changeuserpassword method allows you to combine the two steps into one. A script or a single-page web application is an example of applications that require a single-step procedure to change the user password. To change a password: Step 1 Step 2 Connect to the UCP web application A login page appears. Enter the username and password. The authenticateuser web service function is invoked. If authentication succeeds, the web service compares the new password against the password policy that is configured in ACS. If your new password meets the defined criteria, the changeuserpassword web service function is invoked to change your password. Output Parameters The response from the User Change Password method could be one of the following: Operation Succeeded Operation Failed Exceptions This method displays an error if: The authentication fails because of an incorrect username or password. The user is disabled. The password change operation fails because the password does not conform to the password complexity rules defined in ACS. 2-3

18 Using the WSDL File Chapter 2 Using the UCP Web Service A web service connection error occurs, such as network disconnection or request timeout error. A system failure occurs, such as the database being down and unavailable. Using the WSDL File This section describes the WSDL file and the request and response schemas for the User Authentication and User Change Password methods. This section contains: Downloading the WSDL File, page 2-4 UCP WSDL File, page 2-4 Request and Response Schemas, page 2-7 Downloading the WSDL File To download the WSDL file from the ACS 5.3 web interface: Step 1 Step 2 Step 3 Step 4 Step 5 Log into the ACS 5.3 web interface. Choose System Administration > Downloads > User Change Password. Click UCP WSDL to view the UCP WSDL file. Copy the WSDL file to your local hard drive. Click UCP web application example to download a sample web application and save it to your local hard drive. UCP WSDL File The WSDL file is an XML document that describes the web services and the operations that the web services expose. The UCP WSDL is given below: <?xml version="1.0" encoding="utf-8"?> <!--**************************************************--> <!-- Copyright (c) 2009 Cisco Systems, Inc.--> <!-- All rights reserved.--> <!--**************************************************--> <definitions name="changepass" targetnamespace=" xmlns:tns=" xmlns:soap-env=" xmlns:soap-enc=" xmlns:xsi=" xmlns:xsd=" xmlns:soap=" xmlns:mime=" xmlns:dime=" xmlns:wsdl=" xmlns=" <WSDL:documentation> Copyright (c) 2009 Cisco Systems, Inc. 2-4

19 Chapter 2 Using the UCP Web Service Using the WSDL File ACS5.1 WSDL Service Interface for change password This WSDL document defines the publication API calls for changing user password. </WSDL:documentation> <xsd:types> <xsd:schema xmlns=" targetnamespace=" <xsd:simpletype name="usernametype"> <xsd:restriction base="string"> <xsd:minlength value="1" /> </xsd:restriction> </xsd:simpletype> <xsd:element name="usernametype" type="tns:usernametype" /> <xsd:simpletype name="passwordtype"> <xsd:restriction base="string"> <xsd:minlength value="1" /> </xsd:restriction> </xsd:simpletype> <xsd:element name="passwordtype" type="tns:passwordtype" /> <xsd:simpletype name="statuscodetype"> <xsd:restriction base="string"> <xsd:enumeration value="success" /> <xsd:enumeration value="failure" /> </xsd:restriction> </xsd:simpletype> <xsd:element name="responsetype"> <xsd:complextype> <xsd:attribute name="status" type="tns:statuscodetype" use="required" /> <xsd:sequence> <xsd:element name="errormessage" type="xsd:string" minoccurs="0" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> </xsd:element> </xsd:schema> </xsd:types> <message name="authuserrequest"> <part name="user_name" element="tns:usernametype" /> <part name="password" element="tns:passwordtype" /> </message> <message name="authuserresponse"> <part name="authuserresponse" element="tns:responsetype" /> </message> <message name="changeuserpassrequest"> <part name="user_name" element="tns:usernametype" /> <part name="old_password" element="tns:passwordtype" /> <part name="new_password" element="tns:passwordtype" /> </message> 2-5

20 Using the WSDL File Chapter 2 Using the UCP Web Service <message name="changeuserpassresponse"> <part name="changeuserpassresponse" element="tns:responsetype" /> </message> <WSDL:portType name="changepassword"> <operation name="authenticateuser"> <input message="tns:authuserrequest" name="authuserrequest" /> <output message="tns:authuserresponse" name="authuserresponse" /> </operation> <operation name="changeuserpass"> <input message="tns:changeuserpassrequest" name="changeuserpassrequest" /> <output message="tns:changeuserpassresponse" name="changeuserpassresponse" /> </operation> </WSDL:portType> <WSDL:binding name="changepasssoapbinding" type="tns:changepassword"> <SOAP:binding style="document" transport=" /> <!-- This is the SOAP binding for the Change Password publish operations. --> <WSDL:operation name="authenticateuser"> <SOAP:operation soapaction="" /> <input> <SOAP:body use="literal" /> </input> <output> <SOAP:body use="literal" /> </output> </WSDL:operation> <WSDL:operation name="changeuserpass"> <SOAP:operation soapaction="" /> <input> <SOAP:body use="literal" /> </input> <output> <SOAP:body use="literal" /> </output> </WSDL:operation> </WSDL:binding> <WSDL:service name="changepassword"> <documentation> ACS5.1 Programmatic Interface Service Definitions </documentation> <port name="changepassword" binding="tns:changepasssoapbinding"> <SOAP:address location=" /> </port> </WSDL:service> </definitions> 2-6

21 Chapter 2 Using the UCP Web Service Working with the UCP Web Service Request and Response Schemas User Authentication Request This section lists the request and response schemas of the User Authentication and User Change Password methods. This section contains the following schema: User Authentication Request, page 2-7 User Authentication Response, page 2-7 User Change Password Request, page 2-7 User Change Password Response, page 2-7 <message name="authuserrequest"> <part name="user_name" element="changepass:usernametype" /> <part name="password" element="changepass:passwordtype" /> </message> User Authentication Response <message name="authuserresponse"> <part name="authuserresponse" element="changepass:responsetype" /> </message> User Change Password Request <message name="changeuserpassrequest"> <part name="user_name" element="changepass:usernametype" /> <part name="current_password" element="changepass:passwordtype" /> <part name="new_password" element="changepass:passwordtype" /> </message> User Change Password Response <message name="changeuserpassresponse"> <part name="changeuserpassresponse" element="changepass:responsetype" /> </message> Working with the UCP Web Service You can create custom web-based applications to enable users to change their own password for your enterprise. This section describes how you can run a sample application that is developed using Python and provides the sample client code. The ACS web interface provides a downloadable package that consists of: Python SOAP libraries for Linux and Windows Python script ReadMe Contains installation instructions 2-7

22 Working with the UCP Web Service Chapter 2 Using the UCP Web Service To download this package: Step 1 Step 2 Step 3 Step 4 Log into the ACS 5.3 web interface. Choose System Administration > Downloads > Scripts. The Sample Python Scripts page appears. Click Python Script for Using the User Change Password Web Service. Save the.zip file to your local hard disk. Sample Client Code shows a sample.zip file. This file contains a.war file. You have to deploy this.war file within a web server, such as Tomcat. This example allows your application to communicate with ACS through the UCP web service. Note The Cisco Technical Assistance Center (TAC) supports only the default Python Script. TAC does not offer any support for modified scripts. Sample Client Code from SOAPpy import SOAPProxy # Get the ACS host / IP host = raw_input('please enter ACS host name or IP address:\n') targeturl = ' + host + '/PI/services/UCP/' server = SOAPProxy(targetUrl, 'UCP') # Get the username username = raw_input('please enter user name:\n') # Get the old password oldpassword = raw_input('please enter old password:\n') # Get the new password newpassword = raw_input('please enter new password:\n') # Call the changeuserpassword with the given input ans = server.changeuserpass(username, oldpassword, newpassword) # Password changing failed if ans.status == 'failure': print '\nfailure:' # Print all failure reasons for err in ans.errors: print err else: # Password was changed successfully print 'Success' Note You must have Python software to run this script. 2-8

23 CHAPTER 3 Using the Monitoring and Report Viewer Web Services This chapter describes the environment that you must set up to use the web services provided by the Monitoring and Report Viewer component of ACS 5.3. Hereafter this is referred to as Viewer web services. You can use these web services to create custom applications for tracking and troubleshooting ACS events. The Viewer web services comprise the following methods: getversion() Returns the version of the Monitoring and Report Viewer server. getauthenticationstatusbydate() Returns the authentication status of a user by date. getauthenticationstatusbytimeunit() Returns the authentication status of a user by time. getfailurereasons() Returns a list of reasons for failure. getradiusaccounting() Returns a list of RADIUS accounting records. getapiversion() Returns the version of the Viewer web services. Enabling the Web Interface on ACS CLI You must enable the web interface on ACS before you can use the Viewer web services. To enable the web interface on ACS, from the ACS CLI, enter: acs config web-interface view enable For more information on the acs config web-interface command, refer to reference/cli_app_a.html#wp Viewing the Status of the 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 reference/cli_app_a.html#wp The following sections describe how to use the Monitoring and Report Viewer web services: Understanding the Methods in the Viewer Web Services, page 3-2 Understanding the WSDL Files, page

24 Understanding the Methods in the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services Integrating the Viewer Web Services with Your Application, page 3-9 Working with the Viewer Web Services, page 3-10 Understanding the Methods in the Viewer Web Services This section describes the methods that are available in the Viewer web services: Get Version, page 3-2 Get Authentication Status By Date, page 3-3 Get Authentication Status By Time Unit, page 3-3 Get Failure Reasons, page 3-4 Get RADIUS Accounting, page 3-4 Get API Version, page 3-5 Table 3-1 describes the classes that are used in the Viewer web services. Table 3-1 Viewer Web Services Class Information Class ACSViewWebServices UserCon AuthenticationParam AuthenticationStatus AccountingParam AccountingStatus AccountingDetail ACSViewNBException Description Contains all web services that a client views in the client applications. Contains the ACS username and the user password, which the Monitoring and Report Viewer server uses to authenticate the user. Encapsulates the authentication query parameters, based on which records are queried and returned to you. Contains the Authentication Status record that is the query output received from ACS. Encapsulates the accounting query parameters, based on which records are queried and returned to you. Contains the Accounting Status record that is the query output received from ACS. Contains a list of attribute values that comprise the query output received from ACS. Contains the errors that the Monitoring and Report Viewer displays for any issues with the web services. Note The Monitoring and Report Viewer places all web service classes in the com.cisco.acsview.nbapi package. Get Version Input Parameter userctx (Required) User con object 3-2

25 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the Methods in the Viewer Web Services Purpose Use the getversion method to view the version of the Monitoring and Report Viewer that is installed on your ACS server. You can enter this command in the CLI to call this web service to view the Monitoring and Report Viewer version. Output Parameters Version of the Monitoring and Report Viewer server. Exception This method displays an error if: The user is invalid The input is invalid The ACS instance is not running as the Monitoring and Report Viewer server Get Authentication Status By Date Input Parameters userctx (Required) User con object authparam (Required) AuthenticationParam object startdate (Required) The date from which you want the authentication status enddate (Required) The date until which you want the authentication status Purpose Use the getauthenticationstatusbydate method to view a user s authentication status, arranged chronologically by date, for a specific period. Output Parameter Authentication status of the user, arranged chronologically by date, for the specified period. Exception This method displays an error if the: User con value is entered but passed as null Username and password are entered but passed as null Date value is entered but passed as null Get Authentication Status By Time Unit Input Parameters userctx (Required) User con object authparam (Required) AuthenticationParam object lastx (Required) The time until which you need the authentication status timeunit (Required) Time unit, specified in minutes, hours, or days 3-3

26 Understanding the Methods in the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services Purpose Use the getauthenticationstatusbytimeunit method to view a user s authentication status, arranged chronologically by time, for a specific period. Output Parameter A list of the user s authentication status, arranged chronologically by time, for a specific period. Exception This method displays an error if the: User con value is entered but passed as null Username and password are entered but passed as null Date value is entered but passed as null Get Failure Reasons Input Parameter userctx (Required) User con object Purpose Use the getfailurereasons method to obtain a list of records that contain failure reasons. Output Parameters List of records that contain failure reasons. Exception This method displays an error if the user credentials are invalid. Get RADIUS Accounting Input Parameters userctx (Required) User con object acctparam (Required) Accounting search parameters; valid values for matchoperator are valuelike, valueeq, valuene, valuege, valuele, valuegt, valuelt, attreq, valuein, valueinnot. The equation takes any one of the following forms: AttributeName, MatchArgument, MatchOp=[ valuelike valueeq valuene valuege valuele valuegt valuelt attreq] AttributeName, MultipleValueMatchArgument, MatchOp=[ valuein valueinnot ] Attribute Name As defined by standard RADIUS/Cisco A-V pair names. Attribute names are not case sensitive. However, the values are case sensitive. valuelike Looks for wildcard match (%). For example, %foo%. valueeq Looks for an exact match. valuene Performs a value not equal to comparison. valuege Performs greater than or equal to comparison. 3-4

27 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files valuele Performs lesser than or equal to comparison. valuegt Performs a greater than comparison. valuelt Performs a lesser than comparison. attreq Compares a given attribute with another attribute; returns true or false. valuein Multiple values are allowed for matchoperator valuein. valueinnot Multiple values are not allowed for matchoperator valueinnot. returnattributes (Required) List of return attributes requested. startdate (Required) Date from which you want the RADIUS accounting records. enddate (Required) Date until which you want the RADIUS accounting records. Purpose Use the getradiusaccounting method to obtain a list of RADIUS accounting records. Output Parameters List of RADIUS accounting records. Exception This method displays an error if: User credentials are invalid The acctparam parameter contains invalid values for matchoperator The acctparam parameter contains invalid value for matchvalues A database select error occurs Get API Version Input Parameter userctx (Required) User con object Purpose Use the getapiversion method to obtain the version of the Viewer web services. Output Parameter Version of the Viewer web services. Exception This method displays an error if an authentication failure occurs. Understanding the WSDL Files This section describes the WSDL files, the location from which you can download them, the class files, and the queries that you can use in the Viewer web services. This section contains the following: Downloading the WSDL Files, page

28 Understanding the WSDL Files Chapter 3 Using the Monitoring and Report Viewer Web Services Viewer WSDL Files, page 3-6 Integrating the Viewer Web Services with Your Application, page 3-9 Downloading the WSDL Files You can download the WSDL files from the following location: address or hostname/acsviewwebservices/acsviewwebservices?wsdl, where ip address or hostname is the IP address or hostname of your ACS server. Viewer WSDL Files WSDL is an XML document that describes a web service, the location of the service, and operations that the service exposes: <definitions name="acsviewwebservicesservice" targetnamespace=" xmlns=" xmlns:soap=" xmlns:tns=" xmlns:xsd=" <types> <schema elementformdefault="qualified" targetnamespace=" xmlns=" xmlns:soap11-enc=" xmlns:tns=" xmlns:xsi=" <complextype name="getfailurereasons"> <sequence> <element name="userctx" nillable="true" type="tns:usercon"/> </sequence> </complextype> <complextype name="getauthenticationstatusbydate"> <sequence> <element name="userctx" nillable="true" type="tns:usercon"/> <element name="authparam" nillable="true" type="tns:authenticationparam"/> <element name="startdate" nillable="true" type="datetime"/> <element name="enddate" nillable="true" type="datetime"/> </sequence> </complextype> <complextype name="getauthenticationstatusbydateresponse"> <sequence> <element maxoccurs="unbounded" minoccurs="0" name="result" nillable="true" type="tns:authenticationstatus"/> </sequence> </complextype> <complextype name="getauthenticationstatusbytimeunit"> <sequence> <element name="userctx" nillable="true" type="tns:usercon"/> <element name="authparam1" nillable="true" type="tns:authenticationparam"/> <element name="lastx" type="int"/> <element name="timeunit" nillable="true" type="string"/> </sequence> </complextype> <complextype name="getversion"> <sequence> <element name="userctx" nillable="true" type="tns:usercon"/> </sequence> 3-6

29 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files </complextype> <complextype name="acsviewnbexception"> <sequence> <element name="message" nillable="true" type="string"/> </sequence> </complextype> <complextype name="failurereason"> <sequence> <element name="authenfailurecode" nillable="true" type="string"/> <element name="possiblerootcause" nillable="true" type="string"/> <element name="resolution" nillable="true" type="string"/> </sequence> </complextype> <complextype name="authenticationparam"> <sequence> <element name="aaaclient" nillable="true" type="string"/> <element name="clientipaddress" nillable="true" type="string"/> <element name="clientmacaddress" nillable="true" type="string"/> <element name="username" nillable="true" type="string"/> </sequence> </complextype> <complextype name="authenticationstatus"> <sequence> <element name="authstatus" nillable="true" type="string"/> <element name="date" nillable="true" type="datetime"/> <element name="errorcode" nillable="true" type="string"/> <element maxoccurs="unbounded" minoccurs="0" name="moredetails" nillable="true" type="string"/> </sequence> </complextype> <complextype name="getauthenticationstatusbytimeunitresponse"> <sequence> <element maxoccurs="unbounded" minoccurs="0" name="result" nillable="true" type="tns:authenticationstatus"/> </sequence> </complextype> <complextype name="getversionresponse"> <sequence> <element name="result" nillable="true" type="string"/> </sequence> </complextype> <complextype name="getfailurereasonsresponse"> <sequence> <element maxoccurs="unbounded" minoccurs="0" name="result" nillable="true" type="tns:failurereason"/> </sequence> </complextype> <complextype name="usercon"> <sequence> <element name="password" nillable="true" type="string"/> <element name="username" nillable="true" type="string"/> </sequence> </complextype> <element name="getauthenticationstatusbydate" type="tns:getauthenticationstatusbydate"/> <element name="getauthenticationstatusbydateresponse" type="tns:getauthenticationstatusbydateresponse"/> <element name="getauthenticationstatusbytimeunit" type="tns:getauthenticationstatusbytimeunit"/> <element name="getauthenticationstatusbytimeunitresponse" type="tns:getauthenticationstatusbytimeunitresponse"/> <element name="getversion" type="tns:getversion"/> <element name="acsviewnbexception" type="tns:acsviewnbexception"/> <element name="getversionresponse" type="tns:getversionresponse"/> 3-7

30 Understanding the WSDL Files Chapter 3 Using the Monitoring and Report Viewer Web Services <element name="getfailurereasons" type="tns:getfailurereasons"/> <element name="getfailurereasonsresponse" type="tns:getfailurereasonsresponse"/> </schema> </types> <message name="acsviewnbexception"> <part element="tns:acsviewnbexception" name="acsviewnbexception"/> </message> <message name="acsviewwebservices_getauthenticationstatusbydate"> <part element="tns:getauthenticationstatusbydate" name="parameters"/> </message> <message name="acsviewwebservices_getauthenticationstatusbytimeunitresponse"> <part element="tns:getauthenticationstatusbytimeunitresponse" name="result"/> </message> <message name="acsviewwebservices_getauthenticationstatusbydateresponse"> <part element="tns:getauthenticationstatusbydateresponse" name="result"/> </message> <message name="acsviewwebservices_getversionresponse"> <part element="tns:getversionresponse" name="result"/> </message> <message name="acsviewwebservices_getauthenticationstatusbytimeunit"> <part element="tns:getauthenticationstatusbytimeunit" name="parameters"/> </message> <message name="acsviewwebservices_getversion"> <part element="tns:getversion" name="parameters"/> </message> <message name="acsviewwebservices_getfailurereasons"> <part element="tns:getfailurereasons" name="parameters"/> </message> <message name="acsviewwebservices_getfailurereasonsresponse"> <part element="tns:getfailurereasonsresponse" name="result"/> </message> <porttype name="acsviewwebservices"> <operation name="getauthenticationstatusbydate"> <input message="tns:acsviewwebservices_getauthenticationstatusbydate"/> <output message="tns:acsviewwebservices_getauthenticationstatusbydateresponse"/> <fault message="tns:acsviewnbexception" name="acsviewnbexception"/> </operation> <operation name="getauthenticationstatusbytimeunit"> <input message="tns:acsviewwebservices_getauthenticationstatusbytimeunit"/> <output message="tns:acsviewwebservices_getauthenticationstatusbytimeunitresponse"/> <fault message="tns:acsviewnbexception" name="acsviewnbexception"/> </operation> <operation name="getversion"> <input message="tns:acsviewwebservices_getversion"/> <output message="tns:acsviewwebservices_getversionresponse"/> <fault message="tns:acsviewnbexception" name="acsviewnbexception"/> </operation> <operation name="getfailurereasons"> <input message="tns:acsviewwebservices_getfailurereasons"/> <output message="tns:acsviewwebservices_getfailurereasonsresponse"/> <fault message="tns:acsviewnbexception" name="acsviewnbexception"/> </operation> </porttype> <binding name="acsviewwebservicesbinding" type="tns:acsviewwebservices"> <soap:binding style="document" transport=" <operation name="getauthenticationstatusbydate"> <soap:operation soapaction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> <fault name="acsviewnbexception"> 3-8

31 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files <soap:fault name="acsviewnbexception" use="literal"/> </fault> </operation> <operation name="getauthenticationstatusbytimeunit"> <soap:operation soapaction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> <fault name="acsviewnbexception"> <soap:fault name="acsviewnbexception" use="literal"/> </fault> </operation> <operation name="getversion"> <soap:operation soapaction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> <fault name="acsviewnbexception"> <soap:fault name="acsviewnbexception" use="literal"/> </fault> </operation> <operation name="getfailurereasons"> <soap:operation soapaction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> <fault name="acsviewnbexception"> <soap:fault name="acsviewnbexception" use="literal"/> </fault> </operation> </binding> <service name="acsviewwebservicesservice"> <port binding="tns:acsviewwebservicesbinding" name="acsviewwebservices"> <soap:address location=" </port> </service> </definitions> Integrating the Viewer Web Services with Your Application This section explains how to integrate the Viewer web services with your application. To integrate your code with a Viewer web service and to ensure that you get a response after you invoke the web service: Step 1 Obtain the certificate from the server to create the client certificate: a. Verify the deployed web services from: address or hostname/acsviewwebservices/acsviewwebservices?wsdl 3-9

32 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services For more information on the web services, see Understanding the Methods in the Viewer Web Services, page 3-2. b. Click View Certificate and go to the Details tab. c. Click Copy to File. d. In the welcome window, click Next. e. In the Export File Format window, select DER encoded binary X.509(.CER), then click Next. f. In the File to Export window, enter the filename and click Next. g. In the Completing the Certificate Export Wizard window, click Finish. A copy of the certificate is saved in your local system as server.cer. h. Import the server certificate and store it as client.ks (the Client Certificate) using the following command: Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 keytool -import -file server.cer -keystore client.ks Verify the deployed Viewer web services from: For more information on the web services, see Understanding the Methods in the Viewer Web Services, page 3-2. View the source and copy the WSDL file to your local system using: soap:address location=' For more information on the WSDL files, see Understanding the WSDL Files, page 3-5. Download the JAX-WS 2.0 libraries from the Sun Microsystems website. To view the information related to your artifacts, enter the wsimport -keep command at: Include all the libraries in your location. Write the client code. Compile and run the client code. Working with the Viewer Web Services This section provides sample client code in Java. The requirements that this section describes apply only if you use Java as the client-side conversion tool. This section contains: Required Files, page 3-11 Supported SOAP Clients, page 3-11 Sample Client Code, page

33 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services Required Files To use Java (JAX-WS) 2.0 as the client-side conversion tool, you need the following JAR files. You can download the.jar files and the related tools from the Sun Microsystems website: activation.jar FastInfoset.jar http.jar jaxb-api.jar jaxb-impl.jar jaxb-xjc.jar jaxws-api.jar jaxws-rt.jar jaxws-tools.jar jsr173_api.jar jsr181-api.jar jsr250-api.jar resolver.jar saaj-api.jar saaj-impl.jar sjsxp.jar Supported SOAP Clients The supported SOAP clients include: Apache JAX-WS Connecting to the Viewer Web Services To connect to the Viewer Web Services: Step 1 Step 2 Step 3 Verify the deployed Viewer Web Services from: address or hostname/acsviewwebservices/acsviewwebservices?wsdl For more information on the web services, see Understanding the Methods in the Viewer Web Services, page 3-2. Right click and select View Source/View Page Source option to view the source information. The source information appears in a pop-up dialog box. Save the source information with the name ACSViewWebServices.wsdl on your local directory; <SERVICE_HOME>. 3-11

34 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services Step 4 Execute the following command to create the class files: wsimport <SERVICE_HOME>/ACSViewWebServices.wsdl -d <SERVICE_HOME> Step 5 Step 6 Copy the Sample Client Code section on page 3-12 and save it as Client.java in <SERVICE_HOME> and compile it with the following command javac -cp <SERVICE_HOME> <SERVICE_HOME>/Client.java -d <SERVICE_HOME> This compiles the client code and places the package in the <SERVICE_HOME> directory. To run the Client code, execute the following command java -cp <SERVICE_HOME> com.cisco.acsview.nbapi.jaws.client. Note The above mentioned steps are done in Java 1.6.0_25. JAVA_HOME is java installed directory, and the "path" environment variable should be added with the value <JAVA_HOME>/bin. Sample Client Code This section provides sample client code for the Viewer web services. package com.cisco.acsview.nbapi.jaws; import java.util.calendar; import java.util.gregoriancalendar; import java.util.arraylist; import java.util.list; import java.util.iterator; import com.sun.org.apache.xerces.internal.jaxp.datatype.xmlgregoriancalendarimpl; import javax.xml.datatype.xmlgregoriancalendar; import javax.xml.datatype.datatypefactory; import java.security.cert.x509certificate; import javax.net.ssl.hostnameverifier; import javax.net.ssl.httpsurlconnection; import javax.net.ssl.sslcon; import javax.net.ssl.sslsession; import javax.net.ssl.trustmanager; import javax.net.ssl.x509trustmanager; public class Client { private static void install() throws Exception { // Create a trust manager that does not validate certificate chains TrustManager[] trustallcerts = new TrustManager[] { new X509TrustManager() { public X509Certificate[] getacceptedissuers() { return null; } public void checkclienttrusted(x509certificate[] certs, String authtype) { // Trust always } 3-12

35 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services public void checkservertrusted(x509certificate[] certs, String authtype) { // Trust always } } }; // Install the all-trusting trust manager SSLCon sc = SSLCon.getInstance("SSL"); // Create empty HostnameVerifier HostnameVerifier hv = new HostnameVerifier() { public boolean verify(string arg0, SSLSession arg1) { return true; } }; sc.init(null, trustallcerts, new java.security.securerandom()); HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory()); HttpsURLConnection.setDefaultHostnameVerifier(hv); } public static void install1() throws Exception { // Bypass hostname verification. HttpsURLConnection.setDefaultHostnameVerifier( new HostnameVerifier() { public boolean verify(string arg0, SSLSession arg1) { return true; } }); } public static void main(string args[]) { try { install(); ACSViewWebServicesService serviceobj = new ACSViewWebServicesService(); ACSViewWebServices service = serviceobj.getacsviewwebservices(); UserCon userctx = new UserCon(); userctx.setusername("acsadmin"); userctx.setpassword("acs5.1"); getversion(service,userctx); getapiversion(service,userctx); getauthbydate(service,userctx); getauthbytime(service,userctx); getradiusaccounting(service,userctx); getfailurereasons(service,userctx); } catch (Exception ex) { ex.printstacktrace(); } } /** * getversion provide the application version */ 3-13

36 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services public static void getversion(acsviewwebservices service, UserCon userctx) { try { String result = service.getversion(userctx); System.out.println(" *** Application Version *** "+"\n"); System.out.println("Application Version : "+result); System.out.println(" "+"\n"); } catch(exception e) { e.printstacktrace(); } } /** *getauthbydate provides the data of the authentication success/failure between the specified date range */ private static void getauthbydate(acsviewwebservices service, UserCon userctx) { try { System.out.println(" *** Authentication Status by Date Starts *** "+"\n"); AuthenticationParam authparam = new AuthenticationParam(); /** *** The following Attributes are optional. ** If the parameters are not set, method will return all the authentications success/failure between the specified date range. ** The Data will be filtered based on the attribute set which is falling under the specified date range. ** The attributes set are exactly matched for filtering,ie., only the data which is matching the below attributes and with in the specified date range are retrived. */ authparam.setaaaclient("myclient"); authparam.setclientipaddress(" "); authparam.setclientmacaddress("abac00019e05"); authparam.setusername("user1"); /******* Optional Attributes Ends **************/ DatatypeFactory datatypefactory = DatatypeFactory.newInstance(); GregorianCalendar gc1 = newgregoriancalendar(2011, Calendar.AUGUST, 4); XMLGregorianCalendar startdate = datatypefactory.newxmlgregoriancalendar(gc1).normalize(); GregorianCalendar gc2 = newgregoriancalendar(2011, Calendar.AUGUST, 6); XMLGregorianCalendar enddate = datatypefactory.newxmlgregoriancalendar(gc2).normalize(); java.util.list authstatusarray = service.getauthenticationstatusbydate(userctx,authparam, startdate, enddate); System.out.println("No of Records Retrieved : "+authstatusarray.size()); for(int i=0; i<authstatusarray.size();i++) { System.out.println("*************** Authentication Status : "+(i+1)+" ***************"); AuthenticationStatus status = (AuthenticationStatus)authStatusArray.get(i); java.util.list sarray = status.getmoredetails(); System.out.println(sarray.get(0) +" :: "+sarray.get(1)); for(int j=0;j<sarray.size();j++) { System.out.println(sarray.get(j)+" :: "+sarray.get(++j)); } 3-14

37 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services System.out.println("******************************************************************"); } System.out.println(" *** Authentication Status by Date Ends *** "+"\n"); } catch (Exception ex) { ex.printstacktrace(); } } /** * getauthbytime provides the data of the authentication success/failure in the specified time. * Time can be provided in Minutes, Hours or Days */ private static void getauthbytime(acsviewwebservices service, UserCon userctx) { try { System.out.println(" *** Authentication Status by Time Starts *** "+"\n"); AuthenticationParam authparam = new AuthenticationParam(); /** *** The following Attributes are optional. ** If the parameters are not set method will return all the authentications success/failure between the specified date range. ** The Data will be filtered based on the attribute set which is falling under the specified date range. ** The attributes set are exactly matched for filtering,ie., only the data which is matching the below attributes and with in the specified date range are retrived. */ authparam.setaaaclient("myclient"); authparam.setclientipaddress(" "); authparam.setclientmacaddress("abac00019e05"); authparam.setusername("user1"); /******* Optional Attributes Ends **************/ java.util.list authstatusarray = service.getauthenticationstatusbytimeunit(userctx,authparam, 20, "Hours"); System.out.println("No of Records Retrieved : " + authstatusarray.size()); for(int i=0; i<authstatusarray.size();i++) { System.out.println("*************** Authentication Status : "+(i+1)+" ***************"); AuthenticationStatus status = (AuthenticationStatus)authStatusArray.get(i); java.util.list sarray = status.getmoredetails(); System.out.println(sarray.get(0) +" :: "+sarray.get(1)); for(int j=0;j<sarray.size();j++) { System.out.println(sarray.get(j)+" :: "+sarray.get(++j)); } System.out.println("******************************************************************"); } System.out.println(" *** Authentication Status by Time Ends *** "+"\n"); } catch (Exception ex) { ex.printstacktrace(); } } 3-15

38 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services /** ** getapiversion provides the application API Version */ public static void getapiversion(acsviewwebservices service, UserCon userctx) { try { System.out.println(" *** API Version *** "+"\n"); String apiresult = service.getapiversion(userctx); System.out.println("API Version : "+apiresult); System.out.println(" "+"\n"); } catch(exception ex) { ex.printstacktrace(); } } /** ** getfailurereasons provide the Failure Code, Possible Root Cause and Resolution */ public static void getfailurereasons(acsviewwebservices service, UserCon userctx) { try { // Get Failure reason - Example System.out.println(" *** Failure Reasons Starts *** "+"\n"); List result1 = service.getfailurereasons(userctx); System.out.println("Failure reasons list is : " + result1.size()); for (int i=0;i<result1.size() ;i++ ) { System.out.println("Authentication Failure Code : "+((FailureReason)result1.get(i)).getAuthenFailureCode()); System.out.println("Possible Root Cause : "+((FailureReason)result1.get(i)).getPossibleRootCause()); System.out.println("Resolution : "+((FailureReason)result1.get(i)).getResolution()); } System.out.println(" *** Failure Reasons Ends *** "+"\n"); } catch(exception ex) { ex.printstacktrace(); } } /** ** getradiusaccounting provides the accounting details between the specified date range. */ public static void getradiusaccounting(acsviewwebservices service, UserCon userctx) { try { System.out.println(" *** Radius Accounting Starts *** "+"\n"); 3-16

39 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services List acctparam = new ArrayList(); AccountingParam acparam = new AccountingParam(); List vallist = acparam.getmatchvalues(); vallist.add("11"); acparam.setattributename("cisco-h323-disconnect-cause/h323-disconnect-cause"); acparam.setmatchoperator("valueinnot"); acctparam.add(acparam); List returnattributes = new ArrayList(); returnattributes.add("cisco-h323-disconnect-cause/h323-disconnect-cause"); DatatypeFactory datatypefactory = DatatypeFactory.newInstance(); GregorianCalendar gc1 = newgregoriancalendar(2011, Calendar.AUGUST, 5); XMLGregorianCalendar startdate = datatypefactory.newxmlgregoriancalendar(gc1).normalize(); GregorianCalendar gc2 = newgregoriancalendar(2011, Calendar.AUGUST, 7); XMLGregorianCalendar enddate = datatypefactory.newxmlgregoriancalendar(gc2).normalize(); AccountingStatus acctstatus = service.getradiusaccounting(userctx,acctparam, startdate, enddate, returnattributes); List attrnames = acctstatus.getattrnames(); for(int x=0 ; x<attrnames.size() ; x++) { System.out.println("Attribute Names : "+attrnames.get(x)); } List acctdetailslist = (ArrayList)acctStatus.getAcctDetails(); Iterator detailiterator = acctdetailslist.iterator(); while(detailiterator.hasnext()) { AccountingDetail acctdetailobj = (AccountingDetail)detailIterator.next(); List acctdetails = (List)acctDetailObj.getAttrValues(); for (int i=0;i<acctdetails.size() ;i++ ) { System.out.println("Attribute Details : "+acctdetails.get(i)); } } System.out.println(" *** Radius Accounting Ends *** "+"\n"); } catch(exception e) { e.printstacktrace(); } } } 3-17

40 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services 3-18

41 CHAPTER 4 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 reference/cli_app_a.html#wp 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 ence/cli_app_a.html#wp 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 4-1

42 Supported Configuration Objects Chapter 4 Using the Configuration Web Services 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 Service Location Error Message Supports Get method only. 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. Supports getall method only. It allows to retrieve all ACS message codes and message s 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, page 4-2 Attribute Info, page 4-3 Group Associations, page 4-3 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. 4-2

43 Chapter 4 Using the Configuration Web Services Query Object 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 :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, page 4-3 Sorting, page 4-4 Paging, page 4-5 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 4-3

44 Query Object Chapter 4 Using the Configuration Web Services 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=" <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 4-4

45 Chapter 4 Using the Configuration Web Services Request Structure 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 4-5

46 Request Structure Chapter 4 Using the Configuration Web Services 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 None An Object / {name} 1 getbyid GET /{ObjectType}/id/{i d} None An Object 4-6

47 Chapter 4 Using the Configuration Web Services Response Structure Table 4-3 HTTP Method Summary (continued) Function HTTP Method URL Request content create POST /{ObjectType} Object Note For create, the Object ID property should not be set. Response on Success Rest Response Result, which includes Object ID. delete DELETE /{ObjectType}/name None Rest Result / {name} 1 delete DELETE /{ObjectType}/ None Rest Result id/{id} update 2 PUT /{ObjectType} Object Rest Result Query PUT /{ObjectType}/op/qu ery 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 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 4-7

48 Response Structure Chapter 4 Using the Configuration Web Services 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 400 Bad Request Request errors: Object validation failure, XML syntax error, and other error in request message 401 Unauthorized Authentication Failure/ Time outs 403 Forbidden ACS is a secondary and can not fulfill the request or operation is not allowed per administrator authorizations. 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 500 Internal Server Error For any Server error that has no specific HTTP Code. No data is returned in the response body. 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. Similar to 403 error, but specifically for use when authentication failed or credentials are not available. 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. A request was made for an object that does not exist. For example, deleting an object that does not exist. 4-8

49 Chapter 4 Using the Configuration Web Services WADL File 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 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 To download the WADL files: Step 1 Step 2 From the ACS user interface, go to System Administration > Downloads > Rest Service 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 4-9

50 Sample Code Chapter 4 Using the Configuration Web Services 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 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 4-10

51 CHAPTER 5 Using the Scripting Interface This chapter describes the scripting interface that ACS 5.3 provides to perform bulk operations on ACS objects using the Import and Export features. ACS provides the import and export functionalities through the web interface (graphical user interface) as well as the CLI. ACS exposes these functionalities through the CLI to enable you to create custom shell scripts for bulk operations on ACS objects. The import-data command allows you to: Add ACS objects Update ACS objects Delete ACS objects The import and export functionalities in ACS 5.3 allow you to perform bulk operations such as Create, Update, and Delete on ACS objects and provide a migration path for customers migrating from ACS 4.x releases to ACS 5.3. You can integrate ACS with any of your repositories and import data into ACS through automated scripts, using the Import and Export features. You can also encrypt the.csv file before you transfer the file for additional security, or, optionally, use Secure File Transfer Protocol (SFTP). You can create a scheduled command that looks for a file with a fixed name in the repository to perform bulk operations. This option provides the functionality that was available in ACS 4.x releases. ACS processes the import and export requests in a queue. Only one process can run at a time. When you use the ACS web interface for importing and exporting, you cannot manually control the queue. ACS processes the queue in sequence. However, you can use the CLI to manage the import and export processes in ACS. The ACS CLI allows you to view the status of the queue and terminate the processes that are in the queue. This chapter contains the following sections: Understanding Import and Export in ACS, page 5-2 Supported ACS Objects, page 5-5 Creating Import Files, page 5-7 Using Shell Scripts to Perform Bulk Operations, page

52 Understanding Import and Export in ACS Chapter 5 Using the Scripting Interface Understanding Import and Export in ACS You can use the import functionality in ACS to add, update, or delete multiple ACS objects at the same time. ACS uses a comma-separated values (CSV) file to perform these bulk operations. This.csv file is called an import file. ACS provides a separate.csv template for Add, Update, and Delete operations for each ACS object. The first record in the.csv file is the header record from the template that contains column (field) names. You must download these templates from the ACS web interface. The header record from the template must be included in the first row of any.csv file that you import. You cannot use the same template to import all ACS objects. You must download the template that is designed for each ACS object and use the corresponding template while importing the objects. You can use the export functionality to create a.csv file that contains all the records of a particular object type that are available in the ACS internal store. You must have CLI administrator-level access to perform import and export operations. Additionally: To import ACS configuration data, you need CRUD permissions for the specific configuration object. To export data to a remote repository, you need read permission for the specific configuration object. This section contains: Importing ACS Objects Through the CLI, page 5-2 Exporting ACS Objects Through the CLI, page 5-3 Viewing the Status of Import and Export Processes, page 5-4 Terminating Import and Export Processes, page 5-5 Importing ACS Objects Through the CLI You can import ACS objects from the ACS Configuration mode. You use the import-data command to perform the Import operation. This command takes the following arguments: Name of the remote repository where the import file resides. See Creating Import Files, page 5-7, for information on how to create the import file. Name of the import file. Type of ACS object that the import file contains. ACS obtains the.csv file from the remote repository and processes the file. You can query ACS for the status of the import process using the import-export-status command. After the import process is complete, ACS generates a status file in the remote repository that includes any errors that ACS identified during this process. For additional security during the import process, you have the option of encrypting the import file and using a secured remote repository for the import operation. Also, the import process sometimes can run into errors. You can specify whether you want to terminate the import process or continue it until it is complete. Note If you choose to use a secured remote repository for import, you must specify SFTP as the repository value. 5-2

53 Chapter 5 Using the Scripting Interface Understanding Import and Export in ACS For example, to add internal user records to an existing identity store, from the ACS CLI, enter: import-data add user repository file-name result-file-name {abort-on-error cont-on-error} {full none only-sec-repo only-sec-files} secret-phrase Syntax Description repository Name of the remote repository from which to import the ACS objects, in this case, the internal users. file-name Name of the import file in the remote repository. result-file-name Name of the file that contains the results of the import operation. This file is available in the remote repository when the import process completes or is terminated. abort-on-error Aborts the import operation if an error occurs during the import process. cont-on-error Ignores any errors that occur during the import process and continues to import the rest of the object. full Encrypts the import file using the GNU Privacy Guard (GPG) encryption mechanism and uses secured remote repository to import the file. If you specify the security type as full, you must specify SFTP as the repository value. none Neither encrypts the import file nor uses the secured remote repository for import. secret phrase Provide the secret phrase to decrypt the import file. If you specify the security type as full or only-sec-files, you must specify the secret phrase. only-sec-repo Uses the secured remote repository to import the file. If you specify the security type as only-sec-repo, you must specify SFTP as the repository value. only-sec-files Encrypts the import file using GPG encryption mechanism. For more information on the import-data command, see reference/cli_app_a.html#wp Exporting ACS Objects Through the CLI You can export a list of ACS objects in a.csv file from ACS to your local drive. You can perform this operation from the ACS Configuration mode, using the export-data command. This command takes the following arguments: Object type to be exported. Name of the remote repository to which the.csv file should be downloaded after the export process is complete. When ACS processes your export request, you can enter a command to query the progress of the export. After the export process is complete, the.csv file that is available in your remote repository should contain all the object records that exist in the ACS internal store. Note When you export ACS objects through the web interface, use the available filters to export a subset of the records. For additional security during the export process, you have the option of encrypting the export file and using a secured remote repository for the export operation. 5-3

54 Understanding Import and Export in ACS Chapter 5 Using the Scripting Interface Note If you choose to use a secured remote repository for export, you must specify SFTP as the repository value. For example, to export internal user records, from the ACS CLI, enter: export-data user repository file-name result-file-name {full none only-sec-repo only-sec-files} secret-phrase Syntax Description repository Name of the remote repository to which to export the ACS objects, in this case, the internal users. file-name Name of the export file in the remote repository. result-file-name Name of the file that contains the results of the export operation. This file is available in the remote repository when the export process completes. full Encrypts the export file using the GPG encryption mechanism and uses secured remote repository to export the file. If you specify the security type as full, you must specify SFTP as the repository value. none Neither encrypts the export file nor uses the secured remote repository for export. secret phrase Provide a secret phrase to encrypt the export file. If you specify the security type as full or only-sec-files, you must specify the secret phrase. only-sec-repo Uses the secured remote repository to export the file. If you specify the security type as only-sec-repo, you must specify SFTP as the repository value. only-sec-files Encrypts the export file using GPG encryption mechanism. For more information on the export-data command, see reference/cli_app_a.html#wp Viewing the Status of Import and Export Processes You can view the status of the import and export processes in ACS using the import-export-status command. Use this command to view the status of running import and export processes and to verify whether there are any pending processes. You must run the import-export-status command from the ACS Configuration mode. Any user, irrespective of role, can issue this command. import-export-status {current all id id} Syntax Description current Displays the status of the currently running processes. all Displays the status of all the import and export processes, including any pending processes. id Displays the import or export status, based on a particular process that is specified by the process ID. For more information on the import-export-status command, see reference/cli_app_a.html#wp

55 Chapter 5 Using the Scripting Interface Supported ACS Objects Terminating Import and Export Processes You can use the import-export-abort command to terminate all import and export processes,or process that are currently running or queued. You must run the import-export-abort command from the ACS Configuration mode. Only the super administrator can simultaneously terminate a running process and all pending import and export processes. However, a user who owns a particular import or export process can terminate that particular process by using the process ID, or by stopping the process when it is running. import-export-abort {running all id id} Syntax Description current Aborts any import or export process that is running currently. all Aborts all the import and export processes in the queue. id Aborts the import or export process, based on the process ID that you specify. For more information on the import-export-abort command, see reference/cli_app_a.html#wp Supported ACS Objects While ACS 5.3 allows you to perform bulk operations (Add, Update, Delete) on ACS objects using the import functionality, you cannot import all ACS objects. The import functionality in ACS 5.3 supports the following ACS objects: Users Hosts Network Devices Identity Groups NDGs Downloadable ACLs Command Sets Table 5-1 lists the ACS objects, their properties, and the property data types. Table 5-1 ACS Objects Property Names and s Property Name Object Type: User Username Description Enabled Change Password Password Property (Required in create, edit, and delete) String. Maximum length is 64 characters. (Optional) String. Maximum length is 1024 characters. (Required in create) Boolean. (Required in create) Boolean. (Required in create) String. Maximum length is 32 characters. Not available in Export. 5-5

56 Supported ACS Objects Chapter 5 Using the Scripting Interface Table 5-1 ACS Objects Property Names and s (continued) Property Name Property Enable Password (Optional) String. Maximum length is 32 characters. User Identity Group (Optional) String. Maximum length is 256 characters. List of attributes (Optional) String and other data types. Object Type: Hosts MAC address (Required in create, edit, delete) String. Maximum length is 64 characters. Description (Optional) String. Maximum length is 1024 characters. Enabled (Optional) Boolean. Host Identity Group (Optional) String. Maximum length is 256 characters. List of attributes (Optional) String. Object Type: Network Device Name (Required in create, edit, delete) String. Maximum length is 64 characters. Description (Optional) String. Maximum length is 1024 characters. Subnet (Required in create) String. Support RADIUS (Required in create) Boolean. RADIUS secret (Optional) String. Maximum length is 32 characters. Support TACACS (Required in create) Boolean. TACACS secret (Optional) String. Maximum length is 32 characters. Single connect (Optional) Boolean. Legacy TACACS (Optional) Boolean. Support CTS (Required in create) Boolean. CTS Identity (Optional) String. Maximum length is 32 characters. CTS trusted (Optional) Boolean. Password (Optional) String. Maximum length is 32 characters. sgaclttl (Optional) Integer. peeraznttl (Optional) Integer. envdatattl (Optional) Integer. Session timeout (Optional) Integer. List of NDG names (Optional) String. Object Type: Identity Group Name (Required in create, edit, delete) String. Maximum length is 64 characters. Description (Optional) String. Maximum length is 1024 characters. Object Type: NDG Name (Required in create, edit, delete) String. Maximum length is 64 characters. Description (Optional) String. Maximum length is 1024 characters. Object Type: Downloadable ACLs Name (Required in create, edit, delete) String. Maximum length is 64 characters. 5-6

57 Chapter 5 Using the Scripting Interface Creating Import Files Table 5-1 ACS Objects Property Names and s (continued) Property Name Description Content Property (Optional) String. Maximum length is 1024 characters. (Required in create, edit, delete) String. Maximum length is 1024 characters. Object Type: Command Set Name (Required in create, edit, delete) String. Maximum length is 64 characters. Description (Optional) String. Maximum length is 1024 characters. Commands (in the form of grant:command:arg uments) (Optional) String. Note This is a list with semicolons used as separators (:) between the values that you supply for grant. Fields that are optional can be left empty and ACS substitutes the default values for those fields. For example, when fields that are related to a hierarchy are left blank, ACS assigns the value of the root node in the hierarchy. For network devices, if TrustSec is enabled, all related configuration fields are set to default values. Creating Import Files This section describes how to create the.csv file for performing bulk operations on ACS objects. You can download the appropriate template for each of the objects. This section contains the following: Downloading the Template from the Web Interface, page 5-7 Understanding the CSV Templates, page 5-8 Creating the Import File, page 5-9 Downloading the Template from the Web Interface Before you can create the import file, you must download the import file templates from the ACS web interface. To download the import file templates for adding internal users: Step 1 Step 2 Step 3 Step 4 Log into the ACS 5.3 web interface. Choose Users and Identity Stores > Internal Identity Stores > Users. The Users page appears. Click File Operations. The File Operations wizard appears. Choose any one of the following: Add Adds users to the existing list. This option does not modify the existing list. Instead, it performs an append operation. Update Updates the existing internal user list. 5-7

58 Creating Import Files Chapter 5 Using the Scripting Interface Step 5 Step 6 Step 7 Delete Deletes the list of users in the import file from the internal identity store. Click Next. The Template page appears. Click Download Add Template. Click Save to save the template to your local disk. The following list gives you the location from which you can get the appropriate template for each of the objects: User Users and Identity Stores > Internal Identity Stores > Users Hosts Users and Identity Stores > Internal Identity Stores > Hosts Network Device Network Resources > Network Devices and AAA Clients Identity Group Users and Identity Stores > Identity Groups NDG Location Network Resources > Network Device Groups > Location Device Type Network Resources > Network Device Groups > Device Type Downloadable ACLs Policy Elements > Authorization and Permissions > Named Permission Objects > Downloadable ACLs Command Set Policy Elements > Authorization and Permissions > Device Administration > Command Sets Follow the procedure described in this section to download the appropriate template for your object. Understanding the CSV Templates You can open your CSV template in Microsoft Excel or any other spreadsheet application and save the template to your local disk as a.csv file. The.csv template contains a header row that lists the properties of the corresponding ACS object. For example, the internal user Add template contains the fields described in Table 5-2: Table 5-2 Internal User Add Template Header Field name:string(64):required description:string(1024) enabled:boolean(true,false):required changepassword:boolean(true,false): Required password:string(32):required enablepassword:string(32) UserIdentityGroup:String(256) Description Username of the user. Description of the user. Boolean field that indicates whether the user must be enabled or disabled. Boolean field that indicates whether the user must change password on first login. Password of the user. Enable password of the user. Identity group to which the user belongs. All the user attributes that you have specified would appear here. 5-8

59 Chapter 5 Using the Scripting Interface Creating Import Files Each row of the.csv file corresponds to one internal user record. You must enter the values into the.csv file and save it before you can import the users into ACS. See Creating the Import File, page 5-9 for more information on how to create the import file. This example is based on the internal user Add template. For the other ACS object templates, the header row contains the properties described in Table 5-1 for that object. Creating the Import File After you download the import file template to your local disk, enter the records that you want to import into ACS in the format specified in the template. After you enter all records into the.csv file, you can proceed with the import function. The import process involves the following: Adding Records to the ACS Internal Store, page 5-9 Updating the Records in the ACS Internal Store, page 5-10 Deleting Records from the ACS Internal Store, page 5-10 Adding Records to the ACS Internal Store When you add records to the ACS internal store, you add the records to the existing list. This is an append operation, in which the records in the.csv file are added to the list that exists in ACS. To add internal user records to the Add template: Step 1 Step 2 Step 3 Download the internal user Add template. See Downloading the Template from the Web Interface, page 5-7 for more information. Open the internal user Add template in Microsoft Excel or any other spreadsheet application. See Table 5-1 for a description of the fields in the header row of the template. Enter the internal user information. Each row of the.csv template corresponds to one user record. Figure 5-1 Figure 5-1 shows a sample Add Users import file. Figure 5-1 Add Users Import File Step 4 Save the add users import file to your local disk. 5-9

60 Creating Import Files Chapter 5 Using the Scripting Interface Updating the Records in the ACS Internal Store When you update the records in the ACS store, the import process overwrites the existing records in the internal store with the records from the.csv file. This operation replaces the records that exist in ACS with the records from the.csv files. The Update operation is similar to the Add operation except for one additional column that you can add to the Update templates. The Update template can contain an Updated Name column for internal users and other ACS objects, and an Updated MAC address column for the internal hosts. The name shown in the Updated Name column replaces the name in the ACS identity store. Instead of downloading the update template for each of the ACS objects, you can use the export file of that object, retain the header row, and update the data to create your updated.csv file. To add an updated name or MAC address to the ACS objects, you must download and use the particular update template. Also, for the NDGs, the export template contains only the NDG name, so in order to update any other property, you must download and use the NDG update template. Figure 5-2 shows a sample import file that updates existing user records. Figure 5-2 Update Users Import File Note The second column, Updated name, is the additional column that you can add to the Update template. Also, the password value and the enabled password value are not mandatory in the case of an update operation for the user object. Deleting Records from the ACS Internal Store You can use this option to delete a subset of records from the ACS internal store. The records that are present in the.csv file that you import are deleted from the ACS internal store. The Delete template contains only the key column to identify the records that must be deleted. For example, to delete a set of internal users from the ACS internal identity store, download the internal user Delete template and add the list of users that you want to delete to this Import file. Figure 5-3 shows a sample Import file that deletes internal user records. Timesaver To delete all users, you can export all users and then use the export file as your import file to delete users. 5-10

61 Chapter 5 Using the Scripting Interface Using Shell Scripts to Perform Bulk Operations Figure 5-3 Delete Users Import File Using Shell Scripts to Perform Bulk Operations You can write custom shell scripts that use the import and export CLI commands to perform bulk operations. The ACS web interface provides a sample Python script. To download this sample script: Step 1 Step 2 Log into the ACS web interface. Choose System Administration > Downloads > Scripts. The downloadable package consists of: Python module, Pexpect Python script ReadMe Contains installation instructions Note You must have Python software to run this script. Sample Shell Script import pexpect # Create connection to a specific IP using 'admin' username connector = pexpect.spawn('ssh admin@ ') connector.expect('.ssword:*') # Enter password connector.sendline('defaultpass') connector.expect('.$') # Defining a repository that point to the localdisc connector.sendline('configure') connector.expect('.$') connector.sendline('repository localrepo') connector.expect('.$') connector.sendline('url disk:/') connector.expect('.$') connector.sendline('exit') connector.expect('.$') connector.sendline('exit') connector.expect('.$') 5-11