Installing Manually

HYPR Passwordless: Installation

For testing and pilot purposes you can install the HYPR Passwordless client application manually for each user. However, for deploying to larger segments of your workforce population you’ll want to integrate with a configuration management solution such as Microsoft Endpoint Configuration Manager (formerly SCCM) or Jamf on macOS.

This page describes the available installation parameters and shows how to run the installer from the command line for compatibility with configuration management tools.

Installation Parameters

For both Windows and macOS, the HYPR installer reads its configuration parameters from the hypr.json file located in the same directory as the installer. For Windows, you can also pass the parameters directly on the command line.

πŸ“˜

All Right

If your downloaded install package already includes a hypr.json file, be cautious about changing any of the preconfigured values. This is how HYPR provides the necessary custom parameters for your installation.

The `hypr.json file is a simple collection of name-value pairs, each defining a single install parameter. For example:

{
  "version":"1.0",
  "rpUrl":"https://highlandsbank.gethypr.com/rp",
  "appId":"HYPRDefaultWorkstationApplication",
  "pinningHash":"LeM8XnCIy8+Cxm+HKTEOBZr1g3D8odQNHTH+vdu7RWc=5kJvNEMw0KjrCAu7eXY5HZdvyCS13BbA0VJG1RSP91w=",
  "installToken":"0f03f635-4d9a-46ff-b537-cd97ad77cb6e",
  "certTemplate": "hyprwin",
  "securityKeyCertTemplate": ""
  "supportEmail":"[email protected]",
  "fullUI":"1"
}

The available parameters are as follows:

JSONCommand LineDescription
rpUrlHYPRRP(Required) The URL of your HYPR instance:

https://yourtenant.gethypr.com/rp

Note that the URL must end in /rp
appIdHYPRAPPID(Required) The ID of the HYPR Control Center internal application used to configure the Workstation functionality. The value is the same for all HYPR deployments:

HYPRDefaultWorkstationApplication
pinningHashHYPRHASH(Required) An SHA1 hash of the HYPR server SSL certificate which serves as a public key pinning value.

This value can be obtained from the hypr.json file included when you download HYPR Passwordless (Workforce Access Client).
installTokenHYPRINSTALLTOKEN(Required) A token used to establish encrypted communication between the HYPR Passwordless client and the HYPR Server.

The value is pre-set for each HYPR deployment and shouldn’t be changed.
certTemplateHYPRTEMPLATEThe name of the Active Directory certificate template for Advanced Installs and mobile enrollment. HYPR Support will help you create and name the template, but by default the template name is either hyprwin (for Windows) or hyprmac (for macOS).

If you prefer to create your own custom AD certificate template, please follow these instructions.
supportEmailHYPRSUPPORTThe email address used for any support requests sent by the user from within the HYPR Passwordless client.
proxyServerHYPRPROXYSERVERA proxy server to be used when the HYPR Passwordless client communicates with the HYPR Server, in the form proxy[:port]. For example:

proxy.myoffice.com:3128

The port is optional and defaults to 8080.
proxyBypassHYPRPROXYBYPASSA comma-separated list of host names to be excluded from the proxy connection. If the URL matches any of the hosts in the list, the proxy will be bypassed and a direct connection made. Host names can include wildcards (e.g., .mycompany.com or 10.20.).
qrCodeURLHYPRQRCODEURLThe URL to handle incoming QR code requests. Typically this will be your tenant URL, but may differ.
allowPasswordForPairedUsersN/A(macOS only) Disables the password prompt at login for users who have previously paired using HYPR. Set to false to enforce passwordless login. Enabled (true) by default.
This corresponds to AllowPasswordForPairedUsers described in Configuration Parameters.
See Passwordless Enforcement for Unlock and Login for a full description.
allowPasswordUnlockForPairedUsersN/A(macOS only) Enables/Disables the password prompt at unlock for users who have previously paired using HYPR. Set to false to enforce passwordless unlock. Enabled (true) by default.
This corresponds to AllowPasswordUnlockForPairedUsers described in Configuration Parameters.
See Passwordless Enforcement for Unlock and Login for a full description.
certPublishersN/A(macOS only) (Optional) A comma-separated a list of DNS names for the servers running the service that can generate certificates on behalf of the user. The HYPR Passwordless client will browse the AD forest if you omit this parameter, but if you have multiple servers deployed to manage the domain infrastructure it can take time to explore all of them.
This corresponds to CertificatePublishers described in Configuration Parameters.
certAuthorityN/A(macOS only) (Optional) The name of the publisher of the Active Directory. The HYPR Passwordless client will browse the AD forest if you omit this parameter, but if you have multiple servers deployed to manage the domain infrastructure it can take time to explore all of them.
This corresponds to CertificateAuthority described in Configuration Parameters.
fullUIN/A(Windows only) Should the Environment Setting dialog be displayed during the install.

0 - hide the dialog
1 - show the dialog

Hiding the dialog keeps users from changing any of the configuration parameters set in the hypr.json configuration file when the installer is run normally. Not applicable when installing using msiexec with command-line parameters.
customLogoHYPRCUSTOMLOGO(Windows only) The path to a locally-stored custom image to override the default HYPR logo.

Supported formats: PNG, JPEG, or BMP

Preferred image size: 101x82 pixels

Backslashes in the file path need to be doubled up. For example:

C:\\myImages\hb_logo.png
customBackgroundHYPRCUSTOMBACKGROUND(Windows only) The path to a locally-stored custom image to override the default background.

Supported formats: PNG, JPEG, or BMP

Preferred image size: 633x398 pixels

Backslashes in the file path need to be doubled up. For example:

C:\\myImages\hb_background.png
passwordlessUserTileHYPRPASSWORDLESSUSERTILE(Windows only) If enabled (value 1), the Passwordless User login tile displays by default. Otherwise (value 0), the default is controlled by Windows. The equivalent registry setting is Passwordless User Tile.
securityKeyCertTemplateHYPRSECURITYKEYTEMPLATE(Windows only) The name of the Active Directory certificate template if using non-exportable private keys. If this parameter is defined, HYPR Passwordless client will use the certTemplate value when requesting a certificate for a mobile enrollment, and the securityKeyCertTemplate when requesting a certificate for a security key. If a value is not specified (or is empty), the same template will be used for mobile devices and security keys.

Installations using this parameter will generate a Certificate Template (Security Keys) registry value in the key, HKLM:\SOFTWARE\HYPR Workforce Access.

To create your own custom AD non-exportable security key certificate template, please follow these instructions.

Command Line Installation for Windows

You can use the msiexec command to deploy the HYPR Passwordless for Windows client without the displaying the installation UI. Note that if you’re doing this manually at the command line you’ll need to run from a command prompt that has administrative privileges.

You have two options for setting the necessary parameters:

Option 1

  1. Define the installation parameters in a hypr.json configuration file located in the same folder as the HYPR Passwordless .msi file. (See Installation Parameters above.)
  2. Run msiexec without any parameters:
msiexec.exe /qn /i WorkforceAccess_x64.msi

Option 2

  1. Pass the installation parameters directly to msiexec on the command line. For example:
msiexec.exe /qn /i WorkforceAccess_x64.msi HYPRAPPID="HYPRDefaultWorkstationApplication"
HYPRRP="https://highlandsbank.gethypr.com/rp" HYPRSUPPORT="[email protected]" HYPRHASH="LeM
8XnCIy8+Cxm+HKTEOBZr1g3D8odQNHTH+vdu7RWc=,5kJvNEMw0KjrCAu7eXY5HZdvyCS13BbA0VJG1RSP91w="
HYPRINSTALLTOKEN="0f03f635-4d9a-46ff-b537-cd97ad77cb6e" HYPRSUPPORT="[email protected]"

HYPR Registry Keys

The installation process adds a HYPR key to the Windows Registry at the following location:

Computer\HKEY_LOCAL_MACHINE\SOFTWARE\HYPR Workforce Access

The contents of this registry key are required for normal functioning of the application and shouldn’t normally be changed post-install. However, for troubleshooting purposes HYPR Support may ask you to review or modify some of the values.

Terminal Installation for macOS

You can use the installer command to deploy the HYPR Passwordless client for macOS without displaying the installation UI. Note that if you’re doing this manually in a Terminal window you’ll need to use sudo to grant the necessary privileges.

  1. Define the installation parameters in a hypr.json configuration file located in the same folder as the HYPR Passwordless .pkg file. (See Installation Parameters above.)
  2. Run the installer command as follows:
installer -pkg /path/to/WorkforceAccess-\<version\>-Installer.pkg -target /
  1. The installer will prompt you for a password (if using sudo) and report on the status of the install. For example (replace with the HYPR version):
ghopper@MacBook-Pro ~ % sudo installer -pkg /Users/gracehopper/Desktop/WorkforceAccess-
[<version>]-Installer.pkg -target /
Password:
installer: Package name is WorkforceAccess-<version>-Installer
installer: Upgrading at base path /
installer: The upgrade was successful.
installer: The install requires restarting now.
ghopper@MacBook-Pro ~ %
  1. Restart the workstation when finished.

HYPR Application .plist Keys

The installation process stores a number of key values in an application .plist file in the following location:

/Library/HYPR/HyprOneService.plist

These keys are required for normal functioning of the application and shouldn’t normally be changed post-install. However, for troubleshooting purposes HYPR Support may ask you to review or modify the values.

Configuration Parameters

ParameterDescriptionTypeExample
ApplicationIdName of your Application in the HYPR Control CenterRequiredAcmeMacOSApp
RelyingPartyPinsSSL Pinning for the RP applicationRequired[PIN value]
RelyingPartyUrlURL of your HYPR tenant with added /rp path.Requiredhttps://acme.hypr.com/rp
SupportEmailEmail address of your support team managing the HYPR server.Requiredsupport@acme.com
CertificateAuthEnabledA boolean parameter that enables/disables certificate-based authentication.Optionaltrue
CertificateTemplateName of your Certificate Template in the Microsoft Security Authority. This is a required parameter if you're using the domain-joined computer.OptionalAcmeMacOSUser
CertificatePublishersA comma-separated a list of DNS names for the servers running the service that can generate certificates on behalf of the user. The HYPR Passwordless client will browse the AD forest if you omit this parameter, but if you have multiple servers deployed to manage the domain infrastructure it can take time to explore all of them.
This corresponds to certPublishers described in Installation Parameters.
OptionalDNS1.ADDRESS.COM, DNS2.ADDRESS.COM
CertificateAuthorityThe name of the publisher of the Active Directory. The HYPR Passwordless client will browse the AD forest if you omit this parameter, but if you have multiple servers deployed to manage the domain infrastructure it can take time to explore all of them.
This corresponds to certAuthority described in Installation Parameters.
Optionalhypr-DEVW2012R9DOMXDC-CA
AllowPasswordForPairedUsersEnables/Disables the password prompt at login for users who have previously paired using HYPR. Set to false to enforce passwordless login. Enabled (true) by default.
This corresponds to allowPasswordForPairedUsers described in Installation Parameters.
See Passwordless Enforcement for Unlock and Login for a full description.
Optionaltrue
AllowPasswordUnlockForPairedUsersEnables/Disables the password prompt at unlock for users who have previously paired using HYPR. Set to false to enforce passwordless unlock. Enabled (true) by default.
This corresponds to allowPasswordUnlockForPairedUsers described in Installation Parameters.
See Passwordless Enforcement for Unlock and Login for a full description.
Optionaltrue

Manual Configuration

  1. In a terminal, use sudo to edit /Library/HYPR/HyprOneService.plist via an editor (vi, nano, etc.).
  2. Modify the file according to your configuration. It will appear similar to this:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    	<key>ApplicationId</key>
    	<string>hyprWindowsLogin</string>
    	<key>LogLevel</key>
    	<integer>5</integer>
    	<key>QrCodeUrl</key>
    	<string></string>
    	<key>RelyingPartyPins</key>
    	<string>g1eupqU9HGvXhObmQWABAKQXRYqKB/IziIWKgnn44IY=,LeM8XnCIy8+Cxm+HKTEOBZr1g3D8odQNHTH+vdu7RWc=,klO23nT2ehFDXCfx3eHTDRESMz3asj1muO+4aIdjiuY=,grX4Ta9HpZx6tSHkmCrvpApTQGo67CYDnvprLg5yRME=</string>
    	<key>RelyingPartyUrl</key>
    	<string>https://highlandsbank.hypr.com/rp</string>
    	<key>SupportEmail</key>
    	<string>[email protected]</string>
    </dict>
    </plist>
    
  3. Update the ApplicationId, RelyingPartyUrl, RelyingPartyPins, and SupportEmail based on the current server configuration.
  4. Reboot the computer to apply the changes.

Enterprise Deployment and Configuration

To deploy the HYPR Passwordless client in an enterprise, wrap a script around that installation package. The script installs the package and updates the HyprOneService.plist file of all affected users.

This can be achieved with a combination of the defaults and plutil commands.

Example

#! /bin/bash

PLIST_FILE=/Library/HYPR/HyprOneService.plist

# Install the HYPR Employee Access package.
installer -pkg EmployeeAccess-2.1-Installer.pkg

# Customize the configuration.
defaults write $PLIST_FILE ApplicationId "NAME OF YOUR APP IN CONTROL CENTER"
defaults write $PLIST_FILE RelyingPartyPins "<COMMA DELIMITED LIST OF PINS>"
defaults write $PLIST_FILE RelyingPartyUrl "https://CONTROL_CENTER_URL/rp"
defaults write $PLIST_FILE SupportEmail "SUPPORT EMAIL"

# Convert the configuration file to XML.
plutil -convert xml1 $PLIST_FILE

FileVault Configuration

Apple FileVault doesn't support the smart card authentication protocol, and it can only be unlocked with a user password. Still, there's an option to require HYPR authentication after the FileVault unlock to ensure that users are always using an MFA solution.

Disable the automatic login option of FileVault by executing the following command:

sudo defaults write /Library/Preferences/com.apple.loginwindow DisableFDEAutoLogin -bool YES

If this is disabled, users will be required to authenticate with HYPR Mobile App after entering the FileVault password.

Passwordless Enforcement for Unlock and Login

Configure HYPR to enforce logins without requiring a password as long as HYPR Passwordless client is installed on the workstation. This feature can enable or remove the option to enter a password for workstation login and for workstation unlock.

Passwordless Login Enforcement works provided the user has a valid HYPR pairing. If the user removes all pairings, the password login is enabled again by default.

The feature works for local accounts and not domain-joined Mac workstations.

The configuration parameter that controls these features (AllowPasswordForPairedUsers for Logins; AllowPasswordUnlockForPairedUsers for Unlocking) must be defined either at installation time or as part of the .plist configuration setting. The parameters are called and enabled by default (set to true). When disabled (false), passwords won't be allowed by paired users.

Also see Configuration Parameters.

πŸ“˜

Administrator Caveats

If FileVault auto-login is not disabled, it’s not possible to achieve a passwordless login experience, as the system will automatically pass the FileVault PIN as the login password. We recommend administrators only enable this setting if FileVault auto-login is disabled.

Administrators should make sure they have recovery mechanisms in place for their users before enabling this feature - an IT controlled local account, or a way to push .plist settings to disable it (e.g., JAMF)

MacOS’s Fast User Switching feature can be used to bypass this restriction, as it allows switch to another user, thereafter providing a password. In order to achieve a more complete passwordless experience and remove this risk, administrators are advised to disable this feature either using the local settings (using the command shown here) or through a mobile device manager (MDM) such as JAMF.

defaults write /Library/Preferences/.GlobalPreferences MultipleSessionEnabled -bool 'NO'