How to change vCenter Server Single Sign-On (SSO) domain

• Author
• Recent Posts

Vladan Seget

Vladan Seget is an independent consultant, professional blogger, vExpert 2009-2021, VCAP-DCA/DCD and MCSA. He has been working for over 20 years as a system engineer.

Latest posts by Vladan Seget (see all)

• How to use VMware vSAN ReadyNode Configurator - Fri, Dec 17 2021
• VMware Tanzu Kubernetes Toolkit version 1.3 new features - Fri, Dec 10 2021
• Disaster recovery strategies for vCenter Server appliance VM - Fri, Nov 26 2021

SSO Domain Repointing was introduced in vSphere 6.7 to allow the repointing of a vCenter Server from one SSO Domain to another. Let's say you have an environment with a couple of vCenter Servers, each within one site. One day, your boss tells you that your company just bought another company and that you need to manage the new environment. By repointing the other company’s SSO domain to your company's SSO domain, you'll be able to "join" that other vCenter Server to your organization and manage all the vCenter Servers with Enhanced Linked Mode (ELM). You can also use repointing to separate SSO domains if your company sells one part of the business to another company.

This post is quite technical, but don't worry—we explain all the necessary operations and the tools you'll need in detail.

Note this is not supported with vCenter installed on Windows. It works only with vCenter Server Appliance (VCSA).

In our example below, you can see we have a vCenter Server with an SSO domain called "company.com," and we'll be migrating it into an existing domain called "vsphere.local."

How to repoint a vSphere SSO Domain

We must first enable SSH and the BASH shell to be able to log in to our VCSA appliance via the SSH client. To do so, connect to the administration interface of the VCSA via https://ip_of_vcsa:5480 and log in with the root account and password.

Then go to Access > Edit

Enable SSH access on vCenter Server Appliance

Click the SSH login and BASH shell by entering some value greater than 0 for the BASH shell.

Click to enable SSH access

Now log in to the VCSA appliance via a Putty client. Putty is one of the free SSH clients I use in my lab. There are many other SSH clients; it is easy to find them on the Internet.

Let's log in to our source VCSA appliance now. After providing root credentials at login, type "shell" to access the BASH shell.

Log in to the VCSA appliance with the Putty client

We can then issue a command that will show us the various options that are available for repointing or reconfiguring the SSO domain.

Many architectural options are possible, since VMware Platform Services Controller (PSC) can also be installed as a separate virtual appliance. But in our case, we have PSC running on the same virtual machine (VM) as the vCenter Server.

Type the "cmsso-util" command and press Enter.

Use cmsso util to see the options

We will be migrating this vCenter Server into an existing SSO domain, so we need to do a "precheck" operation and review any conflicts. After the precheck, we can use the "execute" option, which will, as its name suggests, execute the actual operations.

Note: You might also need to merge two domains to create a third (new) SSO domain, rather than migrating anything to an existing domain. In this case, you don't need to perform the precheck since you don't expect any conflicts.

The default resolution mode for Tags and Authorization conflicts is Copy, so even if you don't verify whether there are conflicts, you might end up with some doubles at the destination.

We'll launch the precheck command now.

The syntax:

cmsso-util domain-repoint -m pre-check --src-emb-admin Administrator --replication-partner-fqdn FQDN_of_destination_node --replication-partner-admin PSC_Admin_of_destination_node --dest-domain-name destination_PSC_domain

In my case, the command looks like this:

cmsso-util domain-repoint -m pre-check --src-emb-admin Administrator --replication-partner-fqdn vcsaphoton.lab.local --replication-partner-admin Administrator --dest-domain-name vsphere.local

where my destination domain name is "vsphere.local" and my destination VCSA fully qualified domain name (FQDN) is "vcsaphoton.lab.local."

Note: I recently wrote an article entitled Change a VMware vCenter Server Appliance (VCSA) system name (FQDN). You might find it useful.

You are prompted for the Administrator's password twice, once for the source vCenter Server and once for the destination vCenter Server.

Domain repoint precheck

Validate by typing "Y." After few minutes, you'll get a recap screen that looks like this:

Location of registered conflicts are registered

You should now go and check the "conflicts.json" file, as you see on the screen. For our lab article, we know we do not have any tags or authorizations that would conflict with the destination system, so we can skip that.

After the precheck, we can now finally use the "execute" option, which has replaced the "pre-check" option. This time, the operation takes more time as the system must not only copy all files over to the destination, but also uninstall the platform services controller and reinstall it.

cmsso-util domain-repoint -m execute --src-emb-admin Administrator --replication-partner-fqdn vcsaphoton.lab.local --replication-partner-admin Administrator --dest-domain-name vsphere.local

Here is the screenshot.

SSO repointing was successful

To check out the changes, let's have a look at the VCSA management user interface.

After repointing, you can verify the VCSA management interface

Then connect to your vCenter Server as usual and select Menu > Global Inventory list.

Check the global inventory list

The second vCenter Server is displayed here.

After repointing you will see both vCenter servers

If your architecture has some external PSCs, you should consult VMware online documentation and search "syntax of the domain repoint command" because you would need to use different options for external PSCs. It's a shame this command is only available via the command line and is not integrated into the VCSA user interface. It might just be a simple question of time and we will see it in the next major version, though.

This is usually case with VMware, as we could see it with a conversion tool used to convert external PSCs into embedded ones. Starting with vSphere 6.7 Update 2, VMware has provided this utility integrated into the vSphere management user interface, where it was previously available only via a command line.