View
9
Download
0
Category
Preview:
Citation preview
COL-21512-02
C H A P T E R 1
OverviewAccess 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, page 1-2
Enabling Web Services on the Cisco PAM Server, page 1-2
–
– Purchasing and Installing the Cisco PAM API License, page 1-3
Executing API Requests, page 1-7
API URLs, page 1-7
Namespaces, page 1-8
WSDL File Location, page 1-8
Request and Response Samples, page 1-8
Authentication and Authorization, page 1-9
API Security, page 1-10
Understanding Unique IDs, page 1-10
API Logging, page 1-11
1-1isco Physical Access Control API Reference Guide
Chapter 1 OverviewFunctionality Supported in Release 1.2.0
Functionality Supported in Release 1.2.0
• authenticateUserobject 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, page 1-9 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
•
•
Enabling the API Service on the Cisco PAM Server
Step 1 Cisco Physical Access Manager User Guide
Step 2 Monitoring Status
1-2Cisco Physical Access Control API Reference Guide
OL-21512-02
Enabling Web Services on the Cisco PAM Server
Figure 1-1 Services tab in the Cisco PAM Server Administration Utility
Step 3 Enable
Enabled
Tip Disable
Purchasing and Installing the Cisco PAM API License
•
• , page 1-4
• Verifying the Installed Licenses, page 1-6
Displaying the Cisco PAM Appliance Serial Number, page 1-6
For more information on server configuration and optional licenses, see the .
Purchasing the API License
Step 1
1-3
Chapter 1 OverviewEnabling Web Services on the Cisco PAM Server
Step 2http://www.cisco.com/en/US/ordering/index.shtml.
Note CIAC-PAME-WSAPI=
When the purchase is complete, you are issued a Product Authorization Key (PAK) in paper form, or in an email message.
Step 4
Installing the API License
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, page 1-4
• Option 2: Obtain the License File from the Cisco Web Site, page 1-5
Option 1: Enter the Product Authorization Key to Download the License File
Note
Step 1
Step 2
Step 3 Setup License
PAK
Step 5 Update
1-4Cisco Physical Access Control API Reference Guide
OL-21512-02
Figure 1-2 Installing Optional Feature Licenses
Step 6 Features
Option 2: Obtain the License File from the Cisco Web Site
Step 1
Step 2
Step 3 .lic
Browse
Update
Step 7
1-5
Chapter 1 OverviewEnabling Web Services on the Cisco PAM Server
Verifying the Installed Licenses
Step 1
Step 2
Figure 1-3 License Features List
Displaying the Cisco PAM Appliance Serial Number
Step 1
Step 2 Server Status
Step 3 Server Serial Number
1-6Cisco Physical Access Control API Reference Guide
OL-21512-02
Executing API Requests
Figure 1-4 Cisco PAM Appliance Serial Number
Executing API Requests
SOAP/HTTP and XML/HTTP binding.
The Cisco Physical Access Control API is exposed using the WSDL 1.1 specification.
API URLs, page 1-7
Namespaces, page 1-8
WSDL File Location, page 1-8
Request and Response Samples, page 1-8
PI URLs
type = text/xml, and in the content, request payload.
SOAP/HTTP
•<cpam-server-ip-address>
<cpam-server-ip-address>
XML / HTTP
•
•
1-7
Chapter 1 OverviewExecuting API Requests
Tip ?wsdl
Namespaces
•
•
Note
•
•
WSDL File Location
acws/services/psimws?wsdl
Tip You can also view the WSDL file by including at the end of any of these API URLs.
Request and Response Samples
1-8Cisco Physical Access Control API Reference Guide
OL-21512-02
Chapter 1 OverviewAuthentication and Authorization
Authentication and Authorization
secCtx secCtx
Note
Ending an API session
•
•
•
•
Note )
API Username and Password
•
•
Tip
1-9Cisco Physical Access Control API Reference Guide
OL-21512-02
SSL certificate
Understanding Unique IDs
•
• unique IDunique ID
unidZ4JT5umCTzyCmVfvI6RAKw==
Table 1-1 Methods for Preventing a Client from Rejecting the Cisco PAM Server Self-Signed
Certificate
Method Notes
Java client, configure the SSL libraries for your clients to trust the self-signed certificate by using the Java keytool to import the certificate into the client truststore.
Procedure:
1.cpamadmin
sudo su
cpamservercert.jks
1-10
API Loggingcatalina
/opt/cisco/cpam/apache-tomcat/logs
webapp.log
/opt/cisco/cpam/logs
Recommended