Software Developer s Guide for the Cisco Secure Access Control System 5.1

Transcription

1 Software Developer s Guide for the Cisco Secure Access Control System 5.1 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 PROVED 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 INCENTAL 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. CCDE, CCENT, CCSI, Cisco Eos, Cisco HealthPresence, Cisco IronPort, the Cisco logo, Cisco Nurse Connect, Cisco Pulse, Cisco SensorBase, Cisco StackPower, Cisco StadiumVision, Cisco TelePresence, Cisco Unified Computing System, Cisco WebEx, DCE, Flip Channels, Flip for Good, Flip Mino, Flipshare (Design), Flip Ultra, Flip Video, Flip Video (Design), Instant Broadband, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco Capital, Cisco Capital (Design), Cisco:Financed (Stylized), Cisco Store, Flip Gift Card, and One Million Acts of Green are service marks; and Access Registrar, Aironet, AllTouch, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Lumin, Cisco Nexus, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, Continuum, EtherFast, EtherSwitch, Event Center, Explorer, Follow Me Browsing, GainMaker, ilynx, IOS, iphone, IronPort, the IronPort logo, Laser Link, LightStream, Linksys, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, PCNow, PIX, PowerKEY, PowerPanels, PowerTV, PowerTV (Design), PowerVu, Prisma, ProConnect, ROSA, SenderBase, SMARTnet, Spectrum Expert, StackWise, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or website 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. (0910R) 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 v Audience v How This Guide Is Organized v Conventions iii-vi Documentation Updates vii Related Documentation vii Obtaining Documentation and Submitting a Service Request viii CHAPTER 1 Overview 1-1 Understanding Web Services 1-2 Understanding WSDL 1-2 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-2 Using the WSDL File 2-3 Downloading the WSDL File 2-4 UCP WSDL File 2-4 Request and Response Schemas 2-6 User Authentication Request 2-6 User Authentication Response 2-6 User Change Password Request 2-7 User Change Password Response 2-7 Working with the UCP Web Service 2-7 Sample Client Code 2-7 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 Get Failure Reasons 3-4 iii

4 Contents 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-10 Supported SOAP Clients 3-11 Connecting to the Viewer Web Services 3-11 Sample Client Code 3-12 CHAPTER 4 Using the Scripting Interface 4-1 Understanding Import and Export in ACS 4-1 Importing ACS Objects Through the CLI 4-2 Exporting ACS Objects Through the CLI 4-3 Viewing the Status of Import and Export Processes 4-4 Aborting Import and Export Processes 4-5 Supported ACS Objects 4-5 Creating Import Files 4-7 Downloading the Template from the Web Interface 4-7 Understanding the CSV Templates 4-8 Creating the Import File 4-9 Adding Records to the ACS Internal Store 4-9 Updating the Records in the ACS Internal Store 4-10 Deleting Records from the ACS Internal Store 4-10 Using Shell Scripts to Perform Bulk Operations 4-11 Sample Shell Script 4-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 iv

5 Preface Welcome to the Software Developer Guide for the Cisco Secure Access Control System 5.1! 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, scriptable access for bulk provisioning using the command-line interface (CLI), and the ability 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 concepts relating to: Web Services Description Language (WSDL) File Web 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 features that ACS 5.1 provides in the form of web services and 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. 3 Using the Monitoring and Report Viewer Web Services Describes the web services that the Monitoring and Report Viewer component of ACS provides and how you can use these web services in your application. v

6 Conventions Preface Table 1 Organization (continued) Chapter/ Appendix Title Description 4 Using the Scripting Interface Describes the scripting interface that ACS offers for performing 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 A 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. Timesaver Means the described action saves time. You can save time by performing the action described in the paragraph. vi

7 Preface Conventions Documentation Updates Table 3 Updates to the Software Developer s Guide for the Cisco Secure Access Control System 5.1 Date Description 10/04/2011 Updated the Sample Client Code, page 12 in the chapter Using the Monitoring and Report Viewer Web Services. 04/21/2010 Updated the document for the bug CSCtf /22/2010 Added a note stating that no TAC support is available for modified python scripts in the Working with the UCP Web Service section on page /11/2009 Cisco Secure Access Control System Release 5.1. 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 Related Documentation Document Supported and Interoperable Devices and Software Tables for the Cisco Secure Access Control System 5.1. Regulatory Compliance and Safety Information for Cisco 1121 Secure Access Control System 5.1 and Cisco NAC Appliance 4.7 Release Notes for the Cisco Secure Access Control System 5.1 Installation and Upgrade Guide for the Cisco Secure Access Control System 5.1 Open Source Licensing Document for the Cisco Secure Access Control System 5.1 CLI Reference Guide for the Cisco Secure Access Control System 5.1 User Guide for the Cisco Secure Access Control System 5.1 Location on Cisco.com _control_system/5.1/device_support/sdt51.html l_system/5.1/regulatory/compliance/csacsrcsi.html _control_system/5.1/release/notes/acs_51_rn.html _control_system/5.1/installation/guide/acs5_1_install_guide.html _control_system/5.1/open_source_license/opn_src_lic_doc.html _control_system/5.1/command/reference/acs5_1_cli.html _access_control_system/5.1/user/guide/acsuserguide.html vii

