The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the environment that you must set up to use the User Change Password (UCP) web service and explains how you can use it.
The UCP web service allows you to authenticate an internal user and change the internal user password. You can use this web service interface to integrate ACS with your in-house portals and allow users in your organization to change their own passwords.
The UCP web service allows only the users in your organization to change their passwords. They can do so on the primary or secondary ACS servers.
The UCP web service compares the new password that you provide with the password policy that is configured in ACS for users. If the new password conforms to the defined criteria, your new password takes effect. After your password is changed on the primary ACS server, ACS replicates it to all the secondary ACS servers.
The Monitoring and Report Viewer provides a User_Change_Password_Audit report that is available under the ACS Instance catalog. You can generate this report to track all changes made to user passwords in the internal database, including the changes made through the UCP web service. You can use this report to monitor usage and failed authentications.
Now, you can download the UCP.war file from ACS 5.8 and use it in the JBoss 5.1.0.GA application with jdk6.
Enabling the Web Interface on ACS CLI
You must enable the web interface on ACS before you can use the UCP web service. To enable the web interface on ACS, from the ACS CLI, enter:
For more information on the acs config-web-interface command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.
Viewing the Status of the Web Interface from ACS CLI
To view the status of the web interface, from the ACS CLI, enter:
For more information on the acs config-web-interface command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.
This following sections describe how to use the UCP web service:
■Understanding the Methods in the UCP Web Service
The UCP web service comprises the following methods:
The User Change Password method authenticates a user against an internal database and changes the user password.
Use the changeUserPassword method for applications that require a single-step procedure to change the user password. Changing a user password is normally a two-step procedure. The first step is to authenticate the user and the second step is to change the user password.
The changeUserPassword method allows you to combine the two steps into one. A script or a single-page web application is an example of applications that require a single-step procedure to change the user password.
1. Connect to the UCP web application
2. Enter the username and password.
The authenticateUser web service function is invoked. If your credentials match the data in the ACS internal store, your authentication succeeds.
Note: The user authentication process does not perform any change and does not authorize you to perform any task. You use this process only to verify if the password is correct.
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.
The response from the User Change Password method could be one of the following:
This method displays an error if:
■The authentication fails because of an incorrect username or password.
■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.
This section describes the WSDL file and the request and response schemas for the User Authentication and User Change Password methods. This section contains:
To download the WSDL file from the ACS 5.8 web interface:
1. Log into the ACS 5.8 web interface.
2. Choose System Administration > Downloads > User Change Password.
3. Click UCP WSDL to view the UCP WSDL file.
4. Copy the WSDL file to your local hard drive.
5. Click UCP web application example to download a sample web application and save it to your local hard drive.
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:
This section lists the request and response schemas of the User Authentication and User Change Password methods. This section contains the following schema:
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
■ReadMe—Contains installation instructions
1. Log into the ACS 5.8 web interface.
2. Choose System Administration > Downloads > Sample Python Scripts.
The Sample Python Scripts page appears.
3. Click Python Script for Using the User Change Password Web Service.
4. Save the.zip file to your local hard disk.
Note: After installing ACS 5.8 patch 4, you must run the modules packaged in the Downloads option in ACS on RH 7 which has Python 2.7.5 and OpenSSL 1.0.1e that supports TLSv1.2/1.1 to use the python scripts of UCP on the Linux machine.
Sample Client Code shows a sample.zip file. This file contains a.war file. You have to deploy this.war file within a web server, such as Tomcat. This example allows your application to communicate with ACS through the UCP web service.
Note: The Cisco Technical Assistance Center (TAC) supports only the default Python Script. TAC does not offer any support for modified scripts.
You can use UCP.war file and install it in a JBoss or Apache Tomcat Server. After installing the UCP.war, you can access the UCP web services from the server and change the user password.
To deploy UCP.war in the JBoss server, complete the following steps:
1. Ensure that the JAVA_HOME is set correctly. JAVA_HOME is the location where JDK is installed.
2. Download and extract the JBoss 5.1.0.GA from the link http://www.jboss.org/jbossas/downloads/.
3. Start the JBoss server. You need to navigate to <JBOSS_HOME>\bin\ and run the run.bat (for Windows) or run.sh (for Linux) commands from this location to start the JBoss server. Check the command prompt for the clean startup of JBoss server. Contact the JBoss support team if the JBoss server does not start properly.
4. Enter http://<JBOSS_Installed_Server_IP/HOSTNAME>:< PORT_CONFIGURED> in a browser to launch the JBoss server. If the JBoss server does not start properly, then you need to contact the JBoss support team.
5. Stop the JBoss server using <JBOSS_HOME>/bin/shutdown.bat or shutdown.sh command.
6. Login to Cisco Secure ACS and download UCP.war from the path System Administration > Downloads > User Change Password.
7. Place the UCP.war file in the location <JBOSS_HOME>\server\default\deploy of the JBoss server.
8. Start the JBoss server. You need to navigate to <JBOSS_HOME>\bin\ and run the run.bat (for windows) or run.sh (for Linux) commands from this location to start the JBoss server. You need to verify the JBoss server for a clean startup.
9. Ensure that if the UCP directory is present in the location <JBOSS_HOME>\server\default\work\jboss.web\localhost\. If you cannot find the UCP directory, then you need to download the UCP.war again and repeat the steps 7 to 10.
10. In case if you find any errors or exception even after you deploy UCP.war for the second time, you need to collect the logs from the following location <JBOSS_HOME>\server\default\log\ for further analysis.