Setting Up the Native Messaging Host

The Delinea Native Messaging Host makes it easier to manage settings for the Delinea Web Password Filler. It also provides a more robust method of storing the settings so they are not impacted when the browser cache is deleted.

Without the Native Messaging Host, Web Password Filler runs normally, but the end user will be required to supply the Secret Server URL and to modify other settings to meet their needs.

The Native Messaging Host includes one executable file and one configuration file. You install these files on your computer. Each time you launch your browser, the Native Messaging Host silently sends default configurations and settings to Web Password Filler.

You can prevent Web Password Filler from functioning on specific URLs by adding those URLs to an exclusion list. Web Password Filler will not access Secrets for URLs on the exclusion list, nor will it fill or auto-populate credentials or other information for those URLs.

To use an exclusion list with Web Password Filler, the Native Messaging Host is required.

Downloading the Native Messaging Host

You can download the Native Messaging Host installer here.

Software Requirements

• .NET version 4.8 or later
• Delinea Web Password Filler version 3.10 or later

Supported Browsers

• Chrome
• Edge Chromium
• FireFox

You can find additional information regarding Native Messaging at:

• https://developer.chrome.com/extensions/nativeMessaging
• https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging

Installing the Native Messaging Host

You install the Delinea Native Messaging Host on your computer by copying the ThycoticMessagingHost.exe and settings.json files into an accessible directory such as C:\Thycotic\Web Password Filler\.

Registering the Native Messaging Host

You must then register the ThycoticMessagingHost.exe with the browsers by running ThycoticMessagingHost.exe with a --register command line option, for example, by entering C:\Thycotic\Web Password Filler\ThycoticMessagingHost.exe --registerinto a command window. Native Messaging Host cannot interact with Web Password Filler until this registration is completed.

Once you have successfully registered the Native Messaging Host, it will check the configuration file for updates automatically each time you launch your browser. You do not have to unregister and re-register each time you make a change to the configuration file.

If you manually add the WPF extension to the browser instead of getting it from the browser store, the extension ID changes. In that case, you MUST update the settings.json to reflect the new extension ID. Whenever you change the extension ID, you must run the -–register command line option again before the extension will be able to communicate with the Native Messaging Host. Refer to the settings.json example below.

Changing other options or settings in the settings.json will automatically be reflected once you launch your browser.

During the registration process, the Native Messaging Host creates a folder for each browser (Chrome, Edge, Firefox, and Opera) containing the “native messaging host configuration” information required by each browser. Additionally, registry entries are created for each browser in either the current user registry or the local machine registry.

For example, you will find HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.thycotic.wpf.host with a default value that is the path to the “native messaging host configuration” file. If you register using the EnableForAllUsers = true option, you must run the registration as an administrator.

Uninstalling the Native Messaging Host

To disable or remove the Native Messaging Host, use the –unregister option, for example C:\Program Files\Thycotic\Web Password Filler\ThycoticMessagingHost.exe --unregister. Once unregistered, the Native Messaging Host can no longer communicate with Web Password Filler.

Configuring Web Password Filler Settings

The Native Messaging Host facilitates the management of Web Password Filler settings through modification of a settings.json file. Each time you launch your browser, the Native Messaging Host reads the default configurations and settings in the json file and silently sends them to Web Password Filler. Web Password Filler then updates the local storage with the new settings and configurations.

Establishing Default Settings and Browser-Specific Overrides

The settings.json file begins with a line for each browser, with the browser's identification code. In the image below, these lines are identified by the label, Browser IDs. The next lines in the file, labeled Default Settings in the image, establish your default settings for the Native Messaging Host. The default settings apply to all browsers unless a browser-specific setting overrides the default. Each browser has its own section of code for overrides, labeled Default Overrides per Browser in the image. The first line in the section identifies the browser with the same identifier used at the beginning of the file. The lines that follow in the section mirror the lines used to establish the Native Messaging Host default settings. For each line where the browser-specific value differs from the default value, the browser-specific value takes precedence, overriding the default value.

Formatting the settings.json File

Below is an example settings.json file that sets the Secret Server URL to <https://SomeURL/SecretServer>, sets the domain to “local” and enables various other options for the Delinea Web Password Filler.

We recommend validating the settings.json file prior to deployment to ensure that the json is formatted correctly. There are many free online tools for validating json files.