8 Conventions Preface Table 4 Related Documentation Document Migration Guide for the Cisco Secure Access Control System 5.1 License and Documentation Guide for the Cisco Secure Access Control System 5.1 Location on Cisco.com _access_control_system/5.1/migration/guide/migration_book.html _control_system/5.1/license_doc/guide/acs_51_lic_doc_gd.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. viii

9 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.1 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.1 also provides you 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. 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.1 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 A list of failure reason records A list of RADIUS accounting records 1-1

10 Understanding Web Services Chapter 1 Overview 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 working knowledge of: Web Services Description Language (WSDL) File Web Services Tools This chapter contains the following sections: Understanding Web Services, page 1-2 Understanding WSDL, page 1-2 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.1 exposes the following WSDL files: UCP WSDL Monitoring and Report Viewer WSDL 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. 1-2

11 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 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. Note 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 _system/5.1/command/reference/cli_app_a.html#wp 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 system/5.1/command/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-3 Working with the UCP Web Service, page

12 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-2 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 GUI application that prompts the user to change the password does it in two separate steps: The first step is to authenticate the user and the second step is to change the user password. When you connect to the UCP web application, a login page appears. You provide the username and password. When you submit the request, the authenticateuser web 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 throws an exception if: The authentication fails due to incorrect username or password. The user is disabled. 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. 2-2

13 Chapter 2 Using the UCP Web Service Using the WSDL File 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 a good example of applications that require a single-step procedure to change the user password. When you connect to the UCP web application, a login page appears. You provide the username, current password, and new password. When you submit the request, 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 throws an exception if: The authentication fails due to 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. 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

14 Using the WSDL File Chapter 2 Using the UCP Web Service Downloading the WSDL File To download the WSDL file from the ACS 5.1 web interface: Step 1 Step 2 Step 3 Step 4 Step 5 Log in to the ACS 5.1 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. 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> 2-4

15 Chapter 2 Using the UCP Web Service Using the WSDL File </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> <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" 2-5

16 Using the WSDL File Chapter 2 Using the UCP Web Service 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> 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-6 User Authentication Response, page 2-6 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"> 2-6

17 Chapter 2 Using the UCP Web Service Working with the UCP Web Service <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 To download this package: 1. Log in to the ACS 5.1 web interface. 2. Choose System Administration > Downloads > Scripts. The Sample Python Scripts page appears. 3. Click Python Script for Using the User Change Password Web Service. Save the.zip file to your local hard disk. This sample.zip 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/' 2-7

18 Working with the UCP Web Service Chapter 2 Using the UCP Web Service 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

19 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.1, hereafter referred to as Viewer web services. You can make use of 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. Note 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 _system/5.1/command/reference/cli_app_a.html#wp 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 system/5.1/command/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 3-5 Integrating the Viewer Web Services with Your Application, page 3-9 Working with the Viewer Web Services, page

20 Understanding the Methods in the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services 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 the 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 exception that the Monitoring and Report Viewer throws 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 Purpose Use the getversion method to view the version of the Monitoring and Report Viewer 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. 3-2

21 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the Methods in the Viewer Web Services Output Parameters Version of the Monitoring and Report Viewer server. Exception This method throws an exception 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 throws an exception 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 Purpose Use the getauthenticationstatusbytimeunit method to view a user s authentication status, arranged chronologically by time, for a specific period. 3-3

22 Understanding the Methods in the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services Output Parameter A list of the user s authentication status, arranged chronologically by time, for a specific period. Exception This method throws an exception 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 throws an exception 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. valuele Performs lesser than or equal to comparison. valuegt Performs a greater than comparison. valuelt Performs a lesser than comparison. 3-4

23 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files 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 throws an exception 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 throws an exception 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 3-6 Viewer WSDL Files, page 3-6 Integrating the Viewer Web Services with Your Application, page

24 Understanding the WSDL Files Chapter 3 Using the Monitoring and Report Viewer Web Services 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> </complextype> <complextype name="acsviewnbexception"> <sequence> <element name="message" nillable="true" type="string"/> </sequence> 3-6

25 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files </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"/> <element name="getfailurereasons" type="tns:getfailurereasons"/> <element name="getfailurereasonsresponse" type="tns:getfailurereasonsresponse"/> </schema> </types> <message name="acsviewnbexception"> 3-7

26 Understanding the WSDL Files Chapter 3 Using the Monitoring and Report Viewer Web Services <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"> <soap:fault name="acsviewnbexception" use="literal"/> </fault> </operation> <operation name="getauthenticationstatusbytimeunit"> <soap:operation soapaction=""/> 3-8

27 Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files <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 describes the procedure 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: 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. 3-9

28 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services 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 execute 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-10 Supported SOAP Clients, page 3-11 Sample Client Code, page 3-12 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 3-10

29 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services 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 Step 4 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 with the name ACSViewWebServices.wsdl on your local directory; <SERVICE_HOME>. Execute the following command to create the class files: wsimport <SERVICE_HOME>/ACSViewWebServices.wsdl -d <SERVICE_HOME> 3-11

