Installing and using the Centrify Client for Windows

The following describes how to install and enroll the Centrify Client for Windows by detailing the following:

Preparing for the Centrify Client for Windows Installation

The following are considerations and best practices to review and/or perform before you install the Centrify Client for Windows:

Login considerations

The following are login considerations when installing and using the Centrify Client for Windows.

  • To Remote Desktop Protocol (RDP) into the Privileged Access Service system, do one of the following:

    • use the Centrify portal web RDP, or

    • use the Microsoft workaround available here.

  • Network Level Authentication (NLA) has to be turned off to use Use My Account or log in with Centrify Cloud Service.

  • When the machine with the Centrify Client for Windows installed on it is joined to a different domain, always input the login suffix for the user login.
  • Upon installation and enrollment of the Centrify Client for Windows, local users must use a ".\" prefix (for example: ".\Administrator") to log in.

  • If installed on a machine with either: a Cloud Agent, a Domain Controller, or a Windows agent installed and configured for MFA -- the Centrify Client for Windows will enroll without failure but will not be enabled. If the client is not enabled, the error is saved in the cenroll log.
  • If authenticate profile is disabled or set to "Always allowed", you will be asked for a password upon logon.

  • When logging in as an active directory (AD) user, you must log in with the AD user password. If you input the password during MFA, it is used for the AD password because you still log in as the AD user, not a mapped local user.
  • If you are unable to log in, it may be because the group policy setting doesn't allow members of the Users group to log in locally. Check your group policy setting by navigating to Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment, and review the policies "Allow log on locally" and "Allow log on through Remote Desktop Services."

Here, you can do one of the following:

  1. Add a Users group to the group policy setting "Allow log on locally" or
  2. Create a local group for cloud users and add this group to "Allow log on locally." Additionally, in the web admin portal set up the local group mapping to map all cloud users to this local group.

Using sample scripts

The following sample scripts illustrate some common use-cases for the commands in the client package. For example, there are sample scripts that illustrate how to use the commands in the client package to perform the following tasks:

  • Retrieve and install the Centrify Client for Windows preview in Amazon Web Services (AWS)
  • Retrieve and install the Centrify Client for Windows preview in Microsoft Azure
  • Retrieve and install the Centrify Cloud Agent preview

Retrieve and install the Centrify Client for Windows preview in Amazon Web Services (AWS)

To retrieve and install the Centrify Client for Windows in AWS, perform the following steps:

  1. Place the Centrify package in an online location (in your S3 Bucket), reachable by your AWS instance.
  2. Set the variable bucketName to the name of your bucket.
  3. Replace regCode with your registration code.
  4. Replace cloudURL with your Privileged Access Service URL.
  5. Optional: set the addressType to your desired: PrivateIP, PublicIP, PrivateDNS or PublicDNS.
  6. Optional: set the nameType to your desired: Name Tag, Local Hostname, Public Hostname or InstanceID.
# AWS Bucket Name.
$bucketName = "bucket-name"
# Name of package file.
$packageFilename = "package-name.msi"
# Registration code to use.
$regCode = "SOME-REGISTRATION-CODE"
# Tenant URL against which to enroll.
$cloudURL = "https://TENANT.my.centrify.net"
# Optional - select the FQDN Type (PrivateIP, PublicIP, PrivateDNS, PublicDNS). Defaults to PublicDNS.
$addressType = ''
# Optional - select the Name Type (NameTag, LocalHostname, PublicHostname, InstanceID). Defaults to LocalHostname.
$nameType = ''
 
$system_name = Get-EC2InstanceMetadata -Category LocalHostname
$instid = Get-EC2InstanceMetadata -Category InstanceId
$tagname = ((Get-EC2Instance -InstanceId $instid) | Select -ExpandProperty RunningInstance).tag
 
Write-Output "Retrieving package..."
New-Item -ItemType Directory -Path C:\Centrify
$file = (Read-S3Object -BucketName $bucketName -Key $packageFilename -File C:\Centrify\$packageFilename)
 
# Retrieves the Name to be registered in PAS.
switch ($nameType.ToLower())
{
"nametag"         {$system_name = $tagname.Item(0).Value}
"localhostname"   {$system_name = Get-EC2InstanceMetadata -Category LocalHostname }
"publichostname"  {$system_name = Get-EC2InstanceMetadata -Category PublicHostname }
"instanceid"      {$system_name = $instid }
default {$system_name = Get-EC2InstanceMetadata -Category LocalHostname}
}
 
# Retrieves the FQDN to be registered in PAS.
switch ($addressType.ToLower())
{
"publicip"   {$ipaddr = Get-EC2InstanceMetadata -Category PublicIPv4 }
"privateip"  {$ipaddr = Get-EC2InstanceMetadata -Category LocalIPv4 }
"publicdns"  {$ipaddr = Get-EC2InstanceMetadata -Category PublicHostname }
"privatedns" {$ipaddr = Get-EC2InstanceMetadata -Category LocalHostname }
default {$ipaddr = Get-EC2InstanceMetadata -Category LocalIpv4 }
}
 