{
  "chromeExtensionId": "mfpddejbpnbjkjoaicfedaljnfeollkh",
  "edgeExtensionId": "kjldmpkefedgljefehmmfifbhnjngmbh",
  "operaExtensionId": "eemnnadjdifcpkcnpalolohpepihhbbo",
  "firefoxExtensionId": "dd1e31d5-3623-45cb-b1ad-64074d36b360@thycotic.com",
  "ConfigSSUrl": "https://SomeURL/SecretServer",
  "ConfigDomain": "local",
  "HideConfigPage": false,
  "HideSettingPage": false,
  "SettingUserSSLogin": true,
  "SettingPrompToSave": true,
  "SettingShowPopup": true,
  "SettingHideReadOnlyFolders": true,
  "SettingEnableAutoPopulate": true,
  "EnableForAllUsers": false,
  "PopupDefaultPosition": true,
  "ExactMatchUrl": false,
  "maxSessionRecordingLimit": 120,
  "Exclude": [ "http://*" ],
  "ExcludeException": [],
  "PerExtensionOverride": [
    {
      "id": "mfpddejbpnbjkjoaicfedaljnfeollkh",
      "ConfigSSUrl": "https://SomeURL/SecretServer",
      "ConfigDomain": "",
      "HideConfigPage": true,
      "HideSettingPage": false,
      "SettingUserSSLogin": true,
      "SettingPrompToSave": true,
      "SettingShowPopup": true,
      "SettingHideReadOnlyFolders": true,
      "SettingEnableAutoPopulate": true,
      "EnableForAllUsers": false,
      "PopupDefaultPosition": false,
      "ExactMatchUrl": true,
      "maxSessionRecordingLimit": 120,
      "Exclude": [
         "http://*",
         "http://endoftheinternet.com",
         "https://www.MyCompanySite.com",
         "https://live.com/"
       ],
      "ExcludeException": [
         "https:// MyCompanySite.com/Login.html",
         "https://login.live.com/login.srf"
       ]
    },
    {
      "id": "kjldmpkefedgljefehmmfifbhnjngmbh",
      "ConfigSSUrl": "https://localhost/SecretServer/",
      "ConfigDomain": "",
      "HideConfigPage": false,
      "HideSettingPage": false,
      "SettingUserSSLogin": false,
      "SettingPrompToSave": false,
      "SettingShowPopup": false,
      "SettingHideReadOnlyFolders": false,
      "SettingEnableAutoPopulate": false,
      "PopupDefaultPosition": false,
      "ExactMatchUrl": false,
      "maxSessionRecordingLimit": 120,
      "Exclude": [ "http://*" ],
      "ExcludeException": []
    },
    {
      "id": "dd1e31d5-3623-45cb-b1ad-64074d36b360@thycotic.com",
      "HideConfigPage": false
    },
    {
      "id": "eemnnadjdifcpkcnpalolohpepihhbbo"
    }
  ]
}

A boolean controls the menu's position on the screen; if set to true, the menu appears in the upper right corner, and if set to false, the popup will display below the credentials fields. Additionally, a boolean setting configures Web Password Filler to recognize only exact URL matches, meaning that if it's set to true, WPF will only accepts URLs that match the specified pattern. The duration allowed for a session recording is specified in minutes, with a default setting of 120 minutes and a maximum limit of 480 minutes. If a value in this section differs from the default value defined at the top of the JSON file, the value specified here takes precedence for that browser, overriding the default setting.

Excluding Sites and Making Exceptions

The Delinea Web Password Filler is an “inclusive” extension. Any website that contains a username and password has the potential to have a secret retrieved from or stored in Secret Server. However, some sites are simple web forms that contain user name, password, and a variety of other field types. Registration forms, for instance, would not require interaction or population of the username and password from WPF. The Delinea Native Messaging Host allows you to add exclusions as well as exclusion exceptions so those sites you do not want Web Password Filler to interact with will be ignored. Add exceptions for any site you wish WPF to ignore. For example, to login to an application, you want WPF to retrieve a secret for the login page. However, if you would like WPF to ignore every other page for that same site, add the specific page URL to the exclusion exception list.

To exclude all sites, a wild card can be used (https://* and/or http://*) and then simply add the sites where secrets are available (https://MyCompanySite.com/login.aspx) to the exclusion exception list.

Only the “Exclude” section accepts a wild card. You must enter the “ExcludeException” as the exact URL without a query string.

Setting UI Behavior Based on Preferences

You can set each preference on the Preferences page to “true” or “false” in the settings.json file.

You can set the Secret Server URL and Domain by including strings (text wrapped up in quotations).

Additionally, you can choose to hide these pages from the end user so that the settings and configuration options cannot be changed.

Managing Error Messages

Error messages are recorded in the file named native-messaging, which is stored in the same folder where you installed Native Messaging Host. The error messages in this file are especially useful when contacting Delinea support services.

• The following error message indicates that there are missing elements in the settings.json.

  Copy

  There are elements missing from settings.json. Review the documentation and update setting.json with the missing attributes.
  

  Review the settings.json format and ensure all elements are provided and the json file is well formatted.

• The following message indicates that the setting “EnableForAllUsers” is set to true. However, the user attempting to register the Delinea Native Messaging Host does not have administrator permissions and cannot update or create the key local machine registry key required for browser registration.

  Copy

  This application must be run as an administrator when registering for All Users
  

• The following error message indicates that the ThycoticMessagingHost.exe was executed without the required command line option.

  Copy

  To register the Native Messaging Host, run cmd.exe ThycoticMessagingHost.exe –register
  To unregister the Native Messaging Host, run cmd.exe ThycoticMessagingHost.exe --unregisterPress any key to exit

• The following message indicates that only --register and --unregister are valid command line options.

  Copy

  Incorrect command line. Review the documentation to register or unregister this application.