Table Of Contents

Using the UCP Web Service

Understanding the Methods in the UCP Web Service

User Authentication

User Change Password

Using the WSDL File

Downloading the WSDL File

UCP WSDL File

Request and Response Schemas

User Authentication Request

User Authentication Response

User Change Password Request

User Change Password Response

Working with the UCP Web Service

Sample Client Code

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

•Using the WSDL File

•Working with the UCP Web Service

Understanding the Methods in the UCP Web Service

The UCP web service comprises the following methods:

•User Authentication

•User Change Password

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.

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

•UCP WSDL File

•Request and Response Schemas

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

<!--**************************************************-->

<!-- Copyright (c) 2009 Cisco Systems, Inc.-->

<!-- All rights reserved.-->

<!--**************************************************-->

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

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

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

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

<!--

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

•User Authentication Response

•User Change Password Request

•User Change Password Response

User Authentication Request

<message name="AuthUserRequest">

<part name="user_name" element="changepass:usernameType" />

<part name="password" element="changepass:passwordType" />

</message>

User Authentication Response

<message name="AuthUserResponse">

 <part name="authUserResponse" element="changepass:ResponseType" />

</message>

User Change Password Request

<message name="ChangeUserPassRequest">

<part name="user_name" element="changepass:usernameType" />

<part name="current_password" element="changepass:passwordType" />

<part name="new_password" element="changepass:passwordType" />

</message>

User Change Password Response

<message name="ChangeUserPassResponse">

<part name="changeUserPassResponse" element="changepass:ResponseType" />

</message>

Working with the UCP Web Service

You can create custom web-based applications to enable users to change their own password for your enterprise. This section describes how you can run a sample application that is developed using Python and provides the sample client code.

The ACS web interface provides a downloadable package that consists of:

•Python SOAP libraries for Linux and Windows

•Python script

•ReadMe—Contains installation instructions

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

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.

---