---
locale: "en"
updated_at: "2025-10-29T10:51:51.786Z"
canonical: "https://www.isdecisions.com/en/userlock/docs/guides/sso/certificate-authentication"
---

# Certificate Authentication

Verify users and devices in UserLock SSO using trusted client certificates.

## Overview 

**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](/userlock/docs/guides/sso/install-configure-sso).

## How It Works

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.

## Enabling Certificate Authentication

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.

## Step 1 – Enable Certificate Negotiation on the SSO Server

> **⚠️ Warning**
>
> If you plan to use **Required** certificate mode, make sure all users have their certificate deployed before enabling it. Otherwise, they will be unable to authenticate.

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.

#### Instructions

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.

```powershell
# 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"
}
```

## Step 2 – Configure Certificate Validation in UserLock SSO

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

**Configuration Parameters:**

| Setting | Description | Values |
| --- | --- | --- |
| certificateMode | Defines whether certificates are used and enforced. | `None` (default): certificates ignored  `Allowed`: validates certificate if present  `Required`: rejects authentication if certificate is missing or invalid |
| certificateFilter | Specifies how to identify the user in Active Directory using the certificate. | `None`: no user lookup  `Thumbprint`: matches AD user via altSecurityIdentities  `Raw`: matches via userCertificate attribute  `UPN`: uses the certificate’s Subject UPN |

> **Note**
>
> The certificate trust chain is always validated.
> If certificate authentication is active and the certificate is not trusted, authentication will fail even if the filter is set to **None**.

#### Example Configuration

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.

```json
{
  "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:**

| Scenario | Recommended Mode | Description |
| --- | --- | --- |
| **Testing or initial deployment** | `Allowed` | Lets you test certificate authentication without blocking users who do not yet have a certificate. |
| **Full enforcement** | `Required` | Ensures that only users with valid certificates can authenticate. |

## Troubleshooting

- **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.