Installing and Using the Cloud Client for Windows

This section includes topics about installing the client and enrolling your system.

Preparing for the Cloud Client for Windows Installation

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

Login considerations

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

To Remote Desktop Protocol (RDP) into the Privileged Access Service system, do one of the following:
- use the Delinea PAS 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 Delinea PAS.
When the machine with the Cloud 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 Cloud Client for Windows, local users must use a ".\" prefix (for example: ".\Administrator") to log in.
If installed on a machine with either: a Cloud Client, a Domain Controller, or a Windows agent installed and configured for MFA -- the Cloud 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:

Add a Users group to the group policy setting "Allow log on locally" or
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 for AWS and Azure

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 Cloud Client for Windows in Amazon Web Services (AWS)
Retrieve and Install the Cloud Client for Windows in Microsoft Azure

Retrieve and Install the Cloud Client for Windows in Amazon Web Services (AWS)

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

Place the package in an online location (in your S3 Bucket), reachable by your AWS instance.
Set the variable bucketName to the name of your bucket.
Replace regCode with your registration code.
Replace cloudURL with your Privileged Access Service URL.
Optional: set the addressType to your desired: PrivateIP, PublicIP, PrivateDNS or PublicDNS.

Optional: set the nameType to your desired: Name Tag, Local Hostname, Public Hostname or InstanceID.

Copy

# 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 Cloud Client for Windows in Microsoft Azure

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

Place the package in an online location.
Replace the name of the installation package in packageFilename.
Replace regCode with your registration code.
Replace cloudURL with your Privileged Access Service URL.
If using Azure storage accounts, provide the Account Name and Key.

Optional: select the type of IP/FQDN you would like to use. Defaults to PrivateIP.

Copy

# 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"
# 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."

Downloading and Installing the Cloud Client for Windows

To download the Cloud Client for Windows:

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

When installing the Cloud 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 Cloud Client for Windows Interactively

To install the client interactively:

Open the downloaded client installer file to start the setup program interactively to a welcome page and click Next.
At the enrollment parameters screen, enter the enrollment parameters.

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 Cloud 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 - aany 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 cenroll.

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

Copy

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

The Cloud 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 Cloud Client for Windows. For more information about migrating scripts from the CLI Toolkit to use the commands included in the Cloud Client for Windows package, see Migrating Scripts from the CLI Toolkit.

Troubleshooting the Cloud 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 Cloud 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.

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 Cloud Client for Windows on the system in order to use Local Group Mapping.

To add a group Local Group Mapping:

Navigate to Resources > Systems. Choose a system and click Local Group Mapping from the left-hand navigation.
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.

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.

Using Alternative Accounts with Cloud Client for Windows

For systems that are joined to Active Directory and where you have installed the Cloud Client for Windows, you can run an application using Active Directory alternate accounts without having to checkout the password in Delinea PAS.

You'll need to have first discovered the alternate accounts for your users. For details, see Discovering alternative accounts.

The alternate account should not have any MFA settings. If the alternate account does have MFA options assigned, the operation to run the application with that account will fail.

Also, if you're looking for information about enabling alternate account support on systems that have the Server Suite Agent for Windows installed, see Enabling users to run applications with alternate accounts.

To run an application with an alternate account:

On a Windows system, right-click the desired application and choose Run as Administrator.
In the dialog box that opens, select the Use My Alternate Account option and click Yes to continue.
When prompted, enter your Active Directory credentials to authenticate your account and click Yes to continue.

How the authentication profile is configured for your account determines what kind of authentication credentials you need to enter.
If you have more than one alternate account, select the desired account to use and click Yes to continue.

If your alternate account has administrative privileges, the application runs under this alternate account (with elevated administrative privileges).

Logging in to Windows with Use My Account

You can log in to an enrolled Windows system with the same account that you use when you log in to the Admin Portal, and you can do this either from the Admin Portal or by using a native application that uses RDP, SSH, SCP, or SFTP.

You can log in to an enrolled Windows system without having to first log in to the Admin Portal by using a vaulted account, manual login, or Use My Account (UMA). For details on logging in with a vaulted or manual account, see Accessing remote systems.

Prerequisites for Logging in to Windows Systems with Use My Account

Before you can use this feature, you need the following:

Enroll the system. For details, see Downloading and Installing the Cloud Client for Windows.
Your account needs to have the Agent Auth permission. For details, see Enabling Client-Based Login.
The target system needs to be using the connector that you log in to. For details, see Mapping system subnets to connectors.

Be aware that when an Active Directory users logs in with Use My Account, the system prompts them to enter their password so that the user can log in as a domain user on the system.

Accounts and hostnames needed for logging in to Windows systems with Use My Account

Here are the accounts and hostnames that you'll need for this procedure:

Connector hostname
Connector port, if you're logging in to the connector in order to connect to another system (jumpbox scenario) By default, the port for RDP connections is 5555 and 22 for SSH connections.

You can configure the port per connector in Settings > Network > Centrify Connectors > connector > SSH-RDP Services > RDP Port. You can also configure the SSH port.
The target system's hostname (this is the system that you want to log in to). Be sure to use the fully qualified domain name (FQDN).
Your user name in the Admin Portal, including tenant suffix. For example, joe.user@acme.com.
The "me" account. This is a local account that the service creates automatically but it's normally hidden from view.

If you have already configured a local Windows account named "me" you can contact Delinea Technical Support to configure this feature to use a different name for this special, local account.

Whether you connect to a Windows system directly using Remote Desktop Connection, PuTTY, or an FTP client, the process is the same. You connect to the desired system by way of the connector system.

To log in to an enrolled Windows system directly with Remote Desktop Connection:

In a new Remote Desktop Connection window, enter the computer hostname and (optionally) the port for the system where the cloud connector is installed.

For example, if the hostname is win-prod7.acme.com, enter that as the hostname.

If you're connecting to the system as a way to log in to a networked system (jumpbox scenario), enter the port number. For example, enter win-prod7.acme.com:5555.
Enter the user name that you use to log in to the Admin Portal.

Click Connect to continue.
When prompted, enter the password for your Admin Portal account.
When prompted, enter any additional multi-factor authentication answers.
When prompted for the hostname, enter the hostname for the target system.
When prompted for the account, enter "me".

The "me" account tells the service to use your Admin Portal account.

After the service validates your authentication, it logs you in to the Windows system under your Admin Portal user name.