.. _azure_proxy_windows_vm:

==============================
Azure Proxy — Connector VM
==============================

The Application Proxy connector is a Windows service (``WAPCSvc`` and
``WAPCUpdaterSvc``) that maintains an outbound HTTPS tunnel to Azure and
forwards requests to the internal Peek server. The connector runs on a
Windows VM inside the corporate network — no inbound firewall rule is
required.

VM Requirements
===============

- Windows Server 2019 or newer, 2 vCPU, 4 GB RAM.
- Outbound HTTPS (443) to ``*.msappproxy.net``, ``login.microsoftonline.com``,
  ``login.windows.net``, ``*.servicebus.windows.net``. See Microsoft's
  published list for the full set.
- Internal network access to the Peek backend (HTTPS + WebSocket).
- Time synchronised (Windows Time service running).

Install the Connector
=====================

1. Download the installer on the VM::

       Invoke-WebRequest `
           -Uri "https://download.msappproxy.net/Subscription/<tenant-id>/Connector/DownloadConnectorInstaller" `
           -OutFile "$env:TEMP\AADApplicationProxyConnectorInstaller.exe"

   (Or download from the Entra portal: **Applications -> Enterprise
   applications -> Application proxy -> Download connector service**.)

2. Run the installer silently::

       Start-Process `
           -FilePath "$env:TEMP\AADApplicationProxyConnectorInstaller.exe" `
           -ArgumentList "/q","/norestart" `
           -Wait

3. Confirm the services exist (they will start disabled)::

       Get-Service -Name 'WAPCSvc','WAPCUpdaterSvc' |
           Format-Table Name,Status,StartType

Register the Connector
======================

Registration binds the connector to your tenant. The supplied
``RegisterConnector.ps1`` does not accept modern auth by default — use token
mode:

1. Acquire a connector-registration token (device code flow). Scope is
   ``https://proxy.cloudwebappproxy.net/registerapp/user_impersonation``.

2. Convert the access token to a ``SecureString``::

       $token = ConvertTo-SecureString "<access-token>" -AsPlainText -Force

3. Run the registration script (installed with the connector)::

       & "C:\Program Files\Microsoft Entra private network connector\RegisterConnector.ps1" `
           -AuthenticationMode Token `
           -Token $token `
           -TenantId "<tenant-id>" `
           -Modulepath "C:\Program Files\Microsoft Entra private network connector\Modules\"

   Successful registration writes the connector ID and subscription ID to
   ``Event Viewer -> Applications and Services Logs -> Microsoft -> AadApplicationProxy
   -> Connector -> Admin``.

4. Set both services to *Automatic* and start them::

       Set-Service -Name 'WAPCSvc','WAPCUpdaterSvc' -StartupType Automatic
       Start-Service -Name 'WAPCSvc','WAPCUpdaterSvc'

5. In the Entra portal, go to **Applications -> Enterprise applications ->
   Application proxy -> Connectors**. The new connector appears in the
   ``Default`` group. Create ``PeekConnectorGroup`` (**+ New connector
   group**) and move the connector into it.

Internal URL Hostname Workaround
================================

Application Proxy rejects raw IP addresses for the internal URL
(``InternalUrl_ContainsIP``). If the internal Peek server has no DNS
record, add a hosts file entry on the connector VM::

    Add-Content -Path "$env:SystemRoot\System32\drivers\etc\hosts" `
        -Value "10.46.2.126 azure-peek-nzor1pek6.synerty.com"

Then use the synthetic hostname (e.g.
``https://azure-peek-nzor1pek6.synerty.com``) as the Application Proxy
**Internal URL**.

If the Peek backend uses a certificate whose SAN does not include the
synthetic hostname, enable **Translate URLs in Headers -> Yes** on the
Application Proxy settings so the connector rewrites ``Host:`` to match.

Health Checks
=============

On the VM::

    # Service status
    Get-Service -Name 'WAPCSvc','WAPCUpdaterSvc'

    # Outbound connectivity
    Test-NetConnection -ComputerName "<tenant>.msappproxy.net" -Port 443

    # Recent registration / health events
    Get-WinEvent -LogName 'Microsoft-AadApplicationProxy-Connector/Admin' `
        -MaxEvents 20 | Format-List TimeCreated,Id,Message

From Entra portal:

- **Applications -> Enterprise applications -> Application proxy ->
  Connectors** — the connector must show *Active*.
- Assign the connector group to each Application Proxy app
  (:ref:`azure_proxy_setup`). An application with no connector returns
  502 from the external URL.