Certificate Authentication
Certificate Authentication strengthens UserLock SSO security by checking a user certificate at sign-in. In Required mode, only workstations equipped with a valid user certificate can access the SSO service, so Single Sign-On connections come exclusively from trusted, managed devices.
Certificate authentication lets UserLock SSO ask the browser for a user certificate when a user signs in. Depending on the configuration, the certificate is used to:
restrict sign-in to devices that hold a certificate issued by an authority you trust
check that the certificate belongs to the user who signs in
sign the user in without a password, followed by UserLock MFA
🚩 Before starting
UserLock SSO is installed and configured.
Each user has a certificate with the Client Authentication usage, and its private key, in their personal certificate store on the workstation (for example from the AD CS User template).
On the SSO server and on every backup SSO server, the root certification authority of these certificates is in Trusted Root Certification Authorities and in Client Authentication Issuers (Local Computer). Without it, browsers offer no certificate: Allowed then has no effect and Required denies access to every user.
If certificateFilter is used, the link between certificate and user exists in Active Directory:
Raw: the certificate is published in the user's userCertificate attribute (templates with Publish certificate in Active Directory);
Thumbprint: the user's altSecurityIdentities attribute contains X509:<SHA1-TL> followed by the certificate thumbprint;
UPN: the certificate carries the user's UPN in its Subject Alternative Name.
To add the root authority to Client Authentication Issuers: open certlm.msc, right-click Client Authentication Issuers > Certificates, select All Tasks > Import and import the root certificate.
When a user accesses a SaaS application through UserLock SSO, the SSO server asks the browser for a client certificate (Allowed and Required modes).
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 invalid, the authentication request is rejected. If no certificate is presented, the request is rejected in Required mode only; in Allowed mode the user signs in as usual.
When certificateFilter matches the certificate to a user who is not already signed in with Windows authentication, and UserLock requires MFA for that user, the user signs in without a password, followed by UserLock MFA.
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.
Certificate validation settings are defined in the appsettings.Production.json file of the SSO service (C:\ProgramData\ISDecisions\UserLock\SSO\).
Configuration Parameters:
Setting | Description | Values |
|---|---|---|
certificateMode | Defines whether certificates are used and enforced. |
|
certificateFilter | Specifies how to identify the user in Active Directory using the certificate. |
|
Note
The certificate chain is always validated, and its root authority must be in the Client Authentication Issuers store of the SSO server. If not, access is denied even when certificateFilter is None.
⚠️ Security note – UPN filter
With certificateFilter set to UPN, the SSO trusts the UPN written in the certificate. If a certificate template issued by a trusted authority lets users supply the subject in the request and includes the Client Authentication usage, any user allowed to enroll can obtain a certificate carrying another user's UPN and start a password-less sign-in as that user (that user's UserLock MFA still applies). Prefer Raw or Thumbprint, which require a link stored on the user account, or make sure no such template is issued by the authorities in Client Authentication Issuers.
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:
Scenario | Recommended Mode | Description |
|---|---|---|
Testing or initial deployment |
| Lets you test certificate authentication without blocking users who do not yet have a certificate. |
Full enforcement |
| Ensures that only users with valid certificates can authenticate. |
⚠️ 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.
On the SSO server, start UserLock Configuration Wizard.
Open the Single Sign-On module.
Update the configuration without changing any setting.
The update:
rebuilds both SSL bindings of the SSO port (0.0.0.0 and [::]): with Allowed or Required, client certificate negotiation is enabled and Client Authentication Issuers becomes the list of authorities announced to browsers; with None, negotiation is disabled;
restarts the UserLock SSO service, which reads the mode and the filter at startup.
On each backup SSO server, start the wizard and click Update in Backup services: it takes the mode of the primary server.
⚠️ Do not change the SSL binding by hand
Every update rebuilds it from certificateMode. Before testing, users must close all browser windows: a browser that reuses an earlier session is not asked for a certificate.
The browser does not ask for a certificate
certificateMode is None, or the configuration was not updated after the file was edited (Step 2).
On the SSO server, both bindings must show Negotiate Client Certificate: Enabled and Ctl Store Name: ClientAuthIssuer (check with
netsh http show sslcert ipport=0.0.0.0:<port>, thenipport=[::]:<port>).The root authority of the user certificates must be in Client Authentication Issuers: browsers only offer certificates issued under the authorities listed there.
The user certificate must have the Client Authentication usage and its private key, in the user's personal store.
Close all browser windows after a change: a reused session is not asked for a certificate.
“A certificate is required.”
Required mode, and no certificate was presented: the user cancelled the prompt or has no matching certificate.
“The certificate is not trusted.”
The certificate chain does not build on the SSO server, or its root is not in Client Authentication Issuers.
“Certificate not found in Active Directory.”
certificateFilter could not match the certificate to an Active Directory user, or the certificate belongs to a different user than the one already signed in with Windows authentication.
A Windows credentials prompt appears instead of password-less sign-in
certificateFilter is None: password-less sign-in is not available.
The certificate is not linked to the user for the chosen filter (see Before starting).
UserLock does not require MFA for this user: the SSO then uses Windows authentication.