vSEC:CMS REST API

Introduction

vSEC:CMS REST API is a Web service ASP.NET Core, using Kestrel implementation, that can be used to perform vSEC:CMS tasks from external systems.

This article will describe how you can setup, configure and use the REST API within your environment.

Setup

Download the REST API package from the Downloads page available from the Home page of the support portal. Run the installer package on the server where vSEC:CMS is installed and follow the on-screen wizard to complete the installation.

Log onto the Admin application. Navigate to Options - Connections and click Add and select Rest API Service. You will now see an option to configure the settings for the REST API.

Open the configuration dialog.

In the Host/IP address enter the hostname or IP address that the application will bind to. In the Port field enter the port to bind on. The port should be a port that is not already used on your server.

Enable the Enable swagger UI option (recommended). The Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place.

Enable Use SSL/TLS option to ensure the communication is secure between the clients and server where the API is used. This is recommended to be configure in any production system for optimal security. The SSL/TLS certificate should be a machine web server certificate available on the vSEC:CMS server.

Additionally, for higher security requirements you can enable Certificate authentication and click the Client Certificates button. From here enter the thumbprint of the client certificate(s) that the clients can use for mutual SSL/TLS and which vSEC:CMS will validate. The client certificate will need to be available on any host where the REST API is being used from.

vSEC:CMS Rest API is configured with below properties:

In the Enabled API section enable the APIs, Service or Lifecycle (or both) that you want to use.

The Service API gives you access to operations that can typically be performed by service/helpdesk persons such as credential PIN reset/unblock. For the full description of available operations see the section below on how to use the Swagger UI.

The Lifecycle API gives you access to operations where actions can be performed on the different life cycle states that a managed credential can be changed to. For the full description of available operations see the section below on how to use the Swagger UI.

From the Lifecycle API you can enable Allow card deletion which will allow you to delete managed credentials using the API.

Enable Require approval if you want to ensure that additional approval is required by an operator when deleting managed credentials. The operator will then need to navigate to Repository - Pending Tasks and right click on the task and Approve to completely remove the credential from the system.

Enable the Management option (available from version 6.10) which will give you a function that can be used to check the system health. This can be useful of you want to have a heartbeat check to ensure that the system is functional and operational. See the System Performance Health Check article for more details on using this function. 

Click the Authentication Tickets and add authentication tickets that will be used by your client applications. Enter a name and Enable the checkbox. Provide the time period that the ticket will be valid for.

Select the authentication ticket entry and click the Generate Ticket button to generate a ticket. This ticket should be managed in a secure way and not be exposed. 

In the Binding Options section the Allowed hosts is used for host filtering to bind your application to specific hostnames. For example, if you replace following:

Allowed hosts * with Allowed hosts example.com
and you try to access your application using http://localhost:xxxx/ address you will get default bad request (400) response because of the host-filtering middleware not allowing the application to bind to any other hostname except example.com. You can have multiple allowed hosts separated by semicolon ; character.

For Protocols select which protocol(s) applicable for your environment. The possible values are the following ones:

• Http1: Accept HTTP/1.1 only. Can be used with or without TLS.
• Http2: Accept HTTP/2 only. May be used without TLS only if the client supports a Prior Knowledge mode.
• Http1AndHttp2: Accept HTTP/1.1 and HTTP/2.*HTTP/2 requires the client to select HTTP/2 in the TLS Application-Layer Protocol Negotiation (ALPN) handshake; otherwise, the connection defaults to HTTP/1.1.

In the Advanced Settings you can configure options for the ASP.NET Core Kestrel web service. Settings would need to be configured using JSON. For example, say you want to configure MaxConcurrentConnections to 100, then you would enter below JSON into the Advanced Settings 

{ "Kestrel": { "Limits": { "MaxConcurrentConnections": 100, "MaxConcurrentUpgradedConnections": 100 }, "DisableStringReuse": true } }

Using Swagger UI

From a browser enter the URL configured from the connection dialog, http(s)://<my-cms-server>:<port>/docs/index.html, where <my-cms-server> and <port> are the settings configured for your environment. Important to append /docs/index.html to the connection URL. 

From the Swagger UI select the Authorize option and paste in the authentication ticket generated in the connection dialog and select Authorize. You can then see and test the different functions available from our REST API.

If you require additional assistance with using our REST API please contact us at: support@versasec.com