Trusting the agent downloads on Windows

This page is for the person standing at a print room PC who has downloaded idportal-agent.exe from the portal’s Settings → Downloads page and cannot get Windows to accept it.

The executable is currently unsigned — there is no code-signing certificate on them yet — so Windows treats them as software from an unknown publisher. That is a known state, not a fault in your download. It means you, rather than a signature, are vouching for the file, which is why the first step below is checking that the file really is the one the portal served.

Windows raises up to three separate gates, and clearing one does not clear the next. Work through them in order. Every gate has a legitimate “yes, I meant to do this” path; none of them requires turning protection off.

Step 0 — verify the file before you trust it

The Settings → Downloads page shows the expected SHA-256 next to each download (the download response also carries it in an X-Agent-SHA256 header). Compare:

(Get-FileHash .\idportal-agent.exe -Algorithm SHA256).Hash.ToLower()

• Hashes match → the file is byte-for-byte what the server holds. Every unblock step below is now justified.
• Hashes differ → the download is truncated or altered. Delete it and download again. Do not unblock a file that fails this check — the gates exist for exactly this case.

A truncated download is far more common than a tampered one — an AV proxy or a dropped connection cut it short — but the response is the same either way.

Gate 1 — the browser or AV blocks the download itself

The print agent is an ~84 MB unsigned executable, which is precisely the shape of file Chrome Safe Browsing, SmartScreen and AV proxies drop. The failure is often silent, or reported as “failed” with no reason.

1. Open chrome://downloads (or the Edge equivalent). A blocked entry can usually be recovered with Keep → Keep anyway without downloading again.
2. Check Windows Security → Virus & threat protection → Protection history for a blocked or quarantined item and choose Allow / Restore.
3. Try another browser. If Edge or Firefox succeeds where Chrome failed, it was browser policy — you have your file, move on.
4. If every browser fails the same way, copy the file to the machine by another route (USB stick, network share, scp). There is nothing special about the packaged executable; it does not care how it arrived.

To tell a local block apart from a server problem: if the downloads page shows a version, size and checksum at all, the file is present and readable on the server, and the problem is between there and this PC.

Gate 2 — SmartScreen at first launch (Mark of the Web)

Every file that arrives via a browser is tagged with the Mark of the Web (a Zone.Identifier stream on the file). SmartScreen sees that mark on an unsigned exe and shows “Windows protected your PC” the first time it runs.

Clear it either way — they are equivalent:

• Before first run (cleanest — the warning never appears):

  Unblock-File .\idportal-agent.exe

  The same thing is available in Explorer: right-click the exe → Properties → tick Unblock → OK.

• At the warning: click More info → Run anyway.

This is per-file and permanent: once cleared, that copy never warns again. A newly downloaded copy — including every future update of the agent — carries a fresh mark and needs the same one-time clear. A file that arrived by USB stick or scp usually has no mark at all, which is why the copy-it-by- hand route in Gate 1 often skips this gate entirely.

Gate 3 — Defender or third-party AV quarantines the file

This one can fire at download time, at first launch, or days later after a definitions update — an agent that ran fine on Monday can be quarantined on Thursday. If an installed agent vanishes or stops starting, look here first.

Windows Defender:

1. Windows Security → Virus & threat protection → Protection history.
2. Find the entry naming the agent exe, expand it, and choose Actions → Restore, then Actions → Allow on device so the same detection does not repeat.

Third-party AV (Sophos, Trend, CrowdStrike, …): the console is usually managed centrally, so this becomes an IT request. Give them the file’s SHA-256 and version from the portal’s downloads page — an allow-by-hash is the narrowest possible exception and most products support it.

Keep the exception narrow. Allow the specific file (best: by hash), or at most the exact path such as C:\idportal-agent\idportal-agent.exe. Do not exclude whole folders like C:\ or Downloads from scanning, and do not turn off real-time protection — a scoped allow does everything a broad exclusion does without blinding the machine.

Managed machines: “This app has been blocked by your system administrator”

That message is not SmartScreen — it is application control (AppLocker or WDAC policy) and no local click-through exists. Only IT can clear it, by adding the executable’s hash to policy (a per-release step, since the hash changes with each version) or a path rule for the install location. Point them at the section below.

For the IT department

What these programs are and why they are safe to allow:

• idportal-agent.exe drives the card printer. It is downloaded by signed-in operators from the organisation’s own portal (Settings → Downloads), not from a public site.
• Outbound HTTPS only — to the portal (https://app.cardoffice.nz unless self-hosted) and its storage endpoint for short-lived presigned photo URLs. No inbound port, no VPN, no firewall exception.
• Integrity is verifiable: the portal publishes each build’s SHA-256, size and version on the download page and in the X-Agent-SHA256 response header, and every build is traceable to the exact source commit via its manifest.
• It is unsigned today. Code signing is on the roadmap; until then, allow-by-hash per release (or a path rule) is the intended mechanism, and the published SHA-256 is stable for a given release so the exception can be staged before rollout.
• The credential the agent holds is machine-scoped: its token lives in the service account’s profile.

The short version

Print agent (details: Print agent setup):

mkdir C:\idportal-agent; cd C:\idportal-agent
# download idportal-agent.exe from Settings → Downloads
(Get-FileHash .\idportal-agent.exe -Algorithm SHA256).Hash.ToLower()   # compare with the portal
Unblock-File .\idportal-agent.exe
.\idportal-agent.exe enrol

The portal address for enrolment is https://app.cardoffice.nz.

What not to do

• Do not disable SmartScreen machine-wide. The per-file unblock is enough, and the machine usually belongs to a customer whose policy is not yours to change.
• Do not turn off Defender real-time protection, even “just for the install”. A scoped allow survives; a global toggle gets noticed by IT and reverted, taking the agent with it.
• Do not add broad folder exclusions. Allow the file, not the drive.
• Do not skip the hash check because the gates are annoying. The check is the reason the unblocks are safe.