Planning, designing, and architecting a vSphere SSO Domain for vCenter Server can occasionally feel complex to many VMware Administrators. Whether building new, changing, or redesigning an SSO Domain, vSphere 6.7 has a great new feature to help lessen this complexity. SSO Domain Repointing was introduced to allow the repointing of a vCenter Server from one SSO Domain to another, something that was not possible in vSphere 6.0/6.5. The vCenter Server being repointed, moves from its current SSO domain and joins the other existing domain as another vCenter Server connected via Enhanced Linked Mode (ELM).
This powerful feature can not only help customers with mergers & acquisitions who may have a need to change the name of an SSO Domain but also joining two different SSO Domains into one common domain. If there is a need to repoint a vCenter Server from its current domain to a brand new SSO Domain, that is also possible.
Prerequisites
Before we dive into how to leverage this feature we should discuss some of the requirements and prerequisites that must be considered prior to using it. Repointing is handled by the CMSSO-UTIL command. You may already be familiar with this command utility as it’s used to perform other actions in an SSO Domain such as decommissioning a PSC, or pointing a vCenter Server to another Site, etc. In vSphere 6.7 an additional sub-command (domain-repoint) was added expanding the power of this utility.
The domain-repoint sub-command of cmsso-util is available starting with vCenter Server 6.7 and supports domain repointing for External PSC deployments. In vCenter Server 6.7 Update 1 and later, Embedded and External PSC deployments are supported for domain repointing. Another important prerequisite task is taking a backup. To ensure no loss of data, take a File-Based backup of each vCenter Server before proceeding with domain repointing. In the event of an issue, the vCenter Server can then be quickly restored to its last state.
By running; cmsso-util domain-repoint --help from the vCenter Server appliance shell we can quickly find the usage of the command.
Let’s also recap what a vSphere Single-Sign-On (SSO) Domain is and what it contains. An SSO Domain is the domain that vSphere uses to connect vCenter Servers in a federation. An SSO Domain contains Tags, Licenses, Categories, Global Permissions, Roles, and Privileges. The SSO Domain name defaults to vsphere.local, but can be edited during installation of the vCenter Server to a preferred name. PSC services within the vCenter Server control authentication for the SSO Domain. Adding an Active Directory or LDAP identity source, allows users and groups in that identity source to also authenticate.
What are Conflicts?
It is important to understand that each SSO Domain may contain similarities in contents as well as conflicts for each content type. Prior to an SSO Domain Repoint you have the option to resolve any conflicts before to committing any repointing actions. Conflict discovery is accomplished by performing a pre-check before completing the repointing of the vCenter Server to another SSO Domain. The (pre-check flag) is used with the CMSSO-UTIL command to discover conflicts between each SSO Domain. An example would be: cmsso-util domain-repoint -m pre-check
To make it easy to review and handle any conflicts that may arise, a set of JSON files are produced during any pre-check actions. Pre-check mode fetches the tagging (tags and categories) and authorization (roles and privileges) data from the (PSC) vCenter Server without actually performing the repointing actions.
Four JSON files are produced; All_Privileges.json, All_Roles.json, All_TagCategories.json, and All_Tags.json. These files can be found exported to the /storage/domain-data/ folder on the source vCenter Server where the Domain Repoint command was executed.
Resolving Conflicts
A vSphere Administrator would begin to address any SSO Domain Conflicts found during the pre-check process by reviewing the four JSON files produced.
See the sample Conflict file below:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<----Sample Conflict file code block--->
{
"global":{
"resolution":"MERGE|SKIP|COPY",
"description":"Default resolution option used to resolve Role Conflicts is COPY. The
conflicts list describes the differences between Role entities on source and target PSC. If
the source information represents an empty JSON array, it simply means that all the entity
attributes from source and target are identical. If the source lists few entries, it means
that only these entity attributes are missing from the target. If the target lists few entries,
it means that only these entity attributes are missing from the source. Though a global resolution
can be set, it can also be overridden at each conflict level by providing individual resolution
Let’s further break down the information found in the Conflict file. Each conflict file has few parts that need to be understood:
description: Provides the details on how the conflicts file is read and understood.
source and target: JSON objects that list only the differences between the source and target Platform Services Controller objects.
resolution: User supplies one valid resolution. Valid resolutions are MERGE, COPY, and SKIP.
To specify the resolution for handling conflicts, you can provide a default resolution option for all conflicts within the "global": "resolution" = "MERGE|SKIP|COPY" section. You may also provide a valid resolution option for each of the conflicts individually by editing the resolution property at each conflict level. Doing so, overrides the global resolution option of the conflict file.
Once any conflicts are resolved domain repointing may begin. The repointing operation will migrate Tags, Authorization (Privileges/Roles), and License data from one SSO Domain to another, taking into consideration each conflict and its resolution type.
NOTE: If conflicts within the SSO domain are not addressed, the repointing operation will continue but it will Copy all conflicts to the new SSO domain. This means the SSO domain could end up with multiples of the same Roles, Tags, etc. and manual cleanup will be required on the customer’s behalf. A valid resolution option for each of the conflicts is required for each conflict, individually or globally.
Repointing a vCenter Server
Now that we have a good understanding of the prerequisites for SSO Domain Repointing we can move forward to preforming the Domain Repoint. A few things to remember when performing the repoint. Global Permissions for the Source vCenter Server being repointed to the target/destination domain will be lost. Global Permissions will need to be reapplied manually on the target/destination domain after the repoint is completed. Local users & groups from the Source domain will not be migrated to the Destination domain.
In this example I will be repointing a single vCenter Server (version: 6.7 Update 1) in the SSO Domain “vsphere.local” to an entire new SSO Domain named “nigel.local“. Since there is no other vCenter Server’s in the nigel.local SSO Domain, a pre-check is not required, thus we will not have any conflicts to resolve.
In my lab I am repointing upg-dhcp-1570-vm-055.cpbu.lab which is my vCenter Server 6.7 Update 1. Notice that my Single Sign-On domain is vsphere.local currently. We can also see that the vCenter Server is an embedded deployment type.
Let’s get started by logging in via SSH to the vCenter Server that will be repointed to a new SSO Domain. Provide the root credentials to login to the appliance.
From the appliance shell we can run cmsso-util to review our command syntax. Here we can also see the other functions of the cmsso-util command such as unregister, reconfigure, repoint (for repointing a vCenter Server to another SSO Site), and domain-repoint. We will be using the domain-repoint argument to point our vCenter Server to a new SSO Domain.
Since we are not migrating this vCenter Server into an existing SSO Domain, the is no need to do a pre-check to review any possible data conflicts between the Source and Destination domains. We begin repointing with the following command: cmsso-util domain-repoint -m execute --src-emb-admin Administrator --dest-domain-name nigel.local
NOTE: The SSO Administrator ([email protected]) credentials of the Source vCenter Server are required here. Also, the Destination domain name (--dest-domain-name) equals the name of the new SSO Domain you are pointing the Source vCenter Server to.
To continue, answer the question (Y or N) to confirm all settings are correct to proceed with the repointing operations.
The Domain Repointing operations will now begin. Data is exported from the current SSO Domain, PSC services are updated, SSO data is then imported to the new SSO Domain, CEIP participation status (joined or not joined) is applied, and all services are restarted. At this point, we can now see that our Domain Repoint was a success.
We can further validate this change by logging into the vCenter Server Appliance Management Interface (VAMI) on port 5480.
Final Thoughts
As we have learned, repointing a vCenter Server to another SSO Domain is possible and not very complex. As with any changes to your SSO Domain or vCenter Servers it does require proper planning before execution. It was mentioned above, but please be sure to take a File-Based Backup of each node, Source & Destination, before proceeding with repointing operations.
Also remember that Global Permissions will need to be reapplied manually on the destination domain, as well as any solutions that were registered to the source vCenter Server prior to the repoint will need to be re-registered after repointing has completed. If the repointing process fails, be sure to collect the support bundle first, then revert to the backup taken before this process. I have included a shortlist of domain repointing links below to help navigate the process even further.
