OnGuard Settings and OnGuard Custom Web Pages

This section provides the following information:

Introduction
About the OnGuard Custom Interface and the Remediation Process
Configuring OnGuard Settings
Creating OnGuard Custom Web Pages
Installing Standalone VIA 3.2.x with OnGuard Agent

Introduction

Use the OnGuard Settings page to configure the agent deployment packages.

When you save the OnGuard configuration, ClearPass creates agent deployment packages for the Windows and Macintosh OS X operating systems and provides the packages at a fixed URL on the ClearPass Policy Manager hardware or virtual appliance.

You can then publish this URL to the user community or download the agent deployment packages to another location.

To view the OnGuard Support Charts, see Accessing the OnGuard Support Charts.

About the OnGuard Custom Interface and the Remediation Process

OnGuard provides the ability to show end users a custom interface, or wizard, that guides them through the remediation process if their device is quarantined.

When this feature is enabled and OnGuard needs to run a custom remediation script, the wizard tells the user why the device was denied network access, describes the tasks that are required to fix the problem, and lets the user choose whether to execute the remedial script or not. While the script is being executed and new health checks are run, progress messages are displayed.

The pages of the wizard are created using ClearPass Guest’s Web Pages configuration forms, and can be customized with logo, text, and images (for details, refer to the Custom User Interface parameter in Table 1 and Creating OnGuard Custom Web Pages).

Enabling the Custom User Interface

To enable configuration of the custom user interface and use the options in the Agent Remediation User Interface Customization area, see the next section, Configuring OnGuard Settings.

Creating Custom Web Pages

To create and design the custom web pages the end user sees, use the options provided in the Agent Remediation User Interface Customization area, see Creating OnGuard Custom Web Pages.

Configuring the Show Custom User Interface for Custom Scripts Attribute

To configure the Show Custom UI for Custom Scripts attribute:

1. Navigate to Configuration > Enforcement > Profiles, then select the Agent Script Enforcement profile.
2. Specify the Success Message, Failure Message, Progress Message, and Description attributes, as well as other script-related attributes (for details, see Configuring Agent Script Enforcement Attributes).

Configuring OnGuard Settings

To configure the OnGuard settings:

1. Navigate to Administration > Agents and Software Updates > OnGuard Settings.

The OnGuard Settings page opens:

Figure 1: OnGuard Settings Page

2. Configure the OnGuard Settings parameters as described in Table 1, then click Save.
Table 1: OnGuard Settings Parameters

Parameter

Action/Description

Global Agent Settings

Configure the global agent settings parameters for OnGuard agents.

For more information, see OnGuard Global Agent Settings.

Policy Manager Zones

Configure the network (subnet) for a Policy Manager Zone.

For more information on configuring Policy Manager zones, see Managing Policy Manager Zones.

Agent Version

Indicates the current version of the OnGuard agent.

Agent Installers

Installer Mode

Specify the action to be taken from the following options when the Aruba VIA component is used to provide VPN-based access:

Do not install/enable Aruba VIA component

NOTE: Selecting this option will automatically remove any existing and installed Aruba VIA client software.

Install and enable Aruba VIA component

NOTE: Selecting this option will automatically upgrade any existing and installed Aruba VIA client software.

NOTE: For related information, see Installing Standalone VIA 3.2.x with OnGuard Agent.

Windows

Use the download link to download OnGuard Agent for Windows.

NOTE: This binary file is provided in .exe and .msi formats.

Mac OS X

Use the download link to download OnGuard Agent for Mac OS X.

NOTE: This binary file is in .DMG format.

Ubuntu

Use the download link to download Ubuntu Agent for Linux.

NOTE: This binary file is in .tar.gz format.

Native Dissolvable Agent Apps

Windows

Click the URL to download Native Dissolvable Agent for Windows.

Mac OS X

Click the URL to download Native Dissolvable Agent for Mac OS X.

Ubuntu

Click the URL to download Native Dissolvable Agent for Ubuntu.

NOTE: You can download the .tar.gz files specific to 32-bit and 64-bit systems.

Agent Customization

Managed Interfaces

Select the type(s) of interfaces that OnGuard will manage on the endpoint. Select from the following options:

Wired
Wireless
VPN
Other

Mode

 

Select one of the following options:

Authenticate - no health checks: OnGuard collects username/password but does not perform health checks on the endpoint.
Check health - no authentication: OnGuard does not collect username/password.
Authenticate with health checks: OnGuard collects username/password and also performs health checks on the endpoint.
Username/Password Text:
The label for the Username and Password fields on the OnGuard agent.

NOTE: This setting is not valid for the Check health - no authentication mode.

Username Text

The label for the Username field on the OnGuard agent. This setting is not valid for the Check health - no authentication mode.

Password Text

The label for the Password field on the OnGuard agent. This setting is not valid for the Check health - no authentication mode.

Agent action when an update is available

Determines what the agent does when an update is available.

Select one of the following options:

Ignore: ClearPass Policy Manager ignores the available update.
Notify User: ClearPass Policy Manager notifies the user that an update is available.
Download and Install: ClearPass Policy Manager automatically downloads and installs an update when it is available.

Agent Remediation User Interface Customization

Custom User Interface

When you select the Configure check box, the Agent Remediation User Interface Customization dialog opens (see Figure 3):

Web Pages: To create the OnGuard custom web pages and define the properties for the web pages, click the Create link for the corresponding web page (for details, see the next section, Creating OnGuard Custom Web Pages).

Native Dissolvable Agent Customization

Managed Interfaces

The Native Dissolvable Agent performs health checks for one of the selected interfaces.

This feature ensures that, if both wired and wireless interfaces are connected, the OnGuard Agent will send health requests through the correct interface.

Select the type(s) of managed interfaces that are supported for the Native Dissolvable Agent.

Select from the following options:

Wired
Wireless
VPN
Other

Creating OnGuard Custom Web Pages

HTML Content for OnGuard Custom Web Pages
Important Points
OnGuard Custom Script Exit Codes

To create the OnGuard custom web pages:

1. Navigate to Administration > Agents and Software Updates > OnGuard Settings.

The OnGuard Settings page opens.

2. Scroll down to the Agent Remediation User Interface Customization section.

3. To enable the Custom User Interface configuration dialog, click (enable) the Configure check box.

Figure 2: Agent Remediation User Interface Customization Dialog

4. Click the Create link for the OnGuard custom web page you want to create.

For details, see HTML Content for OnGuard Custom Web Pages.

The Create Web Page (New) > Web Page Settings configuration dialog opens.

Figure 3: Configuring a New OnGuard Custom Web Page

5. Specify the required parameters (Name, Page Name, and Skin, as well as Title if desired), then click Create Page.

The OnGuard custom web page is created.

6. Window Behavior:
Always on Top: The custom user interface window will always be on top of any other windows present.
Allow Minimize: When set to True, the custom user interface window can be minimized.
Allow Close: Prevents users from closing the custom user interface window. If set to True, users will be allowed to close the custom custom user interface window; however, the execution of custom scripts will continue in the background.

 

Even if the Allow Close option is enabled, OnGuard Agent disables the Close button of the custom custom user interface while it is loading a page.

7. Window Size: Specify the window height and width, as well as whether the window size should be a percentage of the the client's screen or defined by the size in pixels.

HTML Content for OnGuard Custom Web Pages

OnGuard Start Page
OnGuard Progress Page
OnGuard Finish Success Page
OnGuard Finish Error Page
OnGuard Finish Reboot Page

This section provides the required names for each OnGuard custom web page as well as the recommended HTML content.

Be sure to use the Page Names specified here as ClearPass Policy Manager and OnGuard Agent look for pages with these names. Text in italics should not be changed.

OnGuard Start Page

The OnGuard Start Page is the initial web page shown to the end user when script execution begins. This page might include a Next button.

Page Name: onguard_start

HTML:

<p>Your device does not meet Minimum Specifications, which is required before you can connect to the Network.</p>

<p>The following is required:</p>

<div id="tasks_list">

</div>

<p>Please click the Next button below to start the remediation needed.</p>

<p>You will be connected to the Network after verification that your device meets all Minimum Security Specifications.</p>

<p><button id="next_button" type="button" onclick=""/>Next</button></p>

 

If the Next button is missing on the OnGuard Start Page, OnGuard Agent will move to the OnGuard Progress Page after 30 seconds. This time duration is not configurable.

OnGuard Progress Page

The OnGuard Progress Page shows the progress and status of custom scripts that are being executed.

Page Name: onguard_progress

HTML:

<p>Please do not disconnect your device.</p>

<div id="task_progress_list">

</div>

OnGuard Finish Success Page

The OnGuard Finish Success Page is shown after all the scripts have executed successfully and a system reboot is not necessary. This page includes a Close button.

Page Name: onguard_finish_success

HTML:

<p>We will now rescan your system to verify that it meets Minimum Security Specifications and then connect you to the Network.</p>

<p>If you are not connected in five minutes, please contact <b>12334</b> or <a href="https://www.google.com">click here</a> .</p>

<p><button id="close_button" type="button" onclick=""/>Close</button></p>

OnGuard Finish Error Page

The OnGuard Finish Error Page is shown if at least one of the scripts returns Failure and a reboot is not required. This page includes a Close button.

Page Name: onguard_finish_error

HTML:

<p>Remediating your device to meet Minimum Security Specifications was unsuccessful because:</p>

<div id="failed_tasks">

</div>

<p>Please visit this <a href="https://www.google.com">Support Page</a> to get assistance.</p>

<p><b>You are not yet connected to the Network.</b></p>

<p><button id="close_button" type="button" onclick=""/>Close</button></p>

OnGuard Finish Reboot Page

Page Name: onguard_finish_reboot

The OnGuard Reboot Page is shown after all the scripts have executed successfully and a system reboot is necessary. This page includes a Reboot button.

HTML:

<p>We will now rescan your system to verify that it meets Minimum Security Specifications and <b>reboot your system</b>, then connect you to the Intel Network.</p>

<p>If you are not connected in five minutes, please contact <b>12334</b> or visit this <a href="https://www.google.com">Support Page</a> to get assistance.</p>

<p><button id="reboot_button" type="button" onclick=""/>Reboot</button></p>

Important Points

This section provides important notes regarding OnGuard Agent behavior when using the Custom User Interface for Custom Scripts.

 

In ClearPass Policy Manager 6.6.7, this feature is supported for Windows Persistent Agent only.

1. OnGuard Agent checks the custom script's exit code to compute the custom scripts status.
2. OnGuard Agent determines the final page based on the script's exit codes and the client's health status. For details, see the next section, OnGuard Custom Script Exit Codes.
3. This feature is not supported when OnGuard is running as a service.
4. The custom user interface loads a fresh web page from ClearPass Guest every time. It does not cache the pages.
5. If the user closes the custom user interface while the script is executing, OnGuard Agent continues executing scripts without the custom user interface.
6. Administrators will have to refresh or open the OnGuard Settings page again after creating web pages in ClearPass Guest (Administration > Agents and Software Updates > OnGuard Settings).
7. If the ClearPass Server Certificate is not validated when ClearPass loads the web page for the first time, the custom user interface displays the following security alert:

Figure 4: Server Certificate Not Validated Security Alert

8. A new option, Server Communication Mode, has been added in Global Agent Settings that you can configure to avoid receiving a Server Certificate security alert (see the Server Communication Mode parameter description in Global Agent Settings Parameters for OnGuard Agents).

OnGuard Custom Script Exit Codes

The OnGuard custom script exit codes are comprised of Success Codes and Failure Codes as described below:

Success Codes (0 to 63)

The range available to Administrators to define their own Success Codes = 3 (0x03) to 63 (0x3F).

Script executed successfully = 0 (0x00)
Reboot (Reboot is required) = 2 (0x02)

Failure Codes (65 to 255)

The range available to Administrators to define their own Failure Codes = 65 (0x41) to 255 (0xFF).

Script executed successfully but its exit code indicates failure = 64 (0x40)

OnGuard Agent Codes (256 onwards):

Unknown error = 256 (0x100)
Timeout: Script did not finish execution in expected time = 257 (0x101)
Failed to read exit code of script = 258 (0x102)
OnGuard failed to execute script = 259 (0x103
Script file not found = 260 (0x104)
Script file did not pass validation checks = 261 (0x105)
Failed to download script file = 262 (0x106)
Execution level is set to “User” but the user is not logged on, so OnGuard was not able to launch the script = 263 (0x107)

Installing Standalone VIA 3.2.x with OnGuard Agent

ClearPass supports standalone installation of both VIA 3.2.x and the OnGuard Agent. This allows administrators to use VIA 3.2.x functionality that is not yet available in the Unified Agent in conjunction with the OnGuard Agent. This feature is supported by OnGuard 6.6.10 and higher and by VIA 3.2.2 and higher. This feature is available only on Windows OS.

To use this feature, OnGuard must be installed by passing the AllowBothVIAAndOnGuard flag to the installer in the following format:

ClearPassOnGuardInstall.exe /AllowBothVIAAndOnGuard=1

msiexec /i ClearPassOnGuardInstall.msi ALLOWBOTHVIAANDONGUARD=1

Both OnGuard and VIA must be installed with this flag in order for them to co-exist on the same system. If either of them is installed without this flag, the other cannot be installed.

In addition, VIA must be installed with the ALLOWBOTHVIAANDONGUARDflag in the following format:

msiexec /i Aruba-VIA-3.2.0.0.XXXXX-64(86).msi ALLOWBOTHVIAANDONGUARD=1

 

If the ClearPass OnGuard Unified Agent is installed with AllowBothVIAAndOnGuard=1, the Unified Agent will not enable the VPN component, even if it is enabled in the ClearPass user interface, i.e., the ClearPass OnGuard Unified agent will run in OnGuard-only mode even if the Administration > Agents and Software Updates > OnGuard Settings > Installer Mode option is set to Install and enable Aruba VIA component.