SSO troubleshooting and recovery
Learn how to restore UserLock Single Sign-On (SSO) service availability and diagnose common SSO connection issues. This guide explains how to switch to a backup SSO server in case of failure and how to use the SSO Assistant to identify and resolve configuration problems.
UserLock Single Sign-On (SSO) provides secure and seamless authentication for web and cloud applications.
If the SSO service becomes unavailable, users will not be able to access any protected SaaS application.
To ensure service continuity, you can deploy one or more backup SSO servers.
If the primary SSO server fails, a simple DNS update redirects traffic to the backup server, restoring user access.
👉️ For installation and configuration instructions, see the Install a backup SSO server guide.
Without a backup server, an SSO outage prevents users from signing in to any SaaS application protected by UserLock.
The backup SSO server allows you to restore service quickly with minimal downtime.
If the primary SSO server (YJSSO) fails, requests can be redirected to YJSSOBACKUP to restore availability.
Update DNS
In your internal DNS, update the record of your SSO domain (for example,
yjssobackup.mydomain.com) so that it points to the backup server.
To ensure a fast switchover, keep the TTL (Time To Live) value as low as possible (for example, a few minutes). This limits propagation delays when redirecting traffic to the backup server.Update routing if needed
If your environment uses RRAS routing, update it to direct requests to the backup SSO server.
✅️ Once these updates are made, the backup SSO server becomes active and SSO access for users is restored.
When the primary SSO server is operational again, revert DNS and routing settings to the initial configuration.
Note
You can configure multiple backup SSO servers if needed. Each one will use the same procedure for activation.
If new SSO profiles or configurations were created on the primary server after the backup was set up, restart the backup SSO service to download and apply the latest changes.
The UserLock SSO Assistant helps analyze your configuration and detect issues that may prevent SSO from functioning correctly.
It verifies key system components and can automatically fix certain problems.
Check | Description |
|---|---|
SSL binding | Verifies that the SSL certificate is correctly bound to the SSO service. |
Listening Permission | Ensures that the SSO service can listen on the required port |
Registry Flag | Confirms that registry settings for the SSO service are properly configured. |
Intranet Zone | Checks that the SSO URL is recognized as part of the local intranet. |
Host Names | Verifies hostnames consistency between configuration and DNS. |
Service Files | Checks that all required SSO files are present. |
Service Running | Ensures that the SSO Windows service is started. |
Service Status | Validates that the SSO service is healthy and responding. |
SPN | Verifies the SPN is registered for Kerberos authentication. |
In the UserLock Configuration Wizard, select Single Sign-On ▸ Tools. It will open a new application, the UserLock SSO Assistant
If prompted for Powershell module installation, select Yes
Select Troubleshoot issues related to UserLock SSO and then Configure
If a problem is detected:
Click Fix to attempt automatic resolution.
If the issue persists, contact IS Decisions Support and include a screenshot of the analysis results.
⚠️ Warning
Clicking Clean will reset the configuration and completely disable SSO functionality.