Calibrant Relay Setup

The Calibrant Relay is a small service you deploy in your own Azure subscription. It handles two things for you:

• Tenant Healthcheck — run M365 configuration audits using PowerShell against your tenant via Managed Identity
• Security Baseline — M365 Security Baseline, CISA SCuBA, and ACSC Essential Eight assessments with automated M365 configuration checks

The relay is a Windows VM running Windows Server 2025 Core (no desktop GUI, minimal attack surface). It uses a Managed Identity for all M365 authentication — no passwords, no service account credentials, no domain join required. The VM makes outbound-only HTTPS connections to Calibrant and Microsoft APIs. No inbound ports are open.

Most deployment time is spent waiting for Azure to provision the VM and install software. Timing varies by Azure region and service availability.

Step 1 — Install the Azure CLI

If you already have the Azure CLI installed, skip to Step 2.

# Windows (PowerShell or Command Prompt)
winget install Microsoft.AzureCLI

# Mac
brew install azure-cli

# After installing, sign in:
az login

Verify you're pointed at the right subscription:

az account show --query "{name:name, id:id}" -o table

# Switch subscriptions if needed:
az account set --subscription "Your Subscription Name"

Step 2 — Create a relay in Calibrant

Go to Connections and scroll to the Calibrant Relay section. Click Add Relay, give it a name (e.g. "Production Relay"), and click Create Relay.

You'll see a Relay API Key — copy it now.

Step 3 — Create a resource group

az group create --name calibrant-relay-rg --location eastus

Pick the Azure region closest to your users — eastus, westeurope,australiaeast, etc.

Step 4 — Deploy the relay VM

Download the Bicep template and run the deployment command. Replace cal_YourKeyHere with the API key you copied in Step 2, and set a secure password (you'll almost never need it — it's just required by Azure for the VM admin account).

# Download the Bicep template
curl -O https://www.calibrant.ai/relay/main.bicep

# Deploy (Azure provisioning time varies)
az deployment group create \
  --resource-group calibrant-relay-rg \
  --template-file main.bicep \
  --parameters calibrantApiKey='cal_YourKeyHere' adminPassword='YourSecurePassword123!'

Optional: verify the template before you deploy it. The template names the exact provisioning script it will run, by SHA-256, and the VM refuses to execute anything else — if the downloaded script does not match, provisioning aborts before it runs. You can check that chain yourself:

# The digest the template pins
grep bootstrapSha256 main.bicep

# The script the template points at, and its actual digest
grep bootstrapUrl main.bicep
curl -sO https://www.calibrant.ai/relay/bootstrap-<sha>.ps1
shasum -a 256 bootstrap-<sha>.ps1   # must equal both the filename and the pin

The script URL is content-addressed — the digest is in the filename — so a template you keep and reuse always resolves to the same reviewed script, even after we publish newer versions. Note this verifies internal consistency: that the script the VM runs is the one the template names. It is not independent third-party attestation, since both the template and the script are served by us.

az deployment group create \
  --resource-group calibrant-relay-rg \
  --template-file main.bicep \
  --parameters calibrantApiKey='cal_YourKeyHere' adminPassword='YourSecurePassword123!' \
               enableNatGateway=true

# Then read the IP you now own:
az network public-ip show --resource-group calibrant-relay-rg \
  --name calibrant-relay-nat-pip --query ipAddress -o tsv

// Calibrant Relay — Windows VM deployment with Managed Identity
// No domain join required. No inbound ports. Outbound HTTPS only.
// Full source: https://github.com/fusedad/calibrant/blob/main/relay/deploy/main.bicep

@secure()
param calibrantApiKey string
@secure()
@minLength(12)
param adminPassword string
param calibrantApiUrl string = 'https://www.calibrant.ai'
param location string = resourceGroup().location
param pollIntervalMs string = '600000'
param adminUsername string = 'calibrant-admin'
param vmSize string = 'Standard_B2ls_v2'
param relayZipUrl string = 'https://www.calibrant.ai/relay/calibrant-relay.zip'

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2024-11-30' = {
  name: 'calibrant-relay-identity'
  location: location
}
// ... (NSG, VNet, NIC, VM, Extensions)
// Full template at the URL above

Step 5 — Grant M365 permissions to the Managed Identity

The relay's Managed Identity needs permission to read your M365 tenant configuration. This is a one-time setup. The script grants 18 Microsoft Graph application roles plus Exchange.ManageAsApp. The Graph roles are read-only; the Exchange grant enables app authentication and its authority is limited by the one Entra ID directory role — Global Reader, also read-only. One optional registration is not read-only. Read the next callout before you run it.

Download and run the permission grant script:

↓ Download grant-healthcheck-permissions.ps1

# Windows
Get-FileHash .\grant-healthcheck-permissions.ps1 -Algorithm SHA256

# Mac / Linux
shasum -a 256 grant-healthcheck-permissions.ps1

The digest is generated from the published file at build time, so it always matches what this site serves. It catches a corrupted or modified download — it is not independent attestation, since the digest and the file come from the same origin. The script is short and readable; for a Global Administrator session, reading it is the strongest check available.

# In a pwsh 7 terminal on your local machine (not the VM):
./grant-healthcheck-permissions.ps1