Write-Output "The system will be enrolled as $system_name with IP/FQDN $ipaddr."
Write-Output "Installing and Enrolling..."
 
$DataStamp = get-date -Format yyyyMMddTHHmmss
$logFile = '{0}-{1}.log' -f $file.fullname,$DataStamp
$MSIArguments = @(
"/i"
('"{0}"' -f $file.fullname)
"/qn"
"/norestart"
"/L*v"
$logFile
 
" TENANTURL=$cloudURL"
" ENROLLCODE=$regCode"
" PARAM=""--address=$ipaddr --name=$system_name"""
)
Start-Process "msiexec.exe" -ArgumentList $MSIArguments   -Wait -NoNewWindow

Retrieve and install the Centrify Client for Windows preview in Microsoft Azure

To retrieve and install the Centrify Client for Windows preview in Microsoft Azure, perform the following steps:

  1. Place the Centrify package in an online location.
  2. Replace the name of the installation package in packageFilename.
  3. Replace regCode with your registration code.
  4. Replace cloudURL with your Privileged Access Service URL.
  5. If using Azure storage accounts, provide the Account Name and Key.
  6. Optional: select the type of IP/FQDN you would like to use. Defaults to PrivateIP.
# Name of package file
$packageFilename = "PACKAGE-NAME.msi"
# Registration code to use
$regCode = "SOME-REGISTRATION-CODE"
# Tenant URL against which to enroll
$cloudURL = "https://TENANT.centrify.com"
# Parameters to retrieve from a storage account (storage account name + secret)
$storageAcct = 'YOUR-STORAGEACCOUNTNAME'
$storageKey = 'Long long string that shall not be embedded in scripts'
# Gathers some Azure Instance data
$meta = Invoke-RestMethod -Headers @{"Metadata"="true"} -URI http://123.456.789.254/metadata/instance?api-version=2017-08-01 -Method get
$privateIP =  $meta.network.interface.ipv4.ipAddress.privateIPaddress
$publicIP =  $meta.network.interface.ipv4.ipAddress.publicIPaddress
$system_name = $meta.compute.name
# Optional - select the FQDN Type (PrivateIP, PublicIP). Defaults to PrivateIP.
$addressType = ''
Write-Output "Retrieving package..."
New-Item -ItemType Directory -Path C:\Centrify
$StorageContext = New-AzureStorageContext -StorageAccountName $storageAcct -StorageAccountKey $storageKey
Get-AzureStorageFileContent -ShareName "share" -Path "cagent.msi" -Context $StorageContext -Destination "C:\Centrify\$packageFilename"
$file = Get-ChildItem -Path "C:\Centrify\$packageFilename"
# Retrieves the FQDN to be registered in PAS.
switch ($addressType.ToLower())
{
"publicip"   {$ipaddr = $publicIP }
"privateip"  {$ipaddr = $privateIP }
default {$ipaddr = $privateIP }
}
Write-Output "The system will be enrolled as $system_name with IP/FQDN $ipaddr."
Write-Output "Installing and Enrolling..."
$DataStamp = get-date -Format yyyyMMddTHHmmss
$logFile = '{0}-{1}.log' -f $file.fullname,$DataStamp
$MSIArguments = @(
"/i"
('"{0}"' -f $file.fullname)
"/qn"
"/norestart"
"/L*v"
$logFile
" TENANTURL=$cloudURL"
" ENROLLCODE=$regCode"
" PARAM=""--address=$ipaddr --name=$system_name"""
)
Start-Process "msiexec.exe" -ArgumentList $MSIArguments -Wait -NoNewWindow
Write-Output "Enrollment Complete."

Retrieve and install the Centrify Client for Windows preview in Microsoft Azure

To retrieve and install the Centrify Client for Windows preview:

  1. Place the Centrify package in an online location.
  2. Replace the name of the installation package in packageFilename.
  3. Replace regCode with your registration code.
  4. Replace cloudURL with your Privileged Access Service URL.
  5. Replace the packageURL with your web location for the MSI package.

Note:   You can change the $packageFilename.

