Install the Windows Adapter

The adapter is responsible for delivering policies and events between the computer and EPM when computers are managed by Endpoint Privilege Management.

The adapter polls for policy updates every 5 minutes, and for pending commands every 60 minutes.

Setup information is available for the Windows adapter on the Configuration page. On the sidebar menu, click Configuration > Adapter Installation.

Prerequisites

.NET 4.6.2

Installer Parameters

Before running the installer, copy the values for the following parameters:

  • TenantID: Go to Configuration > Adapter Installation to copy the Tenant ID for the installer script.
  • InstallationID: Go to Configuration > Adapter Installation to copy the Installation ID for the installer script.
  • InstallationKey: Go to Configuration > Adapter Installation to copy the Installation Key for the installer script.
  • ServerURI: This is the URL for EPM. For example, https://<customerhost>-services.pm.beyondtrust.cloud.com, where customerhost is the DNS name for EPM.
Do not include a port number or slash character on the end of the ServerURI.

For example, neither https://test.pm.beyondtrustcloud.com/ nor https://test.pm.beyondtrustcloud.com:8080/ will work.

  • UserAccount (Optional):
    • For versions before 21.8, the default account for installing the adapter is iC3Adapter.
    • From version 21.8 and up, LocalSystem is the only account name to use.

  • GroupID: A computer must be added to a group as part of the EPM onboarding process. The group determines the policy applied to a computer. The default groupID is automatically assigned to a computer during the adapter install if one is not provided. Computers are then automatically assigned an Authorized status.

For information on how to automatically assign and authorize computer groups, see Authorize and Assign Computers to a Group.

Run the Installer

You must install the Windows adapter using the Windows command line.

To install adapters:

  1. Go to Configuration > Adapter Installation to download the Endpoint Privilege Management adapter installer.
  2. Also on the Adapter Installation page, note the Tenant ID, Server URL, Installation Key, and Installation ID. You need these required parameters for the installer script.
  3. Navigate to the location of the adapter installer. By default this is the AdapterInstallers folder.
  4. From the command line, enter the install command with the required parameters and press Enter. The adapter installer launches. Proceed through the installation wizard.
The line breaks must be removed before you run the script.
msiexec.exe /i "PrivilegeManagementConsoleAdapter_x64.msi"
TENANTID="<TenantID_GUID>"
INSTALLATIONID="<InstallationID>"
INSTALLATIONKEY="<InstallationKey>"
SERVICEURI="<EPM URL>"
USERACCOUNT=LocalSystem
GROUPID="<EPM GroupID GUID>"

Add the following argument if you don't want the adapter service to start automatically. This option is useful when Endpoint Privilege Management for Windows and the adapter are being installed on an image that will be reused to create many individual computers. If the adapter is not disabled in this scenario, the adapter will immediately join the EPM instance indicated.

If the adapter starts up and registers with EPM prior to creating the VM image, then all VMs created from this image will contain the same adapter identifier and will not work properly.

SERVICE_STARTUP_TYPE=Disabled

You can start the IC3Adapter service manually later in the Services.

msiexec.exe /i "PrivilegeManagementConsoleAdapter_x64.msi" TENANTID="6b75f647-d3y7-4391-9278-002af221cc3f" INSTALLATIONID="08A1CD8F-FAE4-479F-81B4-00751A55EEB8" INSTALLATIONKEY="ABCDEFGHIJKLMNO" SERVICEURI="https://CUSTOMERHOST-services.pm.beyondtrustcloud.com"
USERACCOUNT=LocalSystem GROUPID="e531374a-55b9-4516-g156-68f5s32f5e57"
SERVICE_STARTUP_TYPE=Disabled

CUSTOMERHOST = the hostname. For example, if the hostname were test, the desired input would be:

https://test-services.pm.beyondtrustcloud.com

Upgrade the Windows Adapter

To upgrade to a full system-level DPAPI adapter:

  1. Upgrade to the 22.1 adapter, where the adapter continues to run as the IC3 user, but at the system level.
  2. Upgrade from 22.1 to a later version of the adapter allows the adapter to run as any system-level user, like LocalSystem.

For a new adapter install, starting in version 22.1, this 2-step process is not required.

Configure the Windows EPM Adapter

The adapter uses HTTPS when communicating with EPM. If there is a proxy in place that this communication goes through, it must be configured for the adapter user account, which is separate from the logged-on user account.

The computer must be configured to use proxy settings for the machine rather than the individual user. The following registry key needs to be edited to make this change:

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Internet Settings]

The Data value must read 0. This specifies the machine (1 specifies per user).

