Overview

This guide provides instructions for installing and configuring vSEC:CMS Identity. This component enables secure authentication and authorization across applications using the OAuth 2.0 and OpenID Connect (OIDC) protocols.

Prerequisites

Before installation, ensure the following requirements are met:

• vSEC:CMS Version: 7.4 or higher.
• Infrastructure: A user directory (AD, Entra ID, or LDAP) must be configured.
• Credentials: Your preferred FIDO2 hardware credential must be available.

Installation

1. Download: Obtain the latest vSEC:CMS Identity installer from the official Versasec download page.
2. Execute: Run the installer on the same server hosting the vSEC:CMS Service.
3. Configuration: Initial configurations are performed within the vSEC:CMS Admin application (while logged into the server OS) and via filesystem modifications.

Configure Database REST API Connection

The Database REST API enables communication between vSEC Identity and the vSEC Service.

• Navigate to Options - Connections
• Create a Database REST API connection
• Select the appropriate Port.
• Enable Use SSL/TLS and select the corresponding certificate.
• Check the “Enable DB REST API” checkbox
• Click OK to save.

This is distinct from the vSEC:CMS REST API and must be configured independently.

Configure Identity Server Connection

• In Options > Connection, add a new Identity Server connection.
• Port: Select a port (443 is recommended). Note that this port must match the port used in URL origin.
• Security: Select your SSL/TLS certificate and enable Use SSL/TLS. 
• RP ID: Enter the Fully Qualified Domain Name (FQDN) of the vSEC:CMS Identity server (without http/https prefix).
• Origins: Enter the FQDN of the vSEC:CMS Identity server (with http/https prefix).
• CMS DB REST URL: Enter the FQDN of the server running vSEC:CMS Identity, including the http(s) prefix and the port number configured in the Database REST API step.

The Database REST API and the Identity Server cannot share the same port. 

HTTPS is required for OIDC authentication

Configure FIDO2 Passkey Template

In Templates > FIDO2 Passkey Templates, add a new template.

Template Setup:

• Assign a name.
• In Select FIDO2 Idp, choose vSEC:CMS Identity.
• Display Name: Configure as needed; you can use attributes for dynamic naming found in the Configure button.
• Max Display Name Length: Set the character limit.
• Force Discoverable Credential: Enable if you require discoverable passkeys.
• Algorithms: Select supported algorithms. The system defaults to the highest-priority supported option supported by the hardware device when generating the passkeys.
• Identifiers: Input the same Origin and RP ID values as used in the Identity Server Connection. Set the Relaying Party Name to match the RP ID.
• Save your configuration.

Configure FIDO2 Credential Template

FIDO2 Template:

• Navigate to Templates > FIDO2 Template, click Add, and select the Passkey template configured in the previous step.
• Configure as you would for other IdP Passkey templates

Client Integration

Configuring Client Connections

Modify the clients.json file located in /Configuration/ within the vSEC:CMS Identity program files folder. You may manually configure connection data or utilize the tools provided in the /preparation/ directory to generate the required client section.

Example: Configuration

{
    "ClientId": "applicationX",
    "ClientName": "applicationX",
    "AllowedGrantTypes": ["code", "authorization_code"],
    "RequirePkce": false,
    "RequireClientSecret": true,
    "ClientSecrets": [{"Value": "mmMLPWtsI7HBM9qLWZ6A889wGz5gLdqWAsdJ9Xuu6A4RQCo=", "Type": "SharedSecret"}],
    "RedirectUris": ["https://applicationx.lab.versasec.com/"],
    "AllowedScopes": ["openid", "profile", "email", "api", "displayName"],
    "AlwaysIncludeUserClaimsInIdToken": true,
    "AllowOfflineAccess": true
}

Configuration Schema Dictionary

Below is a reference guide explaining the properties used across the client configurations: