HYPR Passwordless Diagnostics Tool

HYPR Passwordless: Workstation Troubleshooting: Windows

The HYPR Passwordless Diagnostics Tool is designed to simplify troubleshooting the HYPR Passwordless client in a new environment or during active deployment when users are experiencing problems with authentication or registration. The tool allows common system compatibility tests such as certificate template validation, user permission, and network connectivity. It is based upon Microsoft's Active Directory Certificate Services (AD CS); more detailed information about AD CS can be found here.

This document explains how to run the HYPR Passwordless client Diagnostics Tool, including the various switches used to get different results, on a Windows 10 operating system. The Diagnostics Tool is a standalone application included in the HYPR Passwordless client .msi client installation.

Running Tests

The Diagnostics Tool can be launched either by double-clicking the HYPR logo on the HYPR Passwordless client dialog (the logo location varies by version) or by issuing commands at a command-line prompt.

Launching the Diagnostics Tool from the GUI

769

To start the UI version, double-click the logo at top left. You are prompted to confirm running the tests:

668

Click Yes to run the tests.

984

Launching the Diagnostics Tool from the Command Line

πŸ“˜

Run as administrator

If the logged in user is not an administrator, run CMD as an administrator to use the Diagnostics Tool.

To run tests for the current user:

  • Change directory to C:\Program Files\HYPR\ and launch HyprDiagnosticsConsole.exe from there, or
  • Run it from anywhere using the complete path, C:\Program Files\HYPR\HyprDiagnosticsConsole.exe

πŸ“˜

Sharing is Caring

This folder exists for all users with the HYPR Passwordless client installed.

Run HyprDiagnosticsConsole.exe help for more details about the tool usage and parameters.

Example Commands

  • To run basic tests that don't require administrative privileges:
    HyprDiagnosticsConsole.exe run
  • To run administrative tests, replace HYPRUserTest in the example below with your certificate template name:
    HyprDiagnosticsConsole.exe run --include-domain-admin-tests --test-certificate-template=HYPRUserTest

Output Directory

The test results will be stored in a \Diagnostics directory where the executable resides. The output directory format is <workstation>_<username>. So for user HIGHLANDSBANK\grace.hopper, the default location is C:\ProgramData\HYPR\Diagnostics\HIGHLANDSBANK_grace.hopper, followed by a subdirectory for each test attempt.

Subdirectories will be created in this folder during each test attempt, named to match the test performed and inclusive of a date-time stamp. (EX: \run-2022-03-08_15-23-45\ADCS) A maximum of 10 subdirectories will be stored in this fashion; the older ones will be removed as newer tests are generated. In each of the timestamped folders, under \ADCS, is a .json file containing the results for each test that was run.

The HyprDiagnostics.log file is written to the \Diagnostics folder. It includes valuable information that Support may need to diagnose advanced issues.

The output directory can be changed for a given test by using the --output-dir parameter, described below.

Test Results

The tests will give a result of Passed (in green on the GUI version) or Failed (in red on the GUI version). If any test fails, the issue description, error code, and recommended resolution will be displayed to the right of the applicable test.

Supported Commands

run

Used to run both the built-in diagnostics tests and any ad hoc tests you want to use. Used alone, it runs only the non-domain administrative tests.

HyprDiagnosticsConsole.exe run

tests

Lists tests both built-in and ad hoc.

HyprDiagnosticsConsole.exe tests

results

Lists results from previous runs (NOT IMPLEMENTED YET).

HyprDiagnosticsConsole.exe results

example

This command returns examples for various parameters, which are detailed in the following section.

HyprDiagnosticsConsole.exe example

Supported Parameters

Below are descriptions of the parameters for the above commands:

-? or -h or --help

1600

This is the default --help parameter providing details for all the supported commands and parameters.

--config=<path>

Used to supply parameters using a .json file. Usage can be found by using the --help parameter.

HyprDiagnosticsConsole.exe run --config=C:\Users\<username>\Desktop\hypr-diag.json

This parameter requires a .json file for all the parameters you would like to test with the Diagnostics Tool. The format of the content to be updated in the .json file can be obtained by running the example command as shown here:

HyprDiagnosticsConsole.exe example --config-non-default

HyprDiagnosticsConsole.exe" example --config-default

1952

--include-domain-admin-tests

Run domain administrative tests. The tests marked with the domainAdminTest attribute will run when the above parameter is specified.

HyprDiagnosticsConsole.exe runΒ  --include-domain-admin-tests

1604

--adhoc-files=<file1;file2;...>

Use the above parameter to supply the ad hoc test file path. The command shown here returns an example ad hoc test.

HyprDiagnosticsConsole.exe example --adhoc

Copy the output and save the content as a .json file, providing the file name from the above parameter <file1;file2;...>.

1602

--adhoc-only

Use the above parameter to run only ad hoc tests.

HyprDiagnosticsConsole.exe runΒ  --adhoc-only --adhoc-files=C:\Users\<username>\Documents\adhoc.json

1604

--adhoc-dirs <dir1;dir2;...>

Specify directories to file the relative file names specified in --adhoc-files parameters.

--test-certificate-template=HYPRUserTest

Provides the certificate template name to be used running the test. By default if no value is passed or if the parameter is not specified, the certificate template from the HYPR configuration in the registry editor will be picked up for the tests.Β If the registry entry is empty, User will be assumed as the configuration template to be used by default. Some examples follow:

When no parameter is specified:

1604

When the parameter is specified and supplied with a valid template name:

When the parameter is specified and supplied with a invalid template name:

--output-dir=<path>

Store test output in the specified path using this parameter.

6288 6008

--filter-name <positive-patterns: -negative-patterns>

A sequence of search patterns separated by colons (:). Negative search patterns should be preceded by a hyphen (-). Both positive and negative patterns can use wildcards to match the test name, which is identified by <Test Group Name>.<Test Name> where <Test Group Name> is the name of the folder including the date-time stamp, and <Test Name> is the name of the specific test, such as Certificate Template.

--output-width=<N>

Explicitly limit the width of the error column in characters.

--log-file=<path>

Specify a custom location in which to write logs.

--log-level=<N>

Overrides the default log level, which is 6 if not specified or if the WACDT is not installed.

--timeout=<N seconds>

Override any and all test timeouts with the entered value.

--connect-timeout=<N seconds>

Overrides default connect timeout value of 10 with the specified value.

--test-certificate-template=<certificate template name>

Specify a certificate template name to be used for testing. When not used, the Diagnostics Tool defaults to User.

--verbose

Includes a more detailed result.

--very-verbose

And an even more detailed result.