Name Type Data
ProxySettingsPerUser REG_DWORD 0

Ensure the iC3Adapter User Has the "User Can Log on as a Service" Right

When you install the adapter, a user account called iC3Adapter is created. The iC3Adapter user is granted the right to Log on as a Service by the installation process. If you have a Group Policy in place that revokes this permission, ensure the iC3Adapter user is excluded, as it requires the Log on as a Service right.

For more information, see the Microsoft Knowledgebase article Add the Log on as a service Right to an Account.

msiexec.exe /i "PrivilegeManagementConsoleAdapter_x64.msi" TENANTID="6b75f647-d3y7-4391-9278-002af221cc3f" INSTALLATIONID="08A1CD8F-FAE4-479F-81B4-00751A55EEB8" INSTALLATIONKEY="ABCDEFGHIJKLMNO" SERVICEURI="https://CUSTOMERHOST-services.pm.beyondtrustcloud.com" GROUPID="e531374a-55b9-4516-g156-68f5s32f5e57"
SERVICE_STARTUP_TYPE=Disabled

CUSTOMERHOST = the hostname. For example, if the hostname were test, the desired input would be:

https://test-services.pm.beyondtrustcloud.com

Set Up a Proxy During Adapter Install

Starting in version 23.1, the Windows adapter installer supports setting up a proxy during installation using the following command line parameters:

PROXYADDRESS, BYPASSONLOCAL, USESYSTEMDEFAULT, and SCRIPTLOCATION

An example command using a proxy configuration parameter looks like the following:

msiexec.exe /l*v adapter_install.log /i "PrivilegeManagementConsoleAdapter_x64.msi" TENANTID="02fe4a89-ae4b-316c-d026-da8acc80b33f" INSTALLATIONID="0066f094-7f73-4c47-bfca-e7d4849d1449" INSTALLATIONKEY="angUArsM39Mk/MRD44o4Mn8dmOBGVBA6l01BBk7ljek=" SERVICEURI="https://tenantid-services.epm.btrusteng.com" GROUPID="bfac11e7-bf82-40c7-b5ee-3a0b34a304cd" usesystemdefault=”false” PROXYADDRESS=”http://<PROXY URL>:<PORT>”

The proxy settings are written to the Avecto.Ic3.Client.Host.exe.config file on the computer’s file system.

When using a non-authenticated proxy configuration, you can install an adapter by passing the command line parameters USESYSTEMDEFAULT='false' PROXYADDRESS='http://<PROXY URL>:<PORT>'

<http://system.net >
  <defaultProxy enabled="true" useDefaultCredentials="true">
    <proxy usesystemdefault="false" proxyaddress="http://<PROXY URL>:<PORT>" />
  </defaultProxy>
</system.net>
msiexec.exe /l*v adapter_install.log /i "PrivilegeManagementConsoleAdapter_x64.msi" TENANTID="02fe4a89-ae4b-316c-d026-da8acc80b33f" INSTALLATIONID="0066f094-7f73-4c47-bfca-e7d4849d1449" INSTALLATIONKEY="angUArsM39Mk/MRD44o4Mn8dmOBGVBA6l01BBk7ljek=" SERVICEURI="https://tenantid-services.epm.btrusteng.com" GROUPID="bfac11e7-bf82-40c7-b5ee-3a0b34a304cd" usesystemdefault=”true” scriptLocation=”http://pactest/adaptertest.pac”
<http://system.net >
    <defaultProxy enabled="true">
      <proxy usesystemdefault="true" scriptLocation="http://pactest/adaptertest.pac" />
    </defaultProxy>
</system.net>

Remove Proxy Configuration

To remove the proxy address configuration, pass PROXYADDRESS='' as a command line parameter during upgrade.

This removes the proxy address configuration from the Avecto.Ic3.Client.Host.exe.config file.

Install and Upgrade Considerations When Using a Proxy

Keep the following in mind when installing and upgrading the adapter using proxy settings:

  • If you install an adapter with proxy command line parameters and later upgrade to a newer version without proxy command line parameters, the older config file proxy settings are retained and persisted.
  • If you install an adapter without proxy command line parameters and later upgrade to a newer version with proxy command line parameters, the newly added proxy configuration are reflected.
  • If you install an adapter version with proxy command line parameters and later upgrade to a newer version with a different proxy configuration, the newly added proxy configuration is used.
  • If you install or upgrade an adapter with an invalid proxy address, the computer is not registered in EPM.
  • Leaving the proxy address field empty does not set the proxy address in the Avecto.Ic3.Client.Host.exe.config file.