Unable to Log into HCX Manager UI (Port 443) Due to Role Mapping Mismatch with vCenter Identity Source

Products

• VMware HCX

Issue/Introduction

After deploying an HCX Connector or HCX Cloud Manager appliance, administrators may be unable to log into the HCX Manager user interface on port 443 using vCenter SSO credentials.

Authentication appears to complete successfully, but the login ultimately fails and the user is denied access to the HCX UI.

The HCX Manager logs may show messages indicating that the SAML token was successfully parsed, followed by an authorization failure similar to:

• AccessDeniedException: Could not assign NSP role based on logged in VCenter user group memberships

The logs may also indicate that HCX expected membership in a specific SSO group (for example, an administrator group in the vsphere.local domain), while the authenticated user belongs to a group from a different identity source such as Active Directory.

As a result, HCX cannot assign an internal role and access to the HCX UI is denied.

Environment

VMware HCX (all supported versions)

HCX Connector or HCX Cloud Manager appliance deployed and registered with vCenter Server

vCenter Server configured with Single Sign-On (SSO) and potentially additional identity sources such as Active Directory

Cause

HCX assigns permissions through role mappings to vCenter SSO groups.

During login, HCX performs the following process:

1. Authenticates the user through vCenter Single Sign-On (SSO).

2. Retrieves the user's group memberships from vCenter.

3. Compares those groups against the groups defined in the HCX Role Mapping configuration.

4. Assigns an internal HCX role if a matching group is found.

If the group returned by vCenter SSO does not match any group configured in the HCX role mapping, HCX cannot assign a role to the user and login is denied.

This commonly occurs when the role mapping expects a group from the vSphere SSO domain, while the authenticated user belongs to a group from a different identity source, such as Active Directory.

Resolution

Update the HCX role mapping configuration to include the correct group from the vCenter identity source.

If login to the HCX UI on port 443 is not possible, update the configuration through the HCX Appliance Management Interface (VAMI).

1. Access the HCX VAMI interface:

   • https://<HCX-Manager-FQDN>:9443
2. Log in using the local administrator account created during deployment.
3. Navigate to:
   • Configuration → SSO Configuration
4. Locate the HCX Role Mapping section.
5. Update the System Administrator role mapping (or appropriate role) to include the correct SSO or Active Directory group used for administrative access.
6. Save the configuration.

After updating the role mapping, log in again to the HCX Manager UI:

• https://<HCX-Manager-FQDN>:443

Once the group mapping matches the group returned by vCenter SSO, HCX can successfully assign the internal administrative role and allow login to the HCX Manager interface.

 

or             (Caution: the below method will add a group to the Administrators group in SSO Provider/vCenter giving the group vCenter Administration privileges)

 

Add a group the user is a member of to the SSO group in vCenter.  Check the HCX Appliance Management Interface (VAMI):  https://<HCX-Manager-FQDN>:9443 > Configuration > HCX Role Mapping and check the User Group configured under the HCX Administrator.

 

Example: 

 

In the SSO provider (typically vCenter), find the group configured in the HCX User Group example above

 

Add a Group the user is a member of to the group configured in the HCX Administrator > User Groups.

 

 

Additional Information

The account used to register vCenter via HCX Admin UI page must belong to the vSphere administrators group and have the administrator role assigned.
For more information, check HCX Manager User Account and Role Requirements

If the issue persists, also check the following KB: Unable to register vCenter SSO with HCX