Skip to main content

Authorize fins:// link installation

important

Behavior Change: fins:// protocol handlers require a Trusted App Configuration (TAC) for first-time installations

  • Providers installing via MSI, installer, or a managed package require no action.
  • For managed RVM upgrades, we encourage an upgrade to version 20.0.1.4 to take advantage of the improved security posture.

Starting with HERE Core RVM 20.0.1.4, Trusted App Config (TAC) enforcement for protocol-link installation is on by default. To keep your application installable via fins:// links, request that it be cryptographically authorized for fins:// installation at support@here.io. A desktop owner can turn off the enforcement on their managed desktops.

This feature works by adding a trustedAppConfigs object to your application manifest. You provide your manifest URL(s) to HERE, and HERE provides you with a signed trustedAppConfigs definition that grants the enableFinsProtocolInstallation feature for those application manifest URLs. For a more detailed explanation of TACs, see Trusted application configurations.

When this feature is needed​

Platform providers prefer the ease of deploying/launching their application via a URL link to a device known to use HERE software.

How it works​

  1. You provide the following information to HERE:

    • A list of manifest URLs (or match patterns) that identify the application manifests to be authorized for fins:// installation.

    • A request that those URLs be granted the enableFinsProtocolInstallation TAC feature.

  2. HERE provides you with a trustedAppConfigs property definition, which contains an embedded digital certificate, includes platform-specific signatures, and grants the requested feature for the requested URLs.

  3. You include this trustedAppConfigs verbatim in your application manifest.

  4. When an end user clicks a fins:// link that targets your manifest URL on a desktop where requireTacForFinsProtocolInstallation is true (the default), the HERE Core RVM does the following:

    • Verifies the trustedAppConfigs signature.

    • Checks that the manifest URL matches the URLs/match patterns granted in your trustedAppConfigs.

    • Confirms that the granted features include enableFinsProtocolInstallation.

    • If all three checks pass, allows the new installation to proceed.

Already-installed apps re-launch successfully regardless of this gate — only new installations are subject to the check.

If you authorize multiple applications, the configuration information for all of them is encoded in a single value property. Use the same trustedAppConfigs definition in each of the application manifests.

How to use it​

For first-time installations​

The trustedAppConfigs definition as provided by HERE has the structure shown in the following example. You add this object as a top-level property of the application manifest:

"trustedAppConfigs": {
  "value": "BASE64-ENCODING-OF-CONFIGURATION",
  "signature": {
    "win": "BASE64-ENCODED-SIGNATURE-FOR-WINDOWS",
    "mac": "BASE64-ENCODED-SIGNATURE-FOR-MACOS"
  }
}

The encoded value declares the enableFinsProtocolInstallation feature for the manifest URLs you requested. If you already use a trustedAppConfigs definition for other TAC features (such as licensed media codecs or extension server URLs), HERE issues a single, combined definition that covers all your requested features.

Your TAC covers only the manifest URLs you requested. It does not cover local or CI manifests. See For development environments.

For development environments​

Local development manifests and most CI manifests have no TAC, so first-time installs from fin:// or fins:// links fail with an "Unable to open app" dialog. Apps that are already installed keep launching.

You can keep using links in development in either of two ways:

Install once with --config, then use your links​

The TAC check only applies when a link installs an app for the first time. Apps that are already installed always launch from links. So instead of changing the DOS, you can install the app once with --config, then keep using your fin:// and fins:// links as before.

1. Install the app once with --config​

Run this once per app, with the manifest's normal http:// or https:// address. Don't use the fin:// or fins:// address here.

Windows (default RVM location):

"%LOCALAPPDATA%\OpenFin\OpenFinRVM.exe" --config="http://localhost:5555/app.json"

macOS (default RVM location):

/Applications/OpenFinRVM.app/Contents/MacOS/OpenFinRVM --config="http://localhost:5555/app.json"

Replace the address with your manifest's. If your RVM is installed somewhere else, use that path instead. Once the app has started, it's installed and you can close it.

Links to the same manifest now launch the app as usual. The link has to point to the same address you installed with:

  • fin://localhost:5555/app.json matches http://localhost:5555/app.json.

  • fins:// matches https:// in the same way.

note

  • Uninstalling resets it. If you uninstall the app, repeat step 1 before using links again.

  • New manifest address, new install. Each manifest address is a separate app, so run step 1 for each one.

  • Testing the first-time install itself. This approach skips the link install, so it can't be used to test that flow. Use a development DOS for that.

Use a development DOS​

A development Desktop Owner Settings (DOS) file that turns the TAC requirement off restores the previous behavior on your machine. See Desktop Owner Settings for what each setting does.

note

Use this DOS on development and CI machines only, not on end-user desktops.

1. Create the DOS file​

Save this as dev-dos.json:

{
  "desktopSettings": {
    "enableFinsProtocolInstallation": true,
    "requireTacForFinsProtocolInstallation": false
  }
}

  • requireTacForFinsProtocolInstallation: false turns off the TAC requirement for new installs and unblocks fin:// and fins:// installs. This is a very important setting. You can set this value to true to simulate the new behavior before you upgrade to RVM version 20.0.1.4 or later.

  • enableFinsProtocolInstallation: true is already the default. It's included so the DOS cannot accidentally disable link installs altogether.

You can save the file anywhere. These steps use:

  • macOS: ~/OpenFin/dos/dev-dos.json

  • Windows: %LOCALAPPDATA%\OpenFin\dos\dev-dos.json

