How can we help?

vSEC:CMS REST API

Duy Nguyen - Versasec
Duy Nguyen - Versasec
  • Updated

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.

Important
It is expected that readers of this article are familiar with using REST APIs.

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.

Important
If you use Microsoft CA you would need to use Microsoft Enhanced RSA and AES Cryptographic Provider as in below example.

Important
When issuing a web server certificate for the vSEC:CMS server it is important that the Common Name (CN) of the certificate is unique for that server, otherwise you run the risk that the wrong certificate will be chosen. This is because of a limitation in OpenSSL which is used when searching for certificates in the local computer store. vSEC:CMS will use the subject of the certificate (CN) to establish the SSL connection to. Therefore it is also important that the subject of the certificate is resolvable from a DNS perspective from the client side.
Additionally, if SSL/TLS is used, the subject CN is case sensitive. For example, if the certificate subject CN for the SSL/TLS is Myserver.cms.com then you need to enter Myserver.cms.com and not myserver.com.com when configuring the connection URL.

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:

Properties Description

RevocationMode = X509RevocationMode.NoCheck;

(Defaults to Online)

Specifies conditions under which verification of certificates in the X509 chain should be conducted.

No revocation check is performed on the certificate.

AllowedCertificateTypes = CertificateTypes.All;
(Defaults to Chained)

Value indicating the types of certificates accepted by the authentication middleware.

ValidateCertificateUse = true;
(Defaults to true)

Flag indicating whether the client certificate must be suitable for client authentication, either via the Client Authentication EKU, or having no EKUs at all. If the certificate chains to a root CA all certificates in the chain must be validated for the client authentication EKU.

ValidateValidityPeriod = true;
(Defaults to true)

Flag indicating whether the client certificate validity period should be checked.

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.

Note
The managed credential will need to be in a revoked state before you can delete it.

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.

Untitled.png

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. 

Untitled.png

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

Untitled.png

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.Untitled.png

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