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  >
article

KB-17161: Preparing for the Tenant URL Change to centrify.net

Privileged Access Service ,  

15 October,19 at 01:12 PM

Problem:

  
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 centrify.com to centrify.net.   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 centrify.net. This will cause the Centrify DirectControl (CDC) agents that are configured for MFA and are dependent upon the centrify.com 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:
i.e.
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:
 

 

Resolution:

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 from Centrify arrives indicating that the tenant migration is completed.

  
Phase 1:  Explicitly define the MFA tenant URL to be the centrify.com 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 centrify.com 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 centrify.com 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
  
i.e.
adclient.legacyzone.mfa.cloudurl: https://aah0148.my.centrify.com:443/
 
Since the URL is already set to use the centrify.com 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 centrify.com 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 https://aah0148.my.centrify.com

  
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 centrify.com 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 centrify.com 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 dzrefresh, 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 centrify.net domain.
 
 
Once the tenant migration is complete and the tenant URL is changed to the newer centrify.net, the CDC agents and connectors that were configured to use centrify.com in Phase 1, must be reconfigured to permanently use centrify.net.

The steps to do the permanent conversion to centrify.net are as follows:
  

 
Step 1) 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 centrify.com to centrify.net
 
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 centrify.net 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 centrify.net tenant url.
  
To modify the zone properities, use the same steps  as described in Phase 1, but select the new
centrify.net domain.

  
2) IMPORTANT: Restart CDC agents that are joined to that zone. Refresh DZWin agents that are joined to the zone with dzrefresh.
  
  
  
   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:
  
adclient.legacyzone.mfa.cloudurl:  https://aah0148.my.centrify.com:8080/
  
Modify this parameter to be the centrify.net 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.
 
i.e.
adclient.legacyzone.mfa.cloudurl: https://aah0148.my.centrify.net:8080/
  
 
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 dzrefresh 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: <new-centrify.net 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 dzrefresh will cause DZWin to see the change immediately.
  
  
 
Step 2) 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
  
  
 
Attachments:

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