Introduction
Out of the box vSEC:CMS uses an internal database which stores information about credentials registered and managed by the vSEC:CMS along with configuration settings. This database is an SQLite implementation.
However, if it is required to use a third-party database, it is possible to configure the vSEC:CMS to connect to an MS SQL database which can be used to store data for the application.
Optimal integration with vSEC:CMS relies on the expertise of MS SQL DBAs for database configuration and operation.
Configure Support
Prerequisites
A fully functional MS SQL server with a database needs to be available to the vSEC:CMS. The vSEC:CMS will not create the database.
As recommended by MS, the MS SQL database should be encrypted. Please consult your MS SQL database documentation for further information on this.
The following versions of MS SQL Server are supported 2017, 2019, 2022, 2025 and Azure SQL.
At minimum, Microsoft ODBC Driver 17 for SQL Server should be available/installed on the server where vSEC:CMS is installed.
It is possible to check what ODBC drivers (if any) are installed on your server. Open the ODBC Data Source Administrator console and from the Drivers tab you can see the drivers installed.
Sizing and Performance
For general information purposes the database sizing and performance can vary depending on how you use vSEC:CMS. This section offers a high-level overview of MS SQL database sizing and performance considerations for your design.
- For a typical system of 1 thousand managed credentials you could expect up to 100 MB to be allocated for your database..
- It is recommended that you configure the MS SQL transaction log to simple recovery model.
- If MS SQL clustering is used then asynchronous commit mode is recommended for Always On Availability Groups (AGs).
Setup and Migration
From Options - Connections click the Add button and select SQL Database.
Enter a template name and from the drop-down list select vSEC:CMS SQL Database (v4) (MS-SQL).
Select the provider from the Database provider drop-down list and manually enter the database name or click Browse, if it is possible to browse and find the database from your environment, into the Database server field.
From version 6.12.2.2 a Connection encryption drop-down field is available. With this setting you can configure whether the connection to the database is to be encrypted or not. Encryption is enabled by default from ODBC 18 and higher. There are 4 options:
- Optional: If this is selected then the system will use default connection settings for the database provider that is selected, i.e., if ODBC 17 or lower is used then encryption is not enabled by default.
- Enabled: If this is selected then the system will try to establish an encrypted connection using the selected database provider. In this case server certificate validation will be performed. This is not a proprietary configuration for vSEC:CMS. It is expected that person(s) with skills in MS SQL have already setup the certificate trust for the ODBC provider used in this case.
- Enabled (Trust server certificate): If this is selected then the system will try to establish an encrypted connection using the selected database provider. In this case the certificate will automatically be trusted, i.e., skip server certificate validation.
- Disabled: If this is selected then the connection will not be encrypted.
If a dedicated SQL user account is to be used for the connection credential enable Use SQL server authentication mode checkbox. Enter the name and password into the available fields. Otherwise the Windows service account that vSEC:CMS Service is running under will be used to connect to the MS SQL database.
If a dedicated Windows account is to be used for the connection credential then it will be required to follow the instructions as described in the article Configure Dedicated Windows Service Account.
Manually enter the database name in the Name field or click the Get Databases button if it is possible to find the database in your environment.
If all settings are configured correctly then click the Test button to test the connection end-to-end. You should see a success dialog as below if the connection is successful.
Click the Save button which will trigger the migration flow to MS SQL. You will see a dialog with a summary of what will be migrated and an estimate of the time it will take to migrate in full. Click Start to begin the migration.
vSEC:CMS needs to have read/write and db_owner permissions on the MS SQL database. db_owner permissions are only required during the migration phase and if the SQL schema needs to be updated. Once the migration is done you can remove db_owner permission and if a schema update is required you can temporarily enable db_owner permission to perform the schema update and disable once this is done.
Below is an example of what permissions the SQL user would need.
Advanced Configurations
If your environment requires advanced ODBC connection settings (as described here) beyond what is available in Options > Connections, you can override them via the Windows Registry on the vSEC:CMS server. This section guides you through the process. Because Versasec has not tested every parameter combination, we strongly recommend consulting your Versasec provider before making any registry updates.
We will describe how this can be done by using a simple example where we will demonstrate configuring a connection to a MS SQL server instance where the following will be configured in the connection string:
- Driver name
- Server name
- Database name
- MultiSubnetFailover
- Trusted_Connection
- Trusted_Connection
- TrustServerCertificate
On the server where vSEC:CMS is installed stop all vSEC:CMS services.
Open a command prompt as administrator and change directory to the root of the vSEC:CMS installation folder, typically here C:\Program Files\Versasec\vSEC_CMS S-Series. Run this command:
CmsService.exe -statusA dialog will popup after sometime. If your database is large this can take a few minutes to appear.
Make a note of the template ID, for example, in the screenshot above the ID is 0x001a0001, which will be used later. Translate this hexadecimal value to its decimal value, for example the ID above equates to a decimal value of 1703937.
You will need to know your MS SQL server, ODBC driver name and database name. This information will also be seen from the screenshot above so make a note of these. From the example above these are:
- [VSEC-CMS-SERVER]
- [ODBC Driver 18 for SQL Server]
- [vsec-cms]
This information needs to be translated into a connection string and put into a Registry String entry. The connection string uses ini one line format, therefore it’s important to understand that the following characters of section, key and value have to be quoted by backslash: \\ \. \= \; \r \n \t \ (Space)
Open Regedit and navigate to [HKEY_LOCAL_MACHINE\SOFTWARE\Versatile Security\vSEC_CMS_T\Service]. Create a String named db.mssql.config.1703937, where 1703937 is the decimal ID value (calculated earlier) of the connection template that we are going to override.
The value for the string then needs to be constructed. For this example it would look like below:
mssql.connstrg=Driver\={ODBC\ Driver\ 18\ for\ SQL\ Server}\;Server\=VSEC-CMS-SERVER\;Database\=vsec-cms\;Trusted_Connection\=yes\;TrustServerCertificate\=yes\;MultiSubnetFailover\=yesStart the vSEC:CMS service and check that the connection is working by performing a typical vSEC:CMS operations(s).
The registry setting always overrides what is configured in the MS SQL connection under Options - Connections.
Limitations
The current implementation of the MS SQL database support has some limitations which are important to note. These are:
- If, on startup of the vSEC:CMS, the MS SQL database is unreachable the application will not start;
- It will only be possible to add one SQL connection of this type on any one installation of the vSEC:CMS;
- Once the MS SQL connection is set up and in use it will not be possible to roll-back to the internal database.