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

(1)

Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883

Software Developer’s Guide for the

Cisco Secure Access Control System 5.1

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

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.

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

(3)

C O N T E N T S

Preface

v

Audience

v

How This Guide Is Organized

v

Conventions

iii-vi

Documentation Updates

vii

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

C H A P T E R 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

(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-10

Supported SOAP Clients

3-11

Connecting to the Viewer Web Services

3-11

Sample Client Code

3-12

C H A P T E R 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

A P P E N D I X 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 IN D E X

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

(6)

Preface Conventions

Conventions

Table 2 describes the conventions followed in this document.

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.

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.

Table 1 Organization (continued)

Chapter/

Appendix Title Description

Table 2 Conventions

Convention Description

bold font Commands and keywords.

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

(7)

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

02/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 2-7.

11/11/2009 Cisco Secure Access Control System Release 5.1.

Table 4 Related Documentation

Document Location on Cisco.com

Supported and Interoperable Devices and Software Tables for the Cisco Secure Access Control System 5.1.

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/device_support/sdt51.html

Regulatory Compliance and Safety Information for Cisco 1121 Secure Access Control System 5.1 and Cisco NAC Appliance 4.7

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_contro l_system/5.1/regulatory/compliance/csacsrcsi.html

Release Notes for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/release/notes/acs_51_rn.html

Installation and Upgrade Guide for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/installation/guide/acs5_1_install_guide.html

Open Source Licensing Document for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/open_source_license/opn_src_lic_doc.html

CLI Reference Guide for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/command/reference/acs5_1_cli.html

User Guide for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure _access_control_system/5.1/user/guide/acsuserguide.html

(8)

Preface Conventions

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:

http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

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.

Migration Guide for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure

_access_control_system/5.1/migration/guide/Migration_Book.html

License and Documentation Guide for the Cisco Secure Access Control System 5.1

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access _control_system/5.1/license_doc/guide/acs_51_lic_doc_gd.html

Table 4 Related Documentation

(9)

C H A P T E R

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

(10)

Chapter 1 Overview Understanding Web Services

• 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:

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

(11)

C H A P T E R

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 http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control _system/5.1/command/reference/cli_app_a.html#wp1765431.

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

show acs-config-web-interface

For more information on the show acs-config-web-interface command, refer to http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_ system/5.1/command/reference/cli_app_a.html#wp1767743.

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

(12)

Chapter 2 Using the UCP Web Service Understanding the Methods in 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.

(13)

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

(14)

Chapter 2 Using the UCP Web Service Using the WSDL File

Downloading the WSDL File

To download the WSDL file from the ACS 5.1 web interface: Step 1 Log in to the ACS 5.1 web interface.

Step 2 Choose System Administration > Downloads > User Change Password. Step 3 Click UCP WSDL to view the UCP WSDL file.

Step 4 Copy the WSDL file to your local hard drive.

Step 5 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"?>

<definitions name="changepass" targetNamespace="http://www.cisco.com/changepass.service" xmlns:tns="http://www.cisco.com/changepass.service" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:MIME="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:DIME="http://schemas.xmlsoap.org/ws/2002/04/dime/wsdl/" xmlns:WSDL="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <WSDL:documentation>

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="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.cisco.com/changepass.service"> <xsd:simpleType name="UserNameType"> <xsd:restriction base="string"> <xsd:minLength value="1" /> </xsd:restriction>

(15)

</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">

<WSDL:portType name="ChangePassword"> <operation name="authenticateUser">

</WSDL:portType>

<WSDL:binding name="changePassSoapBinding" type="tns:ChangePassword"> <SOAP:binding style="document"

(16)

Chapter 2 Using the UCP Web Service Using the WSDL File

transport="http://schemas.xmlsoap.org/soap/http" />

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

<SOAP:address location="https://localhost:8080/PI/services/changepass/" /> </port>

</WSDL:service>

</definitions>

Request and Response Schemas

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

User Authentication Request

User Authentication Response

(17)

User Change Password Request

User Change Password Response

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 = 'https://' + host + '/PI/services/UCP/'

(18)

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

(19)

C H A P T E R

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 http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control _system/5.1/command/reference/cli_app_a.html#wp1765431.

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

show acs-config-web-interface

For more information on the show acs-config-web-interface command, refer to http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_ system/5.1/command/reference/cli_app_a.html#wp1767743.

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

(20)

Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the Methods in the 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.

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

Table 3-1 Viewer Web Services Class Information

Class Description

ACSViewWebServices Contains all the web services that a client views in the client applications. UserContext Contains the ACS username and the user password, which the Monitoring

and Report Viewer server uses to authenticate the user.

AuthenticationParam Encapsulates the authentication query parameters based on which records are queried and returned to you.

AuthenticationStatus Contains the Authentication Status record that is the query output received from ACS.

AccountingParam Encapsulates the accounting query parameters based on which records are queried and returned to you.

AccountingStatus Contains the Accounting Status record that is the query output received from ACS.

AccountingDetail Contains a list of attribute values that comprise the query output received from ACS.

ACSViewNBException Contains the exception that the Monitoring and Report Viewer throws for any issues with the web services.

(21)

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

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

(22)

Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the Methods in the 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 context 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

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

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

(23)

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

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

(24)

Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files

Downloading the WSDL Files

You can download the WSDL files from the following location:

https://<ip 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:

</complexType>

</complexType>

</sequence> </complexType>

</complexType>

</complexType>

(25)

</complexType>

</complexType>

</types>

(26)

Chapter 3 Using the Monitoring and Report Viewer Web Services Understanding the WSDL Files

</operation>

</operation>

</portType>

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <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>

(27)

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

<soap:address location="http://localhost:8080/ACSViewWebServices/ACSViewWebServices"/> </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:

https://<IPaddress(or)HostName>/ACSViewWebServices/ACSViewWebServices?wsdl 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.

(28)

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

keytool -import -file server.cer -keystore client.ks

Step 2 Verify the deployed Viewer web services from:

https://IPaddress(or)HostName/ACSViewWebServices/ACSViewWebServices?wsdl

For more information on the web services, see Understanding the Methods in the Viewer Web Services, page 3-2.

Step 3 View the source and copy the WSDL file to your local system using:

<soap:address location='https://acsview-cars1:443/ACSViewWebServices/ACSViewWebServices'/ >

For more information on the WSDL files, see Understanding the WSDL Files, page 3-5. Step 4 Download the JAX-WS 2.0 libraries from the Sun Microsystems website.

Step 5 To view the information related to your artifacts, enter the wsimport -keep command at:

https://IPAddress:443/ACSViewWebServ/ACSViewWebServices?wsdl Include all the libraries in your location.

Step 6 Write the client code.

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

(29)

• 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 Verify the deployed Viewer Web Services from:

https://ip 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.

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

Step 3 Save the source with the name ACSViewWebServices.wsdl on your local directory; <SERVICE_HOME>.

Step 4 Execute the following command to create the class files:

(30)

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

Step 5 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. Step 6 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.SSLContext; 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) {

(31)

// Trust always }

} };

// Install the all-trusting trust manager SSLContext sc = SSLContext.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(); UserContext userCtx = new UserContext();

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, UserContext userCtx) {

(32)

Chapter 3 Using the Monitoring and Report Viewer Web Services Working with the 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, UserContext 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("10.77.241.203"); 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("******************************************************************"); }

(33)

System.out.println("---*** Authentication Status by Date Ends ***---"+"\n");

}

/**

* 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, UserContext 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("10.77.241.203"); 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");

}

/**

(34)

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

*/

public static void getAPIVersion(ACSViewWebServices service, UserContext 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, UserContext 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, UserContext userCtx)

{ try {

System.out.println("---*** Radius Accounting Starts ***---"+"\n");

List acctParam = new ArrayList();

AccountingParam acParam = new AccountingParam(); List valList = acParam.getMatchValues();

(35)

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 =

GregorianCalendar gc2 = newGregorianCalendar(2011, Calendar.AUGUST, 7); XMLGregorianCalendar endDate =

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(); } } }

(36)

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

(37)

C H A P T E R

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

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