Pairing this instance

Every fresh instance — Azure Deployment or Manual Deployment — arrives at the same screen: Pair this instance. There is no Entra app registration yet, so there is nobody to sign in as until you make a choice here.

Pairing screen showing the download-and-run PowerShell instructions and the Enable Demo Mode fallback

Choose: Demo Mode or pair with your home tenant

Two options from this screen:

  • Enable Demo Mode — explore the console with fictional data. No real tenant, no script to run, nothing to configure. See Demo Mode for what that means and how to get back out of it.
  • Run the deployment script — pairs this instance with your MSP’s real home tenant for production use. This is the path the rest of this page documents.

What pairing does

scripts/Deploy-PatchPilot.ps1 is the canonical, only supported way to create the Entra app registration for a fresh instance:

  1. Creates the Entra app registration in your MSP’s home tenant.
  2. Configures the read-only Graph/Defender permissions and grants admin consent for them.
  3. Sets the Application ID URI (api://<client-id>) and adds the access_as_user scope, so the app can complete the On-Behalf-Of token exchange with no manual portal clicks.
  4. Pairs directly with this running instance using a single-use pairing token baked into the downloaded script — the instance restarts itself automatically the moment the script finishes, now holding real credentials.

How the instance authenticates

The downloaded script carries a certificate that this instance generated for the pairing. The script registers only the public certificate on the app registration. The private key never leaves the instance: it is stored in the database, encrypted with TOKEN_ENCRYPTION_KEY. No client secret is created, sent over the network, or written to disk.

The certificate is valid for one year. Setup → App Registration shows its expiry date and warns 30 days before it runs out. To renew it, download a fresh script from that page and run it again. The script can then remove the older PatchPilot certificates and client secrets from the app.

To pair with a client secret instead (the older behavior), run the script with -CredentialType Secret. Running the script from a git clone, rather than as a download from your instance, always uses a client secret.

An instance on an Azure VM detects the VM’s managed identity, and its script pairs with that by default instead, so it stores no credential at all. That needs the VM’s subscription to be in your MSP tenant; otherwise the script falls back to the certificate. Run it with -CredentialType Certificate to choose the certificate yourself. See Deploying to an Azure VM.

Steps

  1. Open the running instance in a browser. If it hasn’t been paired yet, you’ll land on this screen automatically instead of a sign-in redirect.
  2. Click Download PowerShell Script. The download is personalized with this instance’s pairing token — don’t share it or reuse it against a different instance.
  3. Run the script from PowerShell, on any machine, signed in as a Global Administrator of the MSP’s own (home) tenant.
  4. Wait — the page polls automatically and moves on by itself once pairing completes. No reload needed.

The pairing token is single-use and time-limited; if it expires before you run the script, reload the page to generate a fresh download.

Why Azure Cloud Shell isn’t offered here

Earlier versions of this screen offered Azure Cloud Shell as a no-local- PowerShell alternative. It’s no longer offered: tenants with Security Defaults or Conditional Access policies enabled — the common case today — block Cloud Shell’s sign-in from satisfying those policies, so it stopped completing the pairing script reliably. Running the downloaded script from local PowerShell is the one supported path.

Next step

Once pairing completes, sign in for real and continue to the Navigating PatchPilot365 section, or jump straight to Onboard your first tenant.