COL-21512-02

C H A P T E R 1

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