Certificate Authentication

Certificate Authentication adds an additional layer of security to UserLock SSO by using client certificates.
When enabled, access to the UserLock SSO service requires a valid user certificate installed on the workstation.

This feature allows administrators to restrict authentication requests to trusted devices only, ensuring that only machines equipped with the correct certificate can initiate Single Sign-On sessions.

🚩️ Before starting:

• Each workstation must have a valid user certificate issued by a trusted Certificate Authority (for example, your Active Directory Certificate Services).

• The certificate must be installed in the Windows certificate store and accessible by the browser.

• UserLock SSO must already be installed and configured.

When a user accesses a SaaS application through UserLock SSO, the browser presents a client certificate.
The SSO service verifies the certificate’s validity and, depending on the configuration, may also check that the certificate is associated with the user in Active Directory.

If the certificate is missing or invalid, the authentication request is rejected.

By default, UserLock SSO does not request client certificates, to avoid unsolicited browser prompts.
To enable certificate negotiation and validation, two configuration steps are required.

When UserLock SSO is installed, a default SSL binding is created automatically.
You must recreate this binding with certificate negotiation enabled. The easiest way to do so is by using a Powershell script.

1. Copy the script below to a .ps1 file on your SSO server.

2. Edit the $port value to match the port used by your UserLock SSO URL (for example, 443).

3. Run the script in a PowerShell console with administrator privileges.

4. Once executed, the SSL binding will be recreated with client certificate negotiation enabled.

# TODO - Enter the SSO URL port
$port = 443

# Define the binding IP and action
$enable = $true
$ipport = "0.0.0.0:$port"

# Get the current binding info
$sslCerts = netsh http show sslcert | Select-String -Pattern $ipport -Context 0,6
if ($sslCerts) {
  # Extract certhash and appid from the output
  $lines = $sslCerts.Context.PostContext
  $certhash = ($lines | Where-Object { $_ -match "Certificate Hash" }) -replace ".*: ", ""
  $appid = ($lines | Where-Object { $_ -match "Application ID" }) -replace ".*: ", ""
  Write-Host "Found binding on $ipport"
  Write-Host "Certificate Hash: $certhash"
  Write-Host "AppID: $appid"

  # Delete the existing binding
  Write-Host "Deleting existing binding..."
  netsh http delete sslcert ipport=$ipport

  # Recreate the binding with certificate negotiation enabled
  if ($enable) { $cmd = 'enable' } else { $cmd = 'disable' }
  Write-Host "Recreating binding with certificate negotiation $cmd..."
  netsh http add sslcert ipport=$ipport certhash=$certhash appid=$appid certstorename=MY clientcertnegotiation=$cmd
  Write-Host "Binding updated successfully."
} else {
  Write-Host "No SSL binding found for $ipport"
}

Certificate validation settings are defined in the appSettings.json file of the SSO service.

Configuration Parameters:

In recent versions, there is a new configuration section called AuthenticationConfig.
Windows authentication settings (ntlm, kerberos, negotiate) have been moved from ListeningConfig to this section.
Make sure to update your configuration accordingly.

{
  "ListeningConfig": {
    "https_port": "443",
    "http_port": "",
    "address": "sso.mydomain.com"
  },
  "AuthenticationConfig": {
    "ntlm": false,
    "kerberos": true,
    "negotiate": true,
    "certificateMode": "Allowed",    // None, Allowed, Required
    "certificateFilter": "Thumbprint" // None, Thumbprint, UPN, Raw
  },
  "CertificateLifetime": "12"
}

Recommended Setup:

• Browser not prompting for a certificate
  → Ensure that certificate negotiation is enabled on the SSL binding (Step 1).

• “Invalid certificate” errors
  → Verify that the certificate chain is trusted by the SSO server and that the user certificate matches the configured filter type (Thumbprint, UPN, etc.).

• Users blocked after enabling “Required” mode
  → Confirm that all machines have valid certificates installed before switching to this mode.