Preparing for Installation

Complete these steps before you begin installing the Engage Agent. Preparation requires the expertise of IT and Archer administrators.

Note: Install the Engage Agent on a separate server from Archer.

Task 1: Ensure that your system meets minimum requirements

Ensure that your system meets the minimum requirements before you install the Engage Agent.

Component	Requirements
Archer	Confirm you are running a supported version of Archer. Valid Archer license that provides access to Engage.
Engage Agent	Windows Server 2012 R2 latest Windows Updates and above If you are using Engage version 4.0.1 or higher, install Microsoft .NET Core Runtime 8 of the Windows Hosting Bundle. Otherwise, install Microsoft .NET Core Runtime 6.0.xx.
Ports	Configure the firewall to enable the following ports: 5001 on the Engage Agent server - Archer to Agent communication 13200 on the Archer server - Engage Agent to Archer config URL communication 443 on the Engage Agent server - Agent to Archer base URL and Agent to the portal communication Note: Ports 5001 and 13200 do not need internet connectivity to communicate. Port 443 needs an internet connection to enable communication between the Engage Agent to portal and the Agent to Archer base URL (only if Archer base URL is external). Archer Web Servers Ports Port Inbound Outbound 443 Yes Yes 5001 No Yes 13200 Yes No Engage Agent Server Ports Port Inbound Outbound 443 Yes Yes 5001 Yes No 13200 No Yes
Archer Configuration Service Certificate	Ensure all certificates in the Trusted Root Certificate Authorities store in the Engage Agent Destination server have matching values for the Issued To and Issued By properties. Move any certificate with different values to the Intermediate Certificate Authorities store. . Ensure the Configuration Service Certificate is enabled for both Client Authentication and Server Authentication purposes.
URLs	If you are installing Engage, allow traffic from the Engage Agent to the portal by enabling the desired regional URLs. US Admin and Data API Gateway: https://api.engage.archerirm.us/data https://api.engage.archerirm.us/admin Authentication: https://cognito-idp.us-west-2.amazonaws.com/ https://cognito-idp.us-east-1.amazonaws.com/ For Publish and Retrieve Operation: https://threepp-longbow-upload-us-west-*.s3.us-west-2.amazonaws.com/ https://threepp-packaged-assessments-us-west-2-*.s3.us-west-2.amazonaws.com/ https://threepp-longbow-upload-us-east-*.s3.us-east-1.amazonaws.com/ https://threepp-packaged-assessments-ue1-*.s3.us-east-1.amazonaws.com/ APJ Admin and Data API Gateway: https://api.engage.archerirm.com.au/data https://api.engage.archerirm.com.au/admin Authentication: https://cognito-idp.ap-southeast-2.amazonaws.com/ For Publish and Retrieve Operation: https://threepp-longbow-upload-ap-southeast-2-*.s3.ap-southeast-2.amazonaws.com/ https://threepp-packaged-assessments-as2-*.s3.ap-southeast-2.amazonaws.com/ EMEA Admin and Data API Gateway: https://api.engage.archerirm.eu/data https://api.engage.archerirm.eu/admin Authentication: https://cognito-idp.eu-west-1.amazonaws.com/ https://cognito-idp.eu-central-1.amazonaws.com/ For Publish and Retrieve Operation: https://threepp-longbow-upload-eu-west-1-*.s3.eu-west-1.amazonaws.com/ https://threepp-longbow-upload-eu-central-1-*.s3.eu-central-1.amazonaws.com/ https://threepp-packaged-assessments-ew1-*.s3.eu-west-1.amazonaws.com/ https://threepp-packaged-assessments-ec1-*.s3.eu-central-1.amazonaws.com/ CA Admin and Data API Gateway: https://api.engage.archerirm.net/data https://api.engage.archerirm.net/admin Authentication: https://cognito-idp.ca-central-1.amazonaws.com/ For Publish and Retrieve Operation: https://threepp-longbow-upload-ca-central-1-*.s3.ca-central-1.amazonaws.com/ https://threepp-packaged-assessments-cc1-*.s3.ca-central-1.amazonaws.com/ UAE Admin and Data API Gateway https://api.engage.archerirm.ae/data https://api.engage.archerirm.ae/admin Authentication: https://cognito-idp.me-south-1.amazonaws.com/ For Publish and Retrieve Operation: https://threepp-longbow-upload-me-central-1-*.s3.me-central-1.amazonaws.com/ https://threepp-packaged-assessments-mc1-*.s3.me-central-1.amazonaws.com/

Task 2: Obtain the Archer Configuration Service REST URL

Obtain the Archer Configuration Service REST URL for later use in the installation process.

1. Go to the machine that is running the Archer Configuration Service.

2. In Windows, open File Explorer.

3. Go to the Archer installation folder and open: Services\ArcherTech.Services.ConfigurationService.exe.config. The default file path is C:\Program Files\Archer\Services\ArcherTech.Services.ConfigurationService.exe.config.

4. Locate the following service: ArcherTech.Configuration.RestService.

