> For the complete documentation index, see [llms.txt](https://t1t.gitbook.io/t1c-js-guide-v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t1t.gitbook.io/t1c-js-guide-v3/intune-installation.md). # Intune Installation From v3.8.10 (admin installer) ## Trust1Connector — Intune / MDM Deployment Guide > **Audience:** DevOps engineers managing Microsoft Intune or similar MDM platforms at customer sites.\ > **Scope:** Windows deployment of the Trust1Connector (T1C) MSI package — architecture overview, certificate trust chain, installation, uninstallation, and troubleshooting. *** ### Package Variants — Default vs Standalone Two MSI flavours are published for every release: | Variant | MSI name pattern | Contains `t1c-reg.exe` | Intended environment | | -------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------- | | **Default** | `Trust1Connector-x64-.msi` | **Yes** | Shared / multi-user — Citrix, VDI, Terminal Server, RDS | | **Standalone** | `Trust1Connector-standalone-x64-.msi` | **No** | Single dedicated device (workstation, kiosk) | The only functional difference is the presence of `t1c-reg.exe` (Device Registry daemon). All other binaries, the Root CA flow, and the Intune deployment steps are identical. Sections below note where behaviour differs between variants. *** ### Table of Contents 1. Architecture Overview 2. Process Model 3. Filesystem Layout 4. Root CA — What It Is and Why It Matters 5. Installation Sequence 6. Intune Deployment Requirements 7. Verifying a Successful Installation 8. Uninstallation 9. Upgrade (In-Place) 10. Fallback — Manual Root CA Installation 11. Troubleshooting *** ### 1. Architecture Overview The Trust1Connector is a **per-machine Windows service** that exposes a local HTTPS API on `https://localhost:51983`. Browser extensions and web applications call this API to access smart cards and cryptographic hardware attached to the device. ``` Browser / Web App │ HTTPS (localhost:51983) ▼ t1c-api.exe ← main REST API (Rust) │ spawns ▼ t1c-sandbox.exe ← sandboxed process for card reader I/O t1c-reg.exe ← device registry daemon (default package only — not present in standalone) ``` The connector listens only on `localhost` — no inbound network traffic is involved.\ TLS on `localhost` is provided by a **self-signed Root CA generated locally per device**. That CA must be trusted at the **machine level** before any browser will accept the connection. *** ### 2. Process Model | Executable | Role | Started by | | -------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `t1c-launch.exe` | Watchdog / launcher — reads config, starts the API | Windows `Run` registry key (login) or Intune | | `t1c-api.exe` | Main REST API. On first run: generates Root CA + TLS cert, installs CA to Windows trust store | `t1c-launch.exe` | | `t1c-sandbox.exe` | Isolated card-reader process (lower privilege surface) | `t1c-api.exe` | | `t1c-reg.exe` *(optional)* | Device Registry daemon — registers device with the Distribution Service, syncs state across sessions | `t1c-api.exe` — **default package only**; not present in the standalone variant | > **Note:** For other client packages (`t1c-api.exe`, `t1c-sandbox.exe`, etc.) the binary names differ but the role model is identical. The API runs under the **SYSTEM** account (inherited from the MSI install context), which gives it the privileges needed to install the Root CA into the machine-wide trust store without prompting the end user. *** ### 3. Filesystem Layout ``` C:\Program Files\Trust1Connector\ ← managed by MSI (removed on uninstall) t1c-launch.exe t1c-api.exe t1c-sandbox.exe t1c-reg.exe ← device registry daemon (default package only; absent in standalone) t1cds.pub ← Directory Service public key t1c.cer / t1c.pem ← T1T wildcard cert (DS communication) install-ca.bat ← admin fallback script (see §10) C:\Users\\AppData\Local\Trust1Connector\ ← runtime data (removed on uninstall) device.priv / device.pub / device_der.* ← device identity keys ds-txs.json ← Directory Service sync state *.log ← application logs C:\Users\\AppData\Local\T1CConnector\ ← shared cert store (all T1C packages) t1c-ca.pem ← Root CA certificate (PEM) t1c-ca-key.pem ← Root CA private key t1c-tls.pem ← localhost TLS leaf certificate t1c-tls-key.pem ← localhost TLS private key ``` > The per-package `LocalAppData` folder is **not** managed by Windows Installer. The MSI explicitly deletes it on uninstall via a custom action. On **upgrade** it is intentionally preserved so device keys and sync state survive. The **shared** `T1CConnector` folder is **never** deleted by any single package uninstaller — it is preserved so other installed packages (\*Connector, etc.) can continue to reuse the same Root CA. *** ### 4. Root CA — What It Is and Why It Matters #### Why a local Root CA is needed The connector serves its REST API over HTTPS on `localhost`. Modern browsers (Chrome, Edge, Firefox) require a valid certificate chain for any HTTPS connection — even to localhost. A self-signed leaf certificate is rejected by default. The solution is a locally-generated **Root CA** that is trusted at the machine level, which then signs the `localhost` TLS certificate. #### How the Root CA is generated On **first startup** after installation the API (`t1c-api.exe`) automatically: 1. Generates a **4096-bit RSA key pair** for the Root CA. 2. Issues a self-signed CA certificate with: * **Common Name:** `T1C Local Root CA` * **Validity:** 10 years (3 650 days) * **Key Usage:** `keyCertSign`, `cRLSign` (CA only — cannot be used as a leaf) * **Basic Constraints:** `CA:true, critical` * **Subject Key Identifier** present (required for Chrome chain validation) 3. Saves all four cert files (`t1c-ca.pem`, `t1c-ca-key.pem`, `t1c-tls.pem`, `t1c-tls-key.pem`) to the **shared** folder `%LocalAppData%\T1CConnector\`. If another package has already generated certs there, the existing valid cert is reused instead of generating a conflicting Root CA. 4. Issues a **localhost TLS leaf certificate** signed by the CA. 5. Installs the Root CA into the **Windows machine trust store** (`LocalMachine\Root`) using `certutil -addstore Root`. #### Why machine-level trust is required for enterprise deployment | Trust store | Who sees it | Elevation needed | Dialog for user | | ------------------- | ----------------------- | ------------------ | ------------------------ | | `LocalMachine\Root` | All users on the device | Yes (SYSTEM/admin) | **None** | | `CurrentUser\Root` | Only the logged-in user | No | One-time dialog per user | For enterprise / Intune deployment the cert **must** be in `LocalMachine\Root`: * No per-user prompts (zero end-user interaction). * Works for all users on shared or multi-user devices. * Survives user profile resets. * Compatible with browser enterprise policies that block `CurrentUser\Root` modifications. Because the connector runs as **SYSTEM** when launched by the MSI, `certutil -addstore Root` (targeting `LocalMachine\Root`) succeeds without any UAC prompt. If for any reason the machine-level install fails, the API falls back to `CurrentUser\Root` (acceptable for single-user devices; see §10 for manual remediation). #### Thumbprint verification Before installing, the API computes the **SHA-256 thumbprint** of the CA file on disk and queries both `LocalMachine\Root` and `CurrentUser\Root` using PowerShell: ```powershell Get-ChildItem Cert:\LocalMachine\Root, Cert:\CurrentUser\Root | Where-Object { $_.GetCertHashString('SHA256') -eq '' } ``` If the exact certificate is already present the install step is skipped — no duplicate entries are created. If a stale entry exists with the same CN but a different thumbprint (from a previous installation), it is removed before the new one is added. *** ### 5. Installation Sequence The following diagram shows the full sequence from Intune deployment to a browser-trusted HTTPS connection. ```mermaid sequenceDiagram participant Intune as Intune / MDM participant MSI as MSI Engine (SYSTEM) participant FS as Filesystem participant API as t1c-api.exe (SYSTEM) participant Store as LocalMachine\Root participant Browser as Browser (Chrome/Edge) Intune->>MSI: msiexec /i Trust1Connector.msi /quiet note over MSI: Scope=perMachine → runs as SYSTEM
No UAC dialog for end user MSI->>MSI: killApi — taskkill /F all T1C processes note over MSI: Releases file locks before file operations MSI->>FS: Install files to Program Files\Trust1Connector\ MSI->>FS: Write Run registry key (auto-start on login) MSI->>API: Start t1c-launch.exe → t1c-api.exe (asyncNoWait) note over API: First run detected — no t1c-ca.pem in shared folder API->>FS: Generate RSA-4096 Root CA key pair API->>FS: Write cert files to %LocalAppData%\T1CConnector\ (shared) API->>FS: Generate localhost TLS cert signed by Root CA API->>Store: certutil -addstore Root t1c-ca.pem note over Store: No dialog — running as SYSTEM API->>API: Start HTTPS listener on localhost:51983 MSI->>Store: (belt-and-suspenders) certutil -addstore Root
via MSI commit action after InstallFinalize Browser->>API: GET https://localhost:51983/v3/... Store-->>Browser: Root CA trusted at machine level Browser-->>API: TLS handshake OK API-->>Browser: JSON response ``` #### Key points for Intune * The MSI must be deployed in **system context** (not user context) — see §6. * The entire flow is **silent**: no dialogs, no user interaction. * The Root CA install happens **twice** (API at startup + MSI commit action) for reliability. *** ### 6. Intune Deployment Requirements #### Package type Deploy as a **Line-of-Business (LOB) app** using the `.msi` file directly, or wrap it with the [Win32 Content Prep Tool](https://github.com/Microsoft/Microsoft-Win32-Content-Prep-Tool) for a `.intunewin` package (recommended for better reporting). #### Installation context — critical | Setting | Required value | Reason | | --------------------------- | -------------------- | ----------------------------------------------------------------------- | | **Install behavior** | `System` | Must run as SYSTEM to write to `LocalMachine\Root` without a UAC dialog | | **Device restart behavior** | `No specific action` | No reboot required | | **Return codes** | `0` = success | Standard MSI exit code | > If you deploy in **User** context the Root CA will land in `CurrentUser\Root` for the Intune service account (not the end user), which no browser will read. **Always use System context.** #### Install command ``` msiexec /i Trust1Connector-x64-.msi /quiet /norestart ``` For the standalone variant: ``` msiexec /i Trust1Connector-standalone-x64-.msi /quiet /norestart ``` #### Uninstall command ``` msiexec /x {3D6B46ED-C178-4ED9-8F0E-FFCC13C6BE7D} /quiet /norestart ``` > The GUID above is for `Trust1Connector`. Other client packages have different UpgradeCodes — confirm from the package metadata. #### Detection rules Use **one** of the following: **Option A — Registry (recommended)** ``` HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{} Key: DisplayName Value: Trust1Connector ``` **Option B — File** ``` Path: C:\Program Files\Trust1Connector\ File: t1c-api.exe ``` **Option C — Certificate (confirms end-to-end success)** Run as a custom detection script: ```powershell $cert = Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*T1C Local Root CA*" } if ($cert) { Write-Output "Installed"; exit 0 } exit 1 ``` #### Applicability rules | Rule | Value | | ------------ | ---------------------------------------- | | OS | Windows 10 1903 or later / Windows 11 | | Architecture | x64 (use x86 package only for 32-bit OS) | | Minimum disk | \~150 MB | #### Group Policy / Intune policy dependencies If your tenant enforces **"Prevent users from installing root certificates"** (`HKLM\SOFTWARE\Policies\Microsoft\SystemCertificates\Root\ProtectedRoots` = `1`), this blocks `certutil -addstore Root` even for SYSTEM. You will need to either: * Exempt the device group from that policy, **or** * Pre-deploy the Root CA via Intune's **Trusted Certificate** profile (see §10). *** ### 7. Verifying a Successful Installation Run these commands on the device (or via Intune Remediations / PowerShell script): ```powershell # 1. Root CA in machine trust store certutil -store Root "T1C Local Root CA" # Expected: certificate details printed; exit 0 # 2. API process running Get-Process t1c-api -ErrorAction SilentlyContinue # Expected: process listed # 3. HTTPS endpoint responding try { $r = Invoke-WebRequest https://localhost:51983/v3/status -UseBasicParsing Write-Output "API OK: $($r.StatusCode)" } catch { Write-Output "API not reachable: $_" } # 4. CA file present on disk (shared cert folder) Test-Path "$env:LOCALAPPDATA\T1CConnector\t1c-ca.pem" # 5. Registry daemon running (default package only — skip for standalone) Get-Process t1c-reg -ErrorAction SilentlyContinue ``` All four checks (1–4) should succeed for both variants. Check 5 applies only to the default (non-standalone) package. If check 1 fails but checks 2 and 4 pass, run the manual fallback in §10. *** ### 8. Uninstallation #### What the uninstaller does (in order) ``` 1. killApi — taskkill /F on t1c-launch.exe, t1c-api.exe, t1c-sandbox.exe + t1c-reg.exe (if present — default package only) + 2 s pause for OS to release file handles 2. CleanLocalAppData — rd /s /q %LocalAppData%\Trust1Connector\ (device keys, ds-txs.json, logs — package-specific files) NOTE: %LocalAppData%\T1CConnector\ is NOT deleted (shared cert store) 3. CA_RemoveRootCA — certutil -delstore Root "T1C Local Root CA" 4. RemoveFiles — removes C:\Program Files\Trust1Connector\ 5. Registry — removes Run key and Uninstall entry ``` After uninstall the device is in a completely clean state — no orphaned processes, no leftover certificates, no leftover files. #### Via Intune Set the uninstall command above in the app's **Uninstall command** field. Assign to a device group with **Uninstall** intent. #### Manual uninstall ``` msiexec /x Trust1Connector-x64-.msi /quiet /norestart ``` or use **Settings → Apps → Installed Apps → Trust1Connector → Uninstall**. #### What is NOT removed * The Windows **Startup** `Run` key is removed by the MSI component. * The `%LocalAppData%\T1CConnector\` shared cert folder — preserved so other packages on the same device are not broken. * Firefox NSS stores (if Mozilla Firefox was used) — the Firefox certutil removes the CA from Firefox profiles automatically; if it fails, Firefox will simply show a certificate warning again on next use. *** ### 9. Upgrade (In-Place) The MSI uses `MajorUpgrade` — installing a newer version over an existing one is fully supported and handled automatically: ``` 1. killApi — kills all running T1C processes (same as uninstall step 1) 2. Old version removed (file replacement only — LocalAppData is NOT deleted) 3. New version files installed 4. Service restarted 5. API finds existing t1c-ca.pem in shared folder → reuses it (no cert regeneration, no re-trust needed) ``` Existing CA keys and device identity keys survive an upgrade. The certificate in `LocalMachine\Root` remains valid — no re-deployment of trust is required. Deploy the new MSI via Intune exactly as the initial install. The product UpgradeCode is the same across versions, so Intune will detect and replace the old version. > **Switching variants on upgrade:** If you move a device from the default package to the standalone package (or vice versa), uninstall the current version first. Switching in-place is not supported because the two variants have different Product Codes. *** ### 10. Fallback — Manual Root CA Installation If the automatic install fails (e.g., policy blocks `certutil`, or the API started in non-elevated context), a convenience script is bundled with the installer: ``` C:\Program Files\Trust1Connector\install-ca.bat ``` Run it from an **elevated command prompt** (or deploy via Intune PowerShell with SYSTEM context): ```bat :: Removes any stale copy and re-installs the Root CA from the shared cert folder C:\Program Files\Trust1Connector\install-ca.bat ``` Alternatively, use the raw `certutil` command: ```bat :: Remove stale entry (ignore error if not present) certutil -delstore Root "T1C Local Root CA" >nul 2>&1 :: Install from the shared cert folder (written by the API on first run) certutil -addstore Root "%LocalAppData%\T1CConnector\t1c-ca.pem" ``` Or deploy via **Intune → Trusted Certificate profile**: 1. Export the CA cert from the device: copy `%LocalAppData%\T1CConnector\t1c-ca.pem` → rename to `.cer`. 2. Create a **Trusted Certificate** configuration profile in Intune. 3. Upload the `.cer` file, set destination store to **Computer certificate store — Root**. 4. Assign to the target device group. > **Note:** If you use the Intune Trusted Certificate profile, each device will have a **different** CA certificate because the key pair is generated per-device. You cannot pre-generate a single CA and distribute it — the private key must stay on the device that owns it. *** ### 11. Troubleshooting | Symptom | Likely cause | Fix | | ------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Browser shows `ERR_CERT_AUTHORITY_INVALID` | Root CA not in `LocalMachine\Root` | Run §10 fallback or check §7 verification | | Browser shows `ERR_CERT_AUTHORITY_INVALID` after re-install | Stale cert in store with old thumbprint | `certutil -delstore Root "T1C Local Root CA"` then reinstall | | `certutil -store Root "T1C Local Root CA"` returns NOT\_FOUND | CA installed to `CurrentUser\Root` instead (non-elevated run) | Re-install in System context, or use §10 fallback | | API not starting after install | Startup registry key present but process not launched | Log off and back on, or trigger via `t1c-launch.exe --env prod --silent` | | `t1c-reg.exe` not running (default package) | Process crashed or not started | Check `%LocalAppData%\Trust1Connector\.log`; restart via `t1c-launch.exe` | | `t1c-reg.exe` missing from Program Files | Standalone package deployed instead of default | Re-deploy with the default (non-standalone) MSI if DS registration is required | | Uninstall leaves files in `Program Files` | Processes were still running, locking files | Run `taskkill /F /IM t1c-api.exe /T` before uninstall, then retry | | Uninstall leaves `LocalAppData` folder | Old MSI package (pre-fix) | Delete manually: `rd /s /q "%LocalAppData%\Trust1Connector"` | | `signtool` error during package build | Windows SDK not on PATH | Open a VS Developer Command Prompt, or update to latest `package.bat` (auto-detects SDK) | | Firefox still shows a warning | Firefox NSS certutil not found | Reinstall Firefox; the connector automatically registers with NSS on next start | #### Log file location ``` %LocalAppData%\Trust1Connector\.log ``` The log contains timestamped entries for every cert operation with full `certutil` output, making it straightforward to diagnose trust store issues remotely via Intune's **Collect diagnostics** feature. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://t1t.gitbook.io/t1c-js-guide-v3/intune-installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.