The script will open a browser for sign-in (requires a Global Administrator account), grant all necessary permissions, and print a validation report showing every permission as [OK].

curl -O https://www.calibrant.ai/relay/grants.bicep
curl -o bicepconfig.json https://www.calibrant.ai/relay/grants-bicepconfig.json

az deployment group create \
  --resource-group calibrant-relay-rg \
  --template-file grants.bicep \
  --parameters managedIdentityPrincipalId=<value from Step 4 output>

Step 6 — Confirm the Power Platform decision (optional checks)

There is nothing new to grant here. The grant script in Step 5 either created the Power Platform management-application registration or skipped it, and this step is where you confirm which happened matches what you intended in the Step 5 callout.

Declining costs one baseline control (CAL-DAT-002) and four CISA SCuBA controls; those checks report not evaluated and nothing else changes. The measurements behind this trade are in Why Some Checks Are Manual.

Step 7 — Enable Fabric / Power BI checks (optional)

Skip this and the Fabric checks report not evaluated. Enabling it unlocks twelve baseline controls and eight CISA SCuBA controls. Unlike the rest of setup, this cannot be scripted — the Fabric admin portal has no API for these settings, so it is a few clicks by hand.

Fabric tenant settings checks (the Fabric & Power BI baseline area) use the Fabric admin REST API (https://api.fabric.microsoft.com/v1/admin/tenantsettings) via Managed Identity. No Entra ID directory role is required — access comes from the security group and portal settings below. You must configure these in the Fabric admin portal.

Step 1: Create a security group in Microsoft Entra ID (e.g. FabricApiAccess) and add the calibrant-relay-identity service principal as a member.

Step 2: In the Fabric admin portal, enable these two settings (they are in different sections of Tenant settings):

1. Tenant settings > Developer settings > Service principals can call Fabric public APIs — enable, select "Specific security groups", and add your FabricApiAccess group
2. Tenant settings > Admin API settings > Service principals can access read-only admin APIs — enable, select "Specific security groups", and add the same group

Enable only those two. Leave the neighbouring service-principal settings alone.

Settings take up to 15 minutes to propagate. Fabric checks will show as "Not Evaluated" until the settings take effect.

Step 8 — Verify the relay is connected

Go to Connections in Calibrant. Within 30 seconds of the bootstrap completing, the relay should show as Online with a green indicator.

If it's still showing offline after a minute, check the relay logs:

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\relay.log -Tail 30"

You're done

The relay is running and scanning. Everything below is there when you need it — nothing further is required to use the product.

• Relay reference — exact permissions granted and why, logs, environment variables, pre-installed tools, and who can reach your tenant through the relay
• Relay updates — how new versions are approved and installed
• Removing the relay — full offboarding checklist

Troubleshooting

• Relay shows Offline after deployment — the bootstrap script may still be running. Azure can take several minutes to install all software. Check progress in the Azure portal: go to your VM → Extensions + applications → CustomScriptExtension.
• Bootstrap failed — check the extension logs in the portal or run:

  az vm run-command invoke --name calibrant-relay-vm --resource-group calibrant-relay-rg --command-id RunPowerShellScript --scripts "Get-Content 'C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\1.10\CustomScriptHandler.log' -Tail 50"

• PowerShell cmdlets return Access Denied during healthcheck — the Managed Identity permissions may not have propagated yet. Wait 10 minutes after running the grant script and try again.
• Service starts but shows no agents in logs — check that the API key is correct. Re-run the deployment with the correct key, or update it via Run Command.
  AppEnvironmentExtra replaces the whole extra block rather than merging into it, so anything you do not pass back is dropped from it. The relay keeps working regardless, because CALIBRANT_API_URL, AZURE_CLIENT_ID, and POLL_INTERVAL_MS are also set at machine scope and the service inherits them. The API key is the one value that lives only here — so passing every variable back is the habit to keep.

  First get the Managed Identity client ID:

  az identity show --name calibrant-relay-identity --resource-group calibrant-relay-rg --query clientId -o tsv

  Then set the whole block at once:

  az vm run-command invoke --name calibrant-relay-vm --resource-group calibrant-relay-rg --command-id RunPowerShellScript --scripts "nssm set CalibrantRelay AppEnvironmentExtra 'CALIBRANT_API_URL=https://www.calibrant.ai' 'CALIBRANT_API_KEY=cal_NewKey' 'AZURE_CLIENT_ID=<client-id>' 'POLL_INTERVAL_MS=600000'; nssm set CalibrantRelayUpdater AppEnvironmentExtra 'CALIBRANT_API_URL=https://www.calibrant.ai' 'CALIBRANT_API_KEY=cal_NewKey'; Restart-Service CalibrantRelay -Force; Restart-Service CalibrantRelayUpdater -Force"

  The key lives only in the service environment, which only the service account can read. Do not also set it as a machine-wide environment variable — that copy is readable by any local user via the registry.

Removing the relay

When you are done with the relay, see Removing the Relay for the full offboarding runbook and a read-only script that verifies nothing was left behind. Note that deleting the VM alone is not enough — the Managed Identity is a separate resource with its own lifecycle, and it is the thing that holds the permissions.