5. Within the ArcherTech.Configuration.RestService, locate the baseAddress URL.

   Important: If you are running the Engage Agent on the same machine as the Archer Configuration Service, the string is https://localhost:13200/ConfigService/rest. Otherwise, the URL is https://{servername where config service is running}:13200/ConfigurationService/rest.

6. Save the URL for use when entering the Configuration Service REST URL in the Engage Agent Setup Wizard.

Task 3: Obtain the Configuration Certificate

You must obtain the certificate that you created when installing Archer. By default, it is the Archer Configuration Certificate. However, you may have created your own X.509 certificate with a different name during installation.

1. Go to the machine that is running the Archer Services Server.

2. Open Microsoft Management Console.

3. Click File > Add/Remove Snap-in.

4. In the Add or Remove Snap-ins window, do the following:

   1. In the left pane, select Certificates.

   2. Click Add.

   3. Select Computer account.

   4. Click Next.

   5. Select Local computer.

   6. Click Finish.

   7. Click OK.

      The system provides a list of available certificates to choose from in the left panel.

5. In the list of certificates on the left panel, click Certificates (Local Computer) > Personal > Certificates > [Name of your certificate].

6. Right-click [Name of your certificate], then click All Tasks > Export.

7. In the Certificate Export Wizard, click Next and do the following:

   1. On the Export Private Key page, select whether you want to export the private key with the certificate, then click Next.

      Note: It is recommended to export a private key with the certificate.

   2. Click Next.

   3. On the Export File Format page, select the format Personal Information Exchange - PKCS #12 (PFX).

   4. Under the Personal Information Exchange - PKCS #12 (PFX) format, select checkboxes to:

      1. Include all certificates in the certification path if possible

      2. Export all extended properties.

   5. Click Next.

   6. If you chose to export a private key with the certificate, on the Security Page, select the checkbox for Password, then enter and confirm a password.

   7. Click Next.

   8. On the File to Export page, select the location where you want to save the certificate and then enter a File Name.

   9. Click Save.

   10. Click Next.

   11. Click Finish.

   12. When prompted, click OK to acknowledge that the import was successful.

8. Go to the location where you saved the certificate, then right-click and copy the certificate.

9. Open the server on which you want to install the Engage Agent.

10. Go to the location where you want to save the certificate, then right-click and paste the certificate.

11. (Optional) Install the certificate on the personal store. For more information, see Task 1, Step 9b in Installing the Engage Agent.

Task 4: Export the SSL Certificate

You must export the SSL certificate to use in the Engage Agent Setup Wizard.

Note: These instructions assume you have a binding for HTTPS already installed.

1. Open Internet Information Services (IIS) Manager.

2. In the Connections panel, click Default Web Site.

3. In the Actions panel, click Bindings.

4. Click OK.

   Note: You may have to restart IIS or the server for it to recognize the new certificate.

Task 5: Import Certificates into the Certificate store

You can import certificates to the certificate store prior to using them during the installation.

1. Go to Manage computer certificates.

   The system lists all the available stores in the left panel.

   Important: Ensure all certificates in the Trusted Root Certificate Authorities store on the Engage Agent destination server have different values for Issued To and Issued by properties. Move any certificates with matching values to the Intermediate Certificate Authorities store. If these certificates are outside of the Intermediate Certificate Authorities store, Engage Agent fails.
   

2. Right-click on a store, and click All Tasks > Import.

3. In the Certificate Import Wizard, click Next and do the following:

   1. On the File to import page, click Browse to navigate to the certificates folder.

   2. Select the appropriate certificate.

   3. Click Next.

   4. On the Private key protection page, select the checkboxes to make the key exportable and to include all extended properties.

   5. If the certificate is password enabled, enter the password.

   6. Click Next.

   7. On the Certificate Store page, confirm the location of the Certificate store.

   8. Click Next.

   9. Click Finish.

   10. When prompted, click OK to acknowledge that the import was successful.

   11. Right-click on certificate, select Properties, verify the Client Authentication and "Server Authentication" purposes are selected for this certificate.

Task 6: Check your Certificates

When it comes time to install Archer Engage, 3 certificates are required. If you have followed all the instructions above properly, you should have 3 certificates available.

Certificate	Owned by	Server installed on	Notes
Archer SSL Certificate	Archer	Engage Agent Server	Must be on the Engage Agent Server trusted list.
Archer Configuration Certificate	Archer	Engage Agent Server	Must be on the Engage Agent Server trusted list. To be selected during the Engage Agent installation.
Engage Agent SSL Certificate	Engage Agent	Archer Server	Must be on the Engage Agent Server and Archer server trusted list. To be selected during the Engage Agent installation.

Task 7: Download the Engage Agent installer package

Download the Engage Agent install package from myArcher.

Task 8: Install IIS Extensions

Important: Configure your Microsoft Internet Information Services (IIS) settings to allow IIS to proxy requests to the Engage Agent. Verify Archer supports your IIS version by comparing it to the Qualified and Supported Environments listed on the Archer Community.

Before you configure your IIS settings, you must download and install IIS extensions on the same machine that is running the Archer Web Server.

