Unable to register vCenter SSO with HCX

Products

VMware HCX

Issue/Introduction

On the HCX admin page 9443, under Configuration -> SSO . The SSO registration failed with the following error:
"Lookup service is not reachable at https://<FQDN-or-ip>. Please enter a valid SSO url - https://<domain|ip>"

vCenter registration is unaffected on the HCX admin 9443 page.

The following error is logged in the HCX Manager at /common/logs/appliance-management/appliance-management.log : "Cannot load STS signer certificate."

<timestamps> UTC [https-jsse-nio-9443-exec-7, , ] ERROR c.v.h.a.c.LookupServiceConfigValidator- Cannot load STS signer certificate from https://<FQDN-or-ip>:7444/sso-adminserver/sdk/vsphere.local
<timestamps> UTC [https-jsse-nio-9443-exec-7, , ] WARN  c.v.h.a.c.LookupServiceConfigValidator- Cannot access lookup service at https://<FQDN-or-ip>:443/lookupservice/sdk
java.lang.Exception: Cannot load STS signer certificate from https://<FQDN-or-ip>:7444/sso-adminserver/sdk/vsphere.local

Accessing the HCX plugin from vCenter, error in vSphere Client:

Http failure response for https://<FQDN-or-IP>/plugins/com.vmware.hcx.plugin~4.#.#.#####~-####/#.#.#.#-443/vsphere-client/ui/hcx/hcx-ui/rest/hybridity/api/sessions: 401 OK

You may find the following error in /common/logs/appliance-management/appliance-management.log if the issue is related to DNS resolution. For more information, please see "Cause 1" and "Resolution 1":

<timestamps> UTC [https-jsse-nio-9443-exec-3, , ] ERROR c.v.v.hybridity.LookupServiceAdapter- Error querying SSO server configuration: {"status":"FAILURE","failure":"UnknownHostException","details":"java.net.UnknownHostException: <FQDN-or-ip>: Temporary failure in name resolution\

Environment

VMware HCX
VMware vCenter Server

Cause

This issue typically occurs due to one of the following:
1. Name Resolution Failure: The HCX Manager cannot resolve the vCenter Fully Qualified Domain Name (FQDN) or IP address.
2. SSL Trust Mismatch: A mismatch in the Security Token Service (STS) certificate or stale legacy endpoints on the vCenter Server side, often occurring after a vCenter upgrade.

Resolution

Step 1: Verify Name Resolution

Ensure the HCX Manager can resolve the vCenter FQDN and IP address.

Log in to the HCX Manager CLI via SSH.
Run the following command:
```
nslookup <vCenter-FQDN>
```
If the vCenter FQDN contains a .local domain, refer to DNS resolution in HCX Manager will fail when .local domain used in FQDN for specific resolution steps.

Step 2: Address SSL Trust Issues with 'lsdoctor'

If DNS resolution is functional, use the lsdoctor tool to identify and fix SSL trust mismatches or stale configurations.

IMPORTANT: An offline snapshot of the vCenter Server is mandatory before running the lsdoctor tool in an Enhanced Linked Mode (ELM) environment, take snapshots of all vCenter nodes.
For more information on vCenter snapshots, visit VMware vCenter in Enhanced Linked Mode pre-changes snapshot (online or offline) best practice

Download the lsdoctor tool from Using the 'lsdoctor' Tool.
Upload the lsdoctor-#####.zip file to the vCenter Server.
- Note: If you cannot connect via WinSCP, temporarily change the root shell:
  chsh -s /bin/bash root After upload, revert the shell: chsh -s /bin/appliancesh root
Run the tool to check for issues:
```
python lsdoctor.py -l
```
If trust issues are found, run the fix command:
```
python lsdoctor.py -t
```
If stale legacy endpoints are identified, run the cleanup command:
```
python lsdoctor.py -s
```

Step 3: Restart vCenter Services

After applying changes with lsdoctor, restart all vCenter services for the changes to take effect.

For more information, see Stopping, Starting or Restarting VMware vCenter Server Appliance Services.

Step 4: Retry SSO Registration

Log in to the HCX Admin interface at https://<HCX-Manager-IP>:9443.
Navigate to Configuration > SSO.
Enter the correct SSO provider URL and credentials, then click Save.

Additional Information

Please get in touch with the vCenter Support Team for any queries or issues on the lsdoctor tool.

Useful links: