Table Of Contents
Functionality Supported in Release 1.2.0
Enabling Web Services on the Cisco PAM Server
Enabling the API Service on the Cisco PAM Server
Purchasing and Installing the Cisco PAM API License
Verifying the Installed Licenses
Displaying the Cisco PAM Appliance Serial Number
Authentication and Authorization
Overview
Access Control Web Services (ACWS) defines an application programming interface (API) for the following Cisco Physical Access Manager (Cisco PAM) features:
•The Physical Security Integrated Management of access control devices such as doors and locks. For example, an application can receive the events generated when user access is granted or denied. The application can then open or close a door.
•The Visitor Management Application creates visitors and assigns access policies to allow access to specific doors or locations.
•The Badge Enrollment Application provisions badge credentials in the access control system.
This chapter includes general information, and instructions to enable the ACWS API on a Cisco PAM server. It also describes the ACWS authentication method, and the Namespaces and other information used to issue API requests.
Contents
•Functionality Supported in Release 1.2.0
•Enabling Web Services on the Cisco PAM Server
–Enabling the API Service on the Cisco PAM Server
–Purchasing and Installing the Cisco PAM API License
•Authentication and Authorization
Functionality Supported in Release 1.2.0
The API for Cisco Physical Access Control Release 1.2.0 supports the following features:
•Authentication APIs: applications must call the authenticateUser API to retrieve a security context object before calling any other API. The object is provided as a parameter in all subsequent calls for that API session. If the session ends, a new object must be retrieved. See Authentication and Authorization for more information.
•Physical Security Integration Management (PSIM) APIs: for use by the Physical Security Operations Management applications. These APIs return information on access control devices, users, events and alarms. The API provides mechanisms to query events or alarms based on event type, time-interval, and source device criteria.
•Event Notification: notifies a client application that registered a notification callback when an event or alarm occurs. In addition, APIs can query events or alarms based on the event type, time-interval, or source device.
•Door Command APIs:triggers actions based on access control events. For example, when a user attempts to access a door or device, the PSIM APIs can open or close the door.
•Badge Enrollment APIs: provisions badge credentials in the access control system. Also returns information on access levels and schedules.
•Recording External Events: allows applications to log events and alarms in Cisco PAM.
•Fault Codes: API errors return major and minor fault codes. See Chapter 3, "Fault Codes" for descriptions.
Enabling Web Services on the Cisco PAM Server
To enable the Web Services API functionality on the Cisco PAM server, you must purchase and install the optional Web Services license, and enable the API service, as described in the following sections:
•Enabling the API Service on the Cisco PAM Server
•Purchasing and Installing the Cisco PAM API License
Enabling the API Service on the Cisco PAM Server
Step 1 Log on to the Cisco PAM appliance as described in the Cisco Physical Access Manager User Guide.
Step 2 Select the Monitoring tab and then select Status, as shown in Figure 1-1.
The Status window appears by default. This window also appears when you first log on.
Figure 1-1 Services tab in the Cisco PAM Server Administration Utility
Step 3 Click the Enable button for Web Service API.
A confirmation message appears and the Status changes to Enabled.
Tip To disable web services, click Disable.
Purchasing and Installing the Cisco PAM API License
To enable the API functionality, you must purchase the optional API license from the Cisco website and install it on the Cisco PAM server. If the API license is not installed, API requests to the Cisco PAM server return an error.
This section includes the following information:
•Verifying the Installed Licenses
•Displaying the Cisco PAM Appliance Serial Number
Tip For more information on server configuration and optional licenses, see the Cisco Physical Access Manager User Guide.
Purchasing the API License
To purchase the Cisco PAM API license, do the following:
Step 1 Determine the Cisco PAM appliance serial number (the serial number is required to complete the purchase). See Displaying the Cisco PAM Appliance Serial Number for more information.
Step 2 Purchase the licence by contacting your Cisco sales representative or any Cisco reseller. For more information, visit http://www.cisco.com/en/US/ordering/index.shtml.
Note The part number for the Web services API optional license is CIAC-PAME-WSAPI=.
Step 3 When the purchase is complete, you are issued a Product Authorization Key (PAK) in paper form, or in an email message.
Step 4 Continue to Installing the API License for information on the two options used to download and install the license file using the PAK number.
Installing the API License
If your PC is connected to the Internet, you can enter the Product Authorization Key (PAK) to download and install a license file. You can also install a license file stored on a local disk.
This section includes the following information:
•Option 1: Enter the Product Authorization Key to Download the License File
•Option 2: Obtain the License File from the Cisco Web Site
Option 1: Enter the Product Authorization Key to Download the License File
Note To use this method, your PC must be connected to the Internet.
Step 1 Locate the Product Authorization Key (PAK) created with the purchase of the optional feature.
Step 2 Log on to the Cisco PAM appliance. See the Cisco Physical Access Manager User Guide for more information.
Step 3 Click the Setup tab, and then select the License menu, as shown in Figure 1-2.
Step 4 Enter the PAK code.
Step 5 Select Update to download and install the license file on the appliance and activate the features.
Figure 1-2 Installing Optional Feature Licenses
Note If the license file does not download, verify that your PC has Internet access, or use the method described in Option 2: Obtain the License File from the Cisco Web Site.
Step 6 Select the Features tab to verify that the new license was added. See Verifying the Installed Licenses for more information.
Option 2: Obtain the License File from the Cisco Web Site
To use this method, obtain the license file from the Cisco Web site using a PC connected to the Internet, and transfer the file to the workstation used for server configuration.
Step 1 Locate the Product Authorization Key (PAK) created with the purchase of the optional feature.
Step 2 In a Web browser, open the Cisco Product License Registration Web page.
http://www.cisco.com/go/license/
Step 3 Follow the on-screen instructions to complete the form and enter the Product Authorization Key (PAK). When you are done, a license file with the extension
.lic
is sent to your email address.Step 4 Transfer the file to the drive of the PC used for the configuration.
Step 5 In the License screen (Figure 1-2), click Browse to select the license file located on your local drive. When selected, the file name appears in the File field.
Step 6 Select Update to install the license file on the Cisco PAM appliance and activate the features.
Step 7 Select the Features tab to verify that the new license was added. See Verifying the Installed Licenses for more information.
Verifying the Installed Licenses
From the Cisco PAM Server Administration utility, do the following:
Step 1 Select the Setup tab and then select the License menu, as shown in Figure 1-3.
Step 2 Select the Features tab to view the installed licenses.
Figure 1-3 License Features List
Displaying the Cisco PAM Appliance Serial Number
To view the appliance serial number, do the following:
Step 1 Log on to the Cisco PAM Server Administration utility.
See the Cisco Physical Access Manager User Guide, or ask your system administrator for assistance.
Step 2 Select the Monitoring tab, and then select Server Status, as shown in Figure 1-4.
Step 3 Refer to the entry for Server Serial Number.
Figure 1-4 Cisco PAM Appliance Serial Number
Executing API Requests
To execute an API request, send the desired API function or functions to the Cisco Physical Access Manager server. Cisco Physical Access Control APIs support SOAP/HTTP and XML/HTTP binding.
Note The Cisco Physical Access Control API is exposed using the WSDL 1.1 specification.
API URLs
Applications can use one of the following URLs to invoke an API using the HTTP POST method, content type = text/xml, and in the content, request payload.
SOAP/HTTP
•The http URL for WSDL using SOAP/HTTP
http://<cpam-server-ip-address>:8080/acws/services/psimws•The https URL for WSDL using SOAP/HTTP
https://<cpam-server-ip-address>/acws/services/psimwsXML / HTTP
•The http URL for WSDL using XML / HTTP
http://<cpam-server-ip-address>:8080/acws/services/psimxml•The https URL for WSDL using XML / HTTP
https://<cpam-server-ip-address>/acws/services/psimxml
Tip You can view the WSDL file by including ?wsdl at the end of any of these URLs.
Namespaces
Web Services APIs are defined using WSDL and various object types defined by the XML schema. The schema definitions uses the following target namespaces.
•Interfaces, methods and types are defined using the target namespace:
http://cisco.com/physec/acws•BaseDevice is defined using the target namespace:
http://cisco.com/physec.
Note BaseDevice is a type that defines the base device class. AcDevice and CameraDevices are sub-classes of the BaseDevice in their respective namespaces.
•Camera devices are defined using the target namespace:
http://cisco.com/physec/video interfaces.•ACWS devices and video names are derived by extension.
WSDL File Location
The WSDL file is located at the following URL:
https://<cpam-server-ip-address>/acws/services/psimws?wsdl
Tip You can also view the WSDL file by including ?wsdl at the end of any of these API URLs.
Request and Response Samples
Request and Response examples are provided in Chapter 2, "API Functions". To capture additional examples, use a network packet capture tool such as the TCPMon utility.
Authentication and Authorization
Before a method is called, use the authenticateUser API to send the Cisco PAM username and password, and retrieve a security context object (secCtx). Each subsequent API call uses this secCtx object as a parameter to authorize the API action.
Note For the current Cisco PAM release, we recommend using the Administrator username and password for API authentication.
Ending an API session
API sessions end after a default idle time of 10 hours, or you can manually end the session using the logoutUser API.
•If a application session remains idle for a default duration of 10 hours, the session automatically ends and the security context object is deactivated.
•Applications can also use the logoutUser API to end an API session and deactivate the security context object.
•API calls using an expired security context object return a fault. See Chapter 3, "Fault Codes" for more information.
•Cisco PAM Web Service performs an automatic check every 10 minutes for idle sessions to expire.
Note To begin a new API session, you must retrieve a new security context object (using authenticateUser).
API Username and Password
For the current Cisco PAM release, we recommend using the Administrator username and password for API authentication.
Usernames and passwords can also be configured using the Cisco PAM application to limit the API functionality:
•Use the Logins module to create the username and password for Cisco PAM client access.
•Use the Profiles module to define the Cisco PAM modules and commands available to a user.
For example, if an API application or user needs to view devices and events, the Logins username must be assigned a Profile with privileges to view events and devices. If an API user or application will invoke door commands, the username must include a profile with those privileges.
Tip See the Cisco Physical Access Manager User Guide for instructions to configure Cisco PAM logins and profiles.
API Security
The Cisco PAM server and API use SSL for secure communication between the server and clients. The server uses a X.509 certificate (also called an SSL certificate) to verify its identity when a client attempts to connect to the server.
Be default, the Cisco PAM server provides a self-signed certificate, which a client typically rejects. To prevent a client from rejecting this certificate, take one of the of the actions that Table 1-1 describes.
A client verifies its identity with a user name and password that are sent to the server by the client application.
Understanding Unique IDs
Many parameters include a user-defined ID number, and a machine generated unique ID.
•Readable IDs identify a specific record for an object, such as personId or badgeId. For example: a personId might be 3215. In some cases, this readable ID is used in the API request.
•A unique ID (unid) for an object is used in most API requests, and is displayed in the API result. The unique ID for an object (such as a person or badge) is generated by the database and is the unique identifier for any record. For example, the unid for a person object might be
Z4JT5umCTzyCmVfvI6RAKw==
.Review the description for each API to determine which ID type is required.
API Logging
For debugging, API request and response messages are logged in the
catalina
log file located on the Cisco PAM server in the folder:/opt/cisco/cpam/apache-tomcat/logsBy default, Web Service debug logs are written in
webapp.log
which is located in the folder:/opt/cisco/cpam/logs