1. Go to Microsoft Supported Downloads for IIS (https://www.iis.net/downloads/microsoft).

2. Download and install the following IIS extensions in order:

   1. URL Rewrite (https://www.iis.net/downloads/microsoft/url-rewrite)

   2. Application Request Routing (https://www.iis.net/downloads/microsoft/application-request-routing)

Task 9: Configure Server Farm

Configure the URL Rewrite module by creating new inbound rules at the server level in a Server Farm.

Important: If you have more than one Web Server, you must configure Server Farm on all Web Servers.

1. Open Internet Information Services (IIS) Manager.

2. In the Connections panel, select Server Farms.

3. In the Actions column, click Create Server Farm.

4. In the Create Server Farm window, enter a server farm name, and click Next.

   Note: Remember this name for later.

5. Enter the Server address where the Engage Agent is installed.

6. Click Advanced Settings.

7. Expand application RequestRouting. Do the following:

   1. In the hostName field, enter the hostname of your Engage Agent.

   2. In the httpsPort field, enter 5001.

   3. Click Add.

   4. Click Finish.

8. When prompted by the Rewrite Rules window, click Yes.

9. From the Connections panel, under Server Farms, click the server farm name created in step 4.

10. Double-click Proxy.

11. In the Proxy settings, do the following:

    1. In the Time-out (seconds) field, enter 300.

    2. In response headers, select Reverse rewrite host.

    3. Click Apply, and close the proxy settings window.

12. From your ServerFarm window, click Routing Rules, and do the following:

    1. Select Use URL Rewrite to inspect incoming requests.

    2. Select Enable SSL offloading.

13. Click URL Rewrite.

14. Double click the ARR_<name of the server farm>_loadbalance rule.

15. When installing Archer Engage and Engage for Vendors, in the Edit Inbound Rule window, do the following:

    1. In the Match URL section, do the following:

       • From the Requested URL drop-down list, select Matches the Pattern.

       • From the Using drop-down list, select Regular Expressions.

       • In the Pattern field, enter engage/api/(([^/]*)/{0,1}.*) .

       • Select the Ignore case checkbox.

    2. In the Conditions section, do the following:

       1. From the Logical grouping drop-down list, select Match All.

       2. Click Add and complete the Add Condition section as follows:

          • In the Condition field, enter {R:2}.

          • From the Check if the input string drop-down list, Select Does Not Match the Pattern.

          • Enter (^v[0-9]{1,}$) in the Pattern field.

          • Select Ignore case.

          • Clear the Track capture groups across conditions checkbox.

    3. In the Action section, do the following: 

       • In the Action Type menu, select Route to Server Farm.

       • In the Scheme menu, select https://.

       • In the Server farm menu, select the Server Farm named in Step 4.

       • In the Path field, enter /api/v1/{ToLower:{R:1}}.

       • Unselect the Stop processing of subsequent rules checkbox.

    4. Click Apply.

    5. Click Back to Rules.

16. Select Blank rule from the Inbound rules templates.

17. In the Edit Inbound Rule window, do the following:

    1. In the Name field, enter ARR_(name of the server farm)_With_IncomingAPIVersion.

    2. In the Match URL section, do the following:

       • From the Requested URL drop-down list, select Matches the Pattern.

       • From the Using drop-down list, select Regular Expressions.

       • Enter engage/api/(([^/]*)/{0,1}.*) in the Pattern field.

       • Select the Ignore case checkbox.

    3. In the Conditions section, do the following:

       • From the Logical grouping drop-down list, select Match All.

       • Click the Add and complete the Add Condition section.

         • Enter {R:2} in the Condition input field.

         • From the Check if the input string list, select Matches the Pattern.

         • Enter (^v[0-9]{1,}$) in the Pattern field.

         • Select the Ignore case checkbox.

         • Clear the Track capture groups across conditions checkbox.

    4. No configuration is needed in the Server Variables section.

    5. In the Action section, do the following:

       • In the Action Type menu, select Route to Server Farm.

       • In the Scheme menu, select https://.

       • In the Server farm menu, select the Server Farm named in Step 4.

       • In the Path field, enter /api/{ToLower:{R:1}}.

       • Clear the Stop processing of subsequent rules checkbox.

    6. Click Apply.

Task 10: Check if the Configuration service URL is reachable

1. Log in to the Engage Agent machine.

2. (Optional) Install the Configuration service certificate in the Current User Account.

   Note: Step 2 is not mandatory for the Engage Agent installation. This step is used to troubleshoot Archer configuration service URL This step can be rolled back once the Archer configuration service is reachable from the Engage Agent machine.

3. Open a web browser and open the following configuration URL:

   https://{IpAddress or Host name}:13200/ConfigService/rest/

   Where {IpAddress or Host name} is the fully qualified hostname of web server.

4. Select the Archer configuration service certificate.

If the Archer configuration service URL is reachable from an Engage Agent machine, the following message is displayed:

End point not found.

If the Archer configuration service URL is not reachable, see Troubleshooting Engage for On-Premises.