# Name of package file
$packageFilename = "cagent.msi"
# Registration code to use
$regCode = "A1BC2345-D6E7-89F0-G123-HIJK4LM5N67P"
# Tenant URL against which to enroll
$cloudURL = "https://safe.centrify.vms"
# Package download location
$packageURL = "https://member.centrify.vms/webfiles/" + $packageFilename
Write-Output "Retrieving package..."
New-Item -ItemType Directory -Path C:\Centrify
Invoke-WebRequest -Uri $packageURL -Outfile "C:\Centrify\$packageFilename"
$file = Get-ChildItem -Path "C:\Centrify\$packageFilename"
# Retrieves the IPv4 for the preferred network interface.
$ipaddr = (Get-NetIPAddress | ?{ $_.AddressFamily -eq “IPv4” -and !($_.IPAddress -match “169”) -and `
!($_.IPaddress -match “127”) }).IPAddress
# Retrieves the FQDN of the system
$fqdn = [System.Net.Dns]::GetHostByName(($env:COMPUTERNAME)).Hostname
Write-Output "System Address is $ipaddr, the FQDN is $fqdn."
Write-Output "Installing and Enrolling..."
$DataStamp = get-date -Format yyyyMMddTHHmmss
$logFile = '{0}-{1}.log' -f $file.fullname,$DataStamp
	$MSIArguments = @(
	"/i"
	('"{0}"' -f $file.fullname)
	"/qn"
	"/norestart"
	"/L*v"
	$logFile
 
	" TENANTURL=$cloudURL"
	" ENROLLCODE=$regCode"
	" PARAM=""--address=$ipaddr"""
)
Start-Process "msiexec.exe" -ArgumentList $MSIArguments   -Wait -NoNewWindow
Write-Output "Enrollment Complete."

Downloading and installing the Centrify Client for Windows

To download the Centrify Client for Windows:

  1. Log-in to Admin Portal.
  2. Click Downloads, select Centrify Client for Windows and click Download.

Note:   When installing the Centrify Client for Windows, irrespective of interactive or silent installation, if you specify parameters, the client is installed and enrolled. If you do not specify parameters, the client is installed successfully but not enrolled.

Installing and enrolling the Centrify Client for Windows interactively

To install the client interactively:

  1. Open the downloaded client installer file to start the setup program interactively to a welcome page and click Next.

  1. At the enrollment parameters screen, enter the enrollment parameters.

Note:   If you do not enter enrollment parameters here, the client is installed but not working. The system is not enrolled as no parameters were specified to perform the enrollment . If you don't enter parameters, you will see the following screen and have to run cenroll manually after the installation:

A successful installation screen appears if you have succeeded in one of the following scenarios:

  • You entered the correct enrollment parameters and both the installation and enrollment are completed and the client is up and running.
  • You did not enter enrollment parameters and installation is complete. The system is not enrolled and you must conclude the enrollment manually after the installation with the command cenroll.

If the installation was successful but the system failed to enroll due to an error (for example, a typo in the enrollment code would prevent the enrollment from completing) you will see the below screen and must manually run cenroll to enroll the system.

Installing and enrolling the Centrify Client for Windows silently

To install the program silently use msiexec.exe utility. Refer to msiexec.exe help for complete set of supported options. Enrollment parameters can be passed to the installer via command line using following parameters:

  • TENANTURL - the URL of the tenant portal for your organization.
  • ENROLLCODE - the code that is generated by the administrator of the tenant’s web portal.
  • PARAM - <any additional parameters that you want to pass to cenroll.exe. any additional parameters that you want to pass to cenroll.exe. For additional options for cenroll, see Using Centrify Client commands.

The following is an example of a silent installation command line you can use:

msiexec.exe /q /i cagentinstaller.msi TENANTURL=<url of the tenant> ENROLLCODE=<enrollment code generated by the tenant>

The Centrify Client for Windows replaces the CLI Toolkit, which was available in previous releases. If you downloaded and installed the CLI Toolkit and have scripts that used the commands included in previous releases, you might need to modify the scripts to work with the Centrify Client for Windows. For more information about migrating scripts from the CLI Toolkit to use the commands included in the Centrify Client for Windows package, see Migrating scripts from the CLI Toolkit.

Troubleshooting the Centrify Client for Windows Installation

This section covers common questions to help you identify and correct problems with the client installation.

  • If the service process of Centrify Client for Windows stops running for any reason, the system enters a Rescue Mode. In Rescue Mode, only local administrators can log on to the system.

Understanding Local Group Mapping

With Local Group Mapping, you can map a cloud role to a local group on a Windows system. For example, you create a group in Privileged Access Service and call it "local admins" and map it the local group Administrators. Members of the cloud role “local admins” will be added to the local Windows group Administrators when they are logged into the system.

When the user logs out of the system, the service removes the user account from the local group mapping.

Note:   If the user has both AgentAuth and Offline Rescue permissions, the local group mapping stays intact after the user logs out. Users with these permissions need to retain local group access between sessions for cases when an offline system needs an administrator to bring it back onlin.

You must have installed the Centrify Client for Windows on the system in order to use Local Group Mapping.

To add a group Local Group Mapping:

  1. Navigate to ResourcesSystems. Choose a system and click Local Group Mapping from the left-hand navigation.

  1. Select the role you would like to add by clicking Select and choose the roles you would like to add:

then add the local groups and click OK and you will see the group mapping added.

Note:   There is no verification on local group naming. If there is a typo in the group naming, the system will look for the group on the local system but may not match due to misspelling and the user will not be added. Additionally, if there is a space in the group name both words must be encased in double quote marks " ".

To verify the group membership, open the Computer Management utility and navigate to Local Users and Groups, and either:

  • Select Groups, double-click on the group you’re adding user to (Administrators in our example), or

  • Select Users, double-click on the user and then switch to the Member Of tab.