30 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services 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; 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 } public void checkservertrusted(x509certificate[] certs, String authtype) { 3-12

31 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services // 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 */ public static void getversion(acsviewwebservices service, UserCon userctx) { try 3-13

32 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services { 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)); } System.out.println("******************************************************************"); } 3-14

33 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services 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(); } } /** ** getapiversion provides the application API Version 3-15

34 Working with the Viewer Web Services Chapter 3 Using the Monitoring and Report Viewer Web Services */ 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"); List acctparam = new ArrayList(); AccountingParam acparam = new AccountingParam(); List vallist = acparam.getmatchvalues(); 3-16

35 Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the Viewer Web Services 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

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

37 CHAPTER 4 Using the Scripting Interface This chapter describes the scripting interface that ACS 5.1 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.1 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.1. Using the import and export feature, you can integrate ACS with any of your repositories and import data into ACS through automated scripts. 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 you 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 import and export, 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 abort the processes that are in the queue. This chapter contains the following sections: Understanding Import and Export in ACS, page 4-1 Supported ACS Objects, page 4-5 Creating Import Files, page 4-7 Using Shell Scripts to Perform Bulk Operations, page 4-11 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 4-1

38 Understanding Import and Export in ACS Chapter 4 Using the Scripting Interface 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. Note You cannot use the same template to import all the 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. Note 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 4-2 Exporting ACS Objects Through the CLI, page 4-3 Viewing the Status of Import and Export Processes, page 4-4 Aborting Import and Export Processes, page 4-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: 1. Name of the remote repository where the import file resides. See Creating Import Files, page 4-7, for information on how to create the import file. 2. The name of the import file. 3. The 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 the import 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 an error. You can specify whether you want to abort 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. For example, to add internal user records to an existing identity store, from the ACS CLI, enter: 4-2

39 Chapter 4 Using the Scripting Interface Understanding Import and Export in ACS 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 aborted. 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 cisco_secure_access_control_system/5.1/command/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: 1. Object type to be exported. 2. 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. Note If you choose to use a secured remote repository for export, you must specify SFTP as the repository value. 4-3

40 Understanding Import and Export in ACS Chapter 4 Using the Scripting Interface 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 system/5.1/command/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 specified by the process. For more information on the import-export-status command, see /command/reference/cli_app_a.html#wp

41 Chapter 4 Using the Scripting Interface Supported ACS Objects Aborting Import and Export Processes You can use the import-export-abort command to abort currently running, queued, or all import and export processes. You must run the import-export-abort command from the ACS Configuration mode. Only the super administrator can simultaneously abort a running process and all pending import and export processes. However, a user who owns a particular import or export process can abort that particular process by using the process, 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 that you specify. For more information on the import-export-abort command, see /command/reference/cli_app_a.html#wp Supported ACS Objects While ACS 5.1 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.1 supports the following ACS objects: Users Hosts Network Devices Identity Groups NDGs Downloadable ACLs Command Sets Table 4-1 lists the ACS objects, their properties, and the property data types. Table 4-1 ACS Objects Property Names and s Property Name Object Type: User Username Description Enabled Change Password Password Enable Password User Identity Group 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. (Optional) String. Maximum length is 32 characters. (Optional) String. Maximum length is 256 characters. 4-5

42 Supported ACS Objects Chapter 4 Using the Scripting Interface Table 4-1 ACS Objects Property Names and s (continued) Property Name Property 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. Description (Optional) String. Maximum length is 1024 characters. Content (Required in create, edit, delete) String. Maximum length is 1024 characters. 4-6

43 Chapter 4 Using the Scripting Interface Creating Import Files Table 4-1 ACS Objects Property Names and s (continued) Property Name 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) Property (Optional) String. Note This is a list with semicolons used as separators (:) between the values that you supply for grant. Note 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 the 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 4-7 Understanding the CSV Templates, page 4-8 Creating the Import File, page 4-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 in to the ACS 5.1 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. Delete Deletes the list of users in the import file from the internal identity store. 4-7

44 Creating Import Files Chapter 4 Using the Scripting Interface Step 5 Step 6 Step 7 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 4-2: Table 4-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. A boolean field that indicates whether the user must be enabled or disabled. A 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. 4-8

45 Chapter 4 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 4-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 4-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 the 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 4-9 Updating the Records in the ACS Internal Store, page 4-10 Deleting Records from the ACS Internal Store, page 4-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 4-7 for more information. Open the internal user Add template in Microsoft Excel or any other spreadsheet application. See Table 4-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 4-1 Figure 4-1 shows a sample Add Users import file. Figure 4-1 Add Users Import File 4-9

46 Creating Import Files Chapter 4 Using the Scripting Interface Step 4 Save the add users import file to your local disk. 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. Note To add an updated name or MAC address to the ACS objects, 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 4-2 shows a sample import file that updates existing user records. Figure 4-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. 4-10

47 Chapter 4 Using the Scripting Interface Using Shell Scripts to Perform Bulk Operations 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 4-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. Figure 4-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: 1. Log in to the ACS web interface. 2. 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') 4-11