Installation & onboarding guide

Contents

·Before you start

Have these ready. Full detail on each is in the Azure services, data & security overview.

1Register sign-in

1. Run locally · needs Application Administrator

   Create the Entra sign-in app

   Run the connector script once. It creates a single-tenant app registration for sign-in, adds the Admin / Reviewer / Viewer roles AI Pulse uses internally, and records who the first administrator will be.

   # Uses your current az login identity as the first admin by default .\Connect-AIPulseTenant.ps1 ` -AppDisplayName "AI Pulse" ` -AdminObjectId "<your Entra object ID, or omit to auto-detect>"

   This writes aipulse-onboarding.parameters.json next to the script, containing the Entra client ID, client secret, tenant ID, and the first-admin object ID. Keep this file private and delete it once you've used it — it holds a live secret.

2Deploy from Marketplace

1. Azure Portal · needs Owner or User Access Administrator

   Launch AI Pulse and complete the wizard

   From Azure Marketplace, deploy AI Pulse into your subscription. The wizard has three steps beyond naming the resource group:

   Step	What you'll enter
   Database	A Postgres admin password (16+ characters, mixed case, digits, symbols).
   Identity & SSO	The Entra tenant ID, client ID, client secret, and admin object ID from Step 1's output file.
   AI & Telemetry	Your AI Pulse Gateway URL + key, your Azure OpenAI endpoint, and your SYLVA subscription key.

   The wizard shows an upfront warning that the account running the deploy needs Owner or User Access Administrator — this is expected: the template grants its own managed identity three narrow read-only roles (Reader, Cost Management Reader, Key Vault Secrets User), never anything broader, and only a privileged account can create those role assignments. Deployment takes roughly 5–10 minutes.

   When it finishes, open the deployment's Outputs — you'll need portalFqdn and miPrincipalId for the next two steps.

3Register the redirect URI

1. Run locally · needs Application Administrator

   Point sign-in at the new deployment

   The portal's web address only exists after deployment, so this has to be a separate step. Run:

   .\Set-AIPulseRedirectUri.ps1 ` -EntraClientId "<client ID from Step 1>" ` -AiPulseFqdn "<portalFqdn from the deployment Outputs>" ` -ResourceGroup "<your resource group>"

   This registers https://<portalFqdn>/auth/callback on the sign-in app and restarts the portal with the address set — no image rebuild, just a fresh revision (about 30 seconds).

4Grant read-access

1. Run locally · needs Privileged Role Administrator

   Let the portal read its Microsoft signals

   The portal reads Microsoft Graph using its own managed identity — a separate identity from the sign-in app in Step 1, created fresh during deployment. Grant it the seven read-only permissions it needs (license detection, name resolution, audit trail, shadow-AI discovery):

   .\Grant-AIPulseGraphAccess.ps1 ` -ManagedIdentityPrincipalId "<miPrincipalId from the deployment Outputs>"

   It's safe to run more than once — anything already granted is skipped. If you'd rather grant a subset now and the rest later, pass -Roles with just the ones you want (see the script's help text for the full list). Anything not yet granted shows an honest "permission pending" state in the portal rather than a blank or broken widget.

5First sign-in

1. Browser · the first administrator

   Sign in and complete the setup wizard

   Open https://<portalFqdn> and sign in with the Entra account whose object ID you provided in Step 1. That first sign-in automatically claims the admin role — a one-time, single-use bootstrap. Anyone added as an administrator afterwards is managed inside the product, not through this file.

   The in-product setup wizard then walks through a live check of each optional security service (Defender, Sentinel, Content Safety) so you know exactly what's connected before you start using the dashboards.

·Optional · Microsoft 365 connectors

Only needed if you want Microsoft 365 Copilot usage and Purview governance signals. Requires Microsoft 365 E5 or Copilot add-ons.

This opens one browser sign-in for Security & Compliance and one device-code prompt for Exchange Online, then creates three AI-governance sensitivity labels, two DLP policies, and confirms the unified audit log is on. Takes about five minutes. Without this step, the Copilot and Purview widgets show "licence required" rather than an error.

·Troubleshooting

·Completion checklist

• Sign-in app created and the parameters file's secret has been deleted from disk.
• Managed Application deployed; portalFqdn and miPrincipalId recorded.
• Redirect URI registered and the portal loads at its address.
• Graph read-access granted to the managed identity.
• First administrator signed in and completed the setup wizard.
• Optional: Microsoft 365 connectors run, if applicable.