Already using a DOS?

The RVM reads only one DOS at a time. If your machine already points at one, add the two keys to that file's desktopSettings instead of replacing it.

2. Point the RVM at the file​

The RVM reads the DOS location from a per-user setting called DesktopOwnerSettings. Its value is a URL, and a local file works if you give it as a full file:// URL.

Before you change it, note the current value so you can restore it later (see Check the current value). If nothing comes back, there is no DOS set today.

Windows

The setting is the registry value HKCU\Software\OpenFin\RVM\Settings\DesktopOwnerSettings. Run this in Command Prompt or PowerShell, replacing <you> with your Windows user name:

reg add "HKCU\Software\OpenFin\RVM\Settings" /v DesktopOwnerSettings /t REG_SZ /d "file:///C:/Users/<you>/AppData/Local/OpenFin/dos/dev-dos.json" /f

  • Use forward slashes and three slashes after file:.

  • reg add creates the key if it doesn't exist yet.

  • /f overwrites an existing value without asking.

macOS

On macOS, the RVM keeps these settings in a plist file that mirrors the Windows registry path: ~/Library/Application Support/OpenFin/rvm/FileRegistry.plist, key Software > OpenFin > RVM > Settings > DesktopOwnerSettings. Run this in Terminal:

PLIST="$HOME/Library/Application Support/OpenFin/rvm/FileRegistry.plist"
DOS_URL="file://$HOME/OpenFin/dos/dev-dos.json"
PB=/usr/libexec/PlistBuddy

mkdir -p "$(dirname "$PLIST")"

# Create the parent entries if they don't exist yet
for KEY in :Software :Software:OpenFin :Software:OpenFin:RVM :Software:OpenFin:RVM:Settings; do
  $PB -c "Print $KEY" "$PLIST" >/dev/null 2>&1 || $PB -c "Add $KEY dict" "$PLIST"
done

# Set the DOS URL, or add it if it isn't there yet
$PB -c "Set :Software:OpenFin:RVM:Settings:DesktopOwnerSettings $DOS_URL" "$PLIST" 2>/dev/null \
  || $PB -c "Add :Software:OpenFin:RVM:Settings:DesktopOwnerSettings string $DOS_URL" "$PLIST"

  • If the path to your file contains spaces, write them as %20 in DOS_URL.

  • On a machine where the plist doesn't exist yet, PlistBuddy prints "File Doesn't Exist, Will Create". That's expected.

3. Restart the RVM​

The RVM reads the DOS location when it starts. Quit every OpenFin / HERE Core app and make sure no RVM process is still running:

  • Windows: Task Manager, OpenFinRVM.exe

  • macOS: Activity Monitor

Then launch again.

4. Check it​
Check the current value​

Windows:

reg query "HKCU\Software\OpenFin\RVM\Settings" /v DesktopOwnerSettings

macOS:

/usr/libexec/PlistBuddy -c "Print :Software:OpenFin:RVM:Settings:DesktopOwnerSettings" \
  "$HOME/Library/Application Support/OpenFin/rvm/FileRegistry.plist"

The value should be the file:// URL of your dev-dos.json.

Open a fin:// or fins:// link to a local manifest for an app that isn't installed yet. It should install and launch without the "Unable to open app" dialog.

5. Undo​

To go back to the DOS you had before, run the command from step 2 again with your old URL. If there was no DOS before, delete the value:

Windows:

reg delete "HKCU\Software\OpenFin\RVM\Settings" /v DesktopOwnerSettings /f

macOS:

/usr/libexec/PlistBuddy -c "Delete :Software:OpenFin:RVM:Settings:DesktopOwnerSettings" \
  "$HOME/Library/Application Support/OpenFin/rvm/FileRegistry.plist"

Restart the RVM afterwards (step 3).

CI machines​

Use the same steps in the CI job's setup script, before the first launch. Each command above runs without prompting. Two things to watch:

  • The DOS file must exist at the URL before the RVM starts.

  • If a test suite writes its own DOS, the suite's DOS replaces yours while it runs. Add the two desktopSettings keys to the suite's DOS as well.

Limitations​

  • Internet access is required to validate certificates; there is no option for fully offline mode.

  • fin:// (HTTP) installations cannot be TAC-authorized, because the manifest cannot be cryptographically verified over a plain HTTP connection. Migrate to fins:// over HTTPS for any application you want to remain installable while requireTacForFinsProtocolInstallation is true (the default).

Desktop Owner Settings​

The desktop owner controls fins:// link installation with two Desktop Owner Settings (see General settings):

  • desktopSettings.enableFinsProtocolInstallation (default true) — a kill switch that blocks all new installs via fin:// or fins:// links when set to false. Already-installed apps continue to launch normally.

  • desktopSettings.requireTacForFinsProtocolInstallation (default true in RVM 20.0.1.4 or later) — when true, new fins:// installs require an enableFinsProtocolInstallation TAC grant on the manifest. fin:// installs are blocked entirely while this setting is on, because a fin:// URL cannot be cryptographically verified over plain HTTP. A desktop owner can set it to false to allow both fin:// and fins:// installs without a TAC.

If your application does not carry an enableFinsProtocolInstallation TAC grant, end users see an "Unable to open app" dialog when they click a fins:// link that would install your app, unless their desktop owner has set requireTacForFinsProtocolInstallation to false.

Table of Contents