Authentication

Serviceability limits access to its services through HTTP 1.0 Basic Access Authentication, a transaction scheme described in RFC 2617. The advantage of HTTP Basic Access Authentication is the simple implementation, including using only standard HTTP headers and, when using a web browser, the browser implements and manages the login dialog.

Using Basic Authentication

HTTP Basic Access Authentication requires authorization credentials in the form of a user name and password before granting access to a specific URL. The client application can obtain the user name and password through a challenge dialog or the application can use previously stored values. The user name and password are passed as Base64 encoded text in the header of a subsequent HTTP transaction.

Authorize All Serviceability Requests

• Serviceability requests are authorized using HTTPS basic authorization
• Authorization header with <user>:<password> in BASE64 coding
• Authorization: Basic YXhsVXNlcjpjaXNjbw==
• BASE64 coding can EASILY be decoded
• Authorization secure only because HTTPS is used

Security

Cisco requires that all Serviceability transactions be conducted over a secure session, such as HTTPS. Any non-HTTPS requests may be redirected to the HTTPS port.

Depending on the connection technology used, manual installation of the Cisco Unified Communications Manager (Unified CM) self-signed certificate into a local trust store for the application may be needed.

Authentication Best Practices

Authenticating the username/password in an API request is a relatively heavy operation.  If an application is making multiple, rapid API requests where each request includes Basic Auth credentials this may result in throttling by CUCM and HTTP 503 "Service Unavailable" responses.

The Servicability XML API services create and maintain "session" contexts each time an API request arrives with Basic Auth credentials - this context includes the cached authentication result for the username/password set.  In the response to the initiating request, the API service will include several HTTP cookies (JSESSIONID and JSESSIONIDSSO) which can be used to access this session later:

Example response cookies:

HTTP/1.1 200

Status: 200

Set-Cookie: JSESSIONIDSSO=3E75F33007BE70BCD9B10E39719666ED; Path=/; Secure; HttpOnly

Set-Cookie: JSESSIONID=BB166F5B3928CE833F0101AF40777358; Path=/realtimeservice2/; Secure; HttpOnly

A client application can re-use the session by saving the cookies and sending JSESSIONID /JSESSIONIDSSO cookies back in each subsequent request.  This can significantly improve the response speed of API requests, and reduce overall performance impact on CUCM:

Example subsequent request cookies:

POST /realtimeservice2/services/RISService70

Content-Type: text/xml

Cookie: JSESSIONIDSSO=3E75F33007BE70BCD9B10E39719666ED

Cookie: JSESSIONID=BB166F5B3928CE833F0101AF40777358

Note: sessions are expired after 20 minutes with no activity.  Cookie-auth requests sent after a session has been removed will receive a 401 "Unauthorized" response.  The application can then simply re-send the request including the Basic Auth username/password again, which will result in a new session with a new set of cookies.

Developers should code/configure applications to support cookies/sessions when making serviceability API requests. In most HTTP libraries, this is relatively simple to implement.