Tips for finding Knowledge Articles

  • - Enter just a few key words related to your question or problem
  • - Add Key words to refine your search as necessary
  • - Do not use punctuation
  • - Search is not case sensitive
  • - Avoid non-descriptive filler words like "how", "the", "what", etc.
  • - If you do not find what you are looking for the first time,reduce the number of key words you enter and try searching again.
  • - Minimum supported Internet Explorer version is IE9
Home  >

KB-17161: Preparing for the Tenant URL Change to

Privileged Access Service ,  

28 February,20 at 11:45 PM


The tenant migration of Application and Endpoint services from the Centrify cloud to Idaptive cloud is expected
to begin October 2019.  Customers will be contacted at least 4 weeks in advance as their tenant is scheduled for migration.

As part of the Idaptive tenant spin-out, the tenant URL for Centrify cloud services will change from to   When the migration is complete, by default, the tenant will broadcast the URL change to the connectors and each connector will modify its own cloudurl attributes in Active Directory and in the connector host machine registry.  The connector will then begin to service requests for This will cause the Centrify DirectControl (CDC) agents that are configured for MFA and are dependent upon the URL, to not be able to locate a connector to service the request.

Prior to the tenant migration, customers are required to take the necessary steps as outlined in this article, otherwise may see the following issues:
  • MFA (Multi-Factor Authentication) will not function on machines in the Centrify DirectControl zone.  The Centrify agent will deny logins that rely on MFA.
  • Error messages could be produced by the CDC agent that indicate the agent does not know the proper tenant URL.  An example of such an error message is as follows:
Jun  1 00:00:01 mylinux adclient[2162]: ERROR <bg:refreshCloudConnectorsInfo> base.cloudconnector.locator Failed to choose a cloud connector for Centrify Cloud connectivity. Centrify agent found multiple connectors serving to different Centrify cloud instances(2) in the forest. Please specify to which cloud instance Centrify agent should connect by selecting a 'Trusted cloud instance' on Cloud tab of zone property.

This article addresses issues with MFA on machines running Centrify DirectControl.   It does not cover MFA that is used for login to the tenant portal.   For additional information regarding portal operations, please see the following FAQ articles:



The process is done in two phases as described below. Phase 1 changes should be performed as soon as possible. Phase 2 changes should be performed as soon as notification arrives that the tenant URL is available  and before the tenant migration is  scheduled.

Phase 1:  Explicitly define the MFA tenant URL to be the domain.
Step 1)  To prevent disruption in MFA, the default behavior (described above), must be overridden such that there is a connector that will still respond to MFA requests after the migration. It is recommended that this override process be performed on approximately half of the connectors in each domain configured with MFA.
To override the Cloud tenant URL:
1) For each domain, identify the connectors that are chosen to have the default behavior override.  The recommendation is to select about half of the connectors available for each domain.

2) Download the attached script overrideurl.ps1

3) On each selected connector host machine, open a PowerShell console as an Administrator and run the script.
PS> .\overrideurl.ps1 -add
User-added image
The script will make a copy of the registry value : HKLM -> Software -> Centrify -> Cloud -> url
The new copy will be named urlOverride.  The urlOverride registry value, can be verified using regedit.exe, or by rerunning .\overrideurl.ps1 without any arguments.
User-added image
4) IMPORTANT:  The above process will configure the connector for the override, but the override will only be realized when the 19.5 connector is installed / upgraded.  If the overrideurl.ps1 script is run BEFORE the connector update, no further steps are needed on the connector machine until Phase 2 as the connector will be restarted automatically upon update.  If the script is run AFTER the 19.5 connector install / upgrade, the connector will need to be stopped and restarted manually.

Step 2) Explicitly configure zones to use as the MFA tenant URL.
   Classic and Auto Zone Requirements:
For classic and auto zone environments, the MFA tenant URL is defined in /etc/centrifydc/centrifydc.conf
Since the URL is already set to use the URL, no further action is needed until Phase 2.


   Hierarchical Zone Requirements:
For environments that have MFA in Centrify hierarchical zones, the Platform instance for the environment needs to be explicitly defined in the zone using the domain.  If the Platform instance is already explicitly defined, no  additional changes are needed until Phase 2.
In past releases, the Platform instance was not always explicitly stored in the hierarchical zone.  In this case, the CDC agent searches through Active Directory to find all connector proxy objects.  It then extracts all tenant URLs.   If more than one URL is found, the CDC agent (adclient) is unable to determine which URL is the correct one to use for MFA.
In order to resolve this ambiguity, the correct Platform instance must be explicitly specified in the hierarchical zone (a parent or grandparent zone can be used as well as the direct zone).  In the example below, the hierarchical zone is DeptName and the tenant URL for MFA is

To set the URL into a zone using Access Manager:
1) Identify the zones that need to be modified. 

To assist in this effort, two scripts have been attached to this article. The first, check_cloud_url.ps1, is a PowerShell script to run on a Windows platform. This script requires the installation of the Centrify PowerShell module. The second, check_zone_cloudurl.tcl is an adedit script that runs on a *nix platform.  Both scripts give the same information, so only one of them needs to be used.  Both are provided here for convenience, so that this step can be done on the platform of choice.   
     A) Run check_cloud_url.ps1 on a windows platform:
i) Download the attached script and save it to the Windows machine.
ii) Open an Administrators PowerShell window and run the script without any arguments to show all the hierarchical zones that need a URL defined. 
PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
PS> .\check_cloud_url.ps1
User-added image

Alternately, the script can also be run with a -V (verbose) option.  This will display ALL hierarchical zones and indicate if they are OK or if they need the URL set.  The output from the script, either with or without the -V option, can be lengthy depending on how many zones are defined.  Centrify recommends redirecting the output to a file and then using a common text editor to see all the contents.

     B) Run check_zone_cloudurl.tcl on a *nix platform:
i) As root, download the attached check_zone_cloudurl.tcl script and save it to a *nix platform.

ii ) Make the script executable by doing:
# chmod 744 check_zone_cloudurl.tcl
iii) Run the script using a -m argument to use the machine credentials to retrieve the zone information.  This command will show all the hierarchical zones that need a URL defined.
# ./check_zone_cloudurl.tcl -m
User-added image

Alternately, the script can also be run with a -V (verbose) option.  This will display ALL hierarchical zones and indicate if they are OK or if they need the URL set.  The output from the script, either with or without the -V option, can be lengthy depending on how many zones are defined.  Centrify recommends redirecting the output to a file and then using a common text editor to see all the contents.

2) Browse to the zone in Access Manager, right click, and pick Properties
User-added image 
3) Open the Platform tab.
4)  If the Platform instance is already correctly defined to be a tenant, no changes are needed until Phase 2.  If the tenant is empty (as seen in the image below) or if the URL is pointing to the incorrect tenant, explicitly define the correct URL.  Check Override the Platform instance for the zone:
User-added image
5) The Browse button will bring up the dialog box to allow the selection of the proper Platform instance to use for MFA in this zone.
User-added image

6)  IMPORTANT: Once the Platform instance is specified directly in the hierarchical zone structure,  the CDC agent MUST be stopped and restarted.  This step is ONLY necessary if the Platform instance was changed.  If the Platform instance was already set and no change was made, the CDC agent will not need to be restarted.  For zoned environments that house Centrify Agent for Windows (aka DZwin), the DZWin agent does NOT need to be restarted.  The change will be realized within eight hours.  However, running dzflush, will cause DZWin to see the change immediately.

User-added image

   Zoneless Centrify Agent for Windows (DZwin)
Zoneless Centrify Agents for Windows (aka DZWin) have the MFA tenant URL specified in the host machine registry using either Group Policy or by modifying the registry directly with a tool such as regedit.exe.  No changes are need for this environment until Phase 2.
Phase 2: Explicitly configure MFA CDC agents, DZWin, and connectors to use the newer domain.
Once the tenant URL is made available, the CDC agents and connectors that were configured to use in Phase 1, must be reconfigured to permanently use

The steps to do the permanent conversion to are as follows:

Step 1) Restart the Centrify connectors.  This is required for the connectors to recognize the tenant URL change. 
 NOTE: If a web proxy is being used, ensure whitelisting is updated per KB-13446  
Step 2) Change the Platform instance defined for CDC agents and DZWin.
    Hierarchical zone requirements:
1) Use the check_cloud_url.ps1 and/or check_zone_cloudurl.tcl script to identify the hierarchical zones that need to be modified in Phase 2.  Each script can use a -P2 flag to list the zones that need to be changed from to

Reminder, check_cloud_url.ps1 is a PowerShell script that requires the Centrify PowerShell module, which can be installed on a Windows platform machine.
PS> .\check_cloud_url.ps1 -P2

User-added image

For each zone shown in the output that reads "action needed"... "please fix <zone> to the new cloudurl".  modify the Platform instance of the zone properties to the tenant url.

# ./check_zone_cloudurl.tcl -m -P2
User-added image

For each zone shown in the output that reads "action needed"..."<zone> has old cloudurl", modify the Platform instance of the zone properties to the tenant url.
To modify the zone properities, use the same steps  as described in Phase 1, but select the new domain.

2) IMPORTANT: Restart CDC agents that are joined to that zone.


3) IMPORTANT: Before the change will be realized in the zoned DZWin agents, ALL the connector overrides must be removed and the connectors restarted per Step 3 below .  After that the DZWin agent can be manually updated by running the command dzflush.
   Classic and Auto zone requirements:
1)  For classic and auto zones, the Platform instance is defined in the /etc/centrifydc/centrifydc.conf file via the parameter in the example below:
Modify this parameter to be the Platform instance using either Group Policy to push out the value to all Centrify agent machines, or by manually editing the parameter directly in centrifydc.conf.
2) IMPORTANT: Restart the CDC agent
   Zoneless Centrify Agent for Windows (DZWin)
Zoneless DZWin agents have the tenant URL specified in the host machine registry.  The registry is set either by using group policy, or by using a tool such as regedit.exe to make the registry change directly.
1) For zoneless DZWin that have MFA configured through group policy, the change is made to the GPO that has this policy:

Computer Configuration -> Policies -> Centrify Settings -> Windows Settings -> MFA Settings -> Specify the Platform instance URL to use (when the agent is not joined to a zone)
User-added image
User-added image
The DZWin does NOT need to be explicitly restarted.  The change will be realized within eight hours.  However, running dzflush will cause DZWin to see the change immediately.

2) For Zoneless DZWin with MFA configured through direct registry edits, the following modification needs to be made to the registry key:

Key: HKLM\Software\Centrify\DirectAuthorize\Agent
Value:  ZonelessTenantUrl
Data: < Tenant URL>:<port>

User-added image
The DZWin agent does NOT need to be explicitly restarted  The change will be realized within 8 hours. However, running dzflush will cause DZWin to see the change immediately.
Step 3) Remove the connector urloverride created in Phase 1.
1) Download the attached script, overrideurl.ps1, if it is not already on the machine per phase 1.
2) On each connector host machine, where the override was configured, open a PowerShell console as an Administrator and run the script:
PS> .\overrideurl.ps1 -remove
User-added image
 The change in the registry can be confirmed by running regedit.exe and checking that urlOverride key is no longer present, or by rerunning .\overrideurl.ps1 without any arguments.
  User-added image
3) IMPORTANT: Restart the connector

4) Once ALL the connectors have the override removed, the zoned DZWin agents will see the tenant URL within eight hours.  If the change must be realized immediately, the dzflush command can be run on each machine.

Click here for a video demonstration of what Centrify/Idaptive tenants will look like post split: 
 User-added image

Still have questions? Click here to log a technical support case, or collaborate with your peers in Centrify's Online Community.