Authentication

Overview

Certificate Management limits access to its services through HTTP 1.0 Basic Access Authentication. It is a transaction scheme described in RFC 2617. The advantage of HTTP Basic Access Authentication is that it's simple to implement. It uses 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 username and password before granting access to a specific URL. The username and password are the OS admin credentials for the UC server. The username and password are passed as Base64 encoded text in the Authorization header. All certificate management API requests require authentication for access.

Note: OS admin credentials could be unique for each server in the cluster.

Create a dedicated user for Certificate Management APIs. User can be created using set account name command with required privilege:

• privilege 0 would mean that the user can only exercise Read APIs.
• privilege 1 would mean that the user can exercise both Read/Write APIs.

The Certificate management API requires a header parameter of Authorization with base 64 encoded format of username and password to provide authorization for each request.

{
"Authorization": "Basic <Base64encoded username:password>"
}

curl -X 'GET' \
  'https://editor.swagger.io/https/platformcom/api/v1/certmgr/config/csr?service=tomcat' \
  -H 'accept: application/json' \
  -H 'X-Request-ID: abc1-2buj'
  -H 'Authorization: Basic <Base64encoded username:password>'

Note: A user can be deleted using delete account command.

Security

Cisco requires that all Certificate Management APIs transactions be conducted over a secure session, such as HTTPS. Any non-HTTPS requests will be permanently redirected with status code 301. Depending on the connection technology used, you may need to manually install the server's self-signed certificate into a local trust store for your application.

Authentication Best Practices

A client application that intends to perform multiple requests could maintain a certificate management session by supplying a session cookie when it makes subsequent requests. This will ensure quicker responses and less overhead on the server and its authentication mechanisms (avoiding throttling and HTTP 503 "Service Unavailable" responses.)

Client requests which are authenticated via Basic Auth are given a cookie named 'JSESSIONIDSSO' in the response. This cookie can be provided in subsequent requests (instead of the Basic Auth 'Authorization' header) to re-use the authentication session.

Cookie: JSESSIONIDSSO=2723FD93559E7FA7E17F0E7958D13; Path=/; Secure; HttpOnly

A developer should code their client to properly handle this cookie. In most HTTP libraries, this is simple and usually involves only a few lines of code.