Legacy SPO Web Setup
This page keeps the older SharePoint web-tracking setup guidance that no longer applies to current releases. Nothing here has been deleted — it has just been moved off the main installation pages so those describe only the current process.
Use this page if you are running an older release of the solution, if you are deploying to SharePoint Server on-premises, or if you are troubleshooting a site that was originally set up with one of the older methods.
For current deployments, start here instead: Install with the installer and Manual install — web tracking & config.
Web tracking (AITracker) is the only part of this solution that has ever needed an interactive administrator sign-in to SharePoint. How that sign-in works changed:
| Old (legacy) | Current | |
|---|---|---|
| Sign-in method | Embedded Internet Explorer pop-up inside the installer, authenticating with cookies (OfficeDevPnP.Core.AuthenticationManager.GetWebLoginClientContext) |
Your default system browser, authenticating with OAuth / MSAL |
| MFA, Conditional Access, passkeys / FIDO2 | Frequently broke — see MFA causing SharePoint install errors below | Fully supported; whatever your browser and tenant support works |
| Entra ID app registration | None | None by default — the installer uses Microsoft's built-in SharePoint Online Management Shell app. Optionally you can supply your own; see Optional: use your own Entra ID app registration |
| Number of sign-ins per install | One per site collection, plus one for the app catalog | One, reused for the app catalog and every target site |
| Command-line / scripted install |
InstallSPOInsightsTracker.ps1 + a saved password file (SecureString.txt) |
The installer, or the PnP script below |
The legacy stack (SharePointPnPCoreOnline / OfficeDevPnP.Core) was removed because it only ever shipped a .NET Framework 4.6.1 build, which blocked moving the installer to modern .NET. See issue #156.
Nothing about the tracker itself changed. The AITracker.js file, the SPOInsights document library, the per-web custom actions and the SPFx extension are all deployed exactly as before, and existing sites keep working after an upgrade. There is nothing to re-run on already-tracked sites.
Older documentation and older installer builds asked for SharePoint credentials (a username and password) on the installer's SharePoint tab, and the Prerequisites page listed:
SharePoint tenant administrator credentials | Used to install a SharePoint extension add-in into the app-catalog | Only if deploying SPO web components
SharePoint site collection administrator credentials | Usually same user as above. Site collection administrator rights required for target site collections | Only if deploying SPO web components
Current builds never ask for a password. The installer opens your browser, you sign in, and the token is held in memory for the duration of the install only — it is not written to the configuration file or to disk. The rights the signed-in admin needs are unchanged:
- SharePoint Administrator (or Global Administrator) — to upload and tenant-deploy the SPFx package to the tenant app catalog.
-
Site Collection Administrator on every target site collection — to create and secure the
SPOInsightslibrary and register the custom actions.
Error text: "'IdcrlException': The sign-in name or password does not match one in the Microsoft account system"
This no longer happens on current releases — the browser-based sign-in supports MFA, Conditional Access, passkeys and FIDO2 natively. The section is kept for anyone still running an older build.
On older builds, if the SharePoint account used to install the tracking JavaScript had MFA enabled, the install stage failed with the error above, and the standalone PowerShell usually failed for the same reason.
Workarounds that applied to those builds:
- Use the SharePoint add-in to deploy to each site collection.
- Use a SharePoint account without MFA applied.
- Deploy to SharePoint with the "PnP" PowerShell script (below).
The AITracker installer scripts still ship in AITrackerInstaller.zip and are still the right tool for SharePoint Server on-premises and for scripting deployment to new sites after the initial install. The username/password variants are legacy: SharePoint Online no longer accepts basic authentication, so on SPO use InstallSPOInsightsTracker.PnP.ps1 (or just re-run the installer).
Once Application Insights is set up & you have the AITrackerInstaller source, deploy the AITracker.js file to the SharePoint sites you want to track:
- Open the Microsoft 365 Advanced Analytics Engine build folder, then "Scripts.AITrackerInstaller".
- Create/edit the install json config file used by the PowerShell install script (DevConfig.json for example – edit or create your own).
- Change mandatory values in your new configuration file:
- TargetSites – a JSon array of the root sites (all sub-sites will be included automatically) to deploy to. Important – URL is the root-site URL only, with no trailing backslashes or pages/lists. See example config files shipped with the script.
- AdminUsername – a user ID with site-collection admin rights to the target site-collection (not needed for PnP PowerShell version)
- ApplicationInsightsKey – the "instrumentation key" for the Application Insights application created.
- The other keys can be changed if desired but aren’t critical.
Note: you may need to unblock the script for the script to run:
Run one of the scripts to deploy, depending on target needs, passing config filename as a parameter:
-
InstallSPOInsightsTracker.PnP.ps1— the only supported option for SharePoint Online. Uses a web login, so no username is read from the configuration file, and it works with MFA. -
InstallSPOInsightsTracker.ps1— legacy. Username + password against SharePoint Online. Basic authentication is disabled across SharePoint Online, so this will fail on current tenants. -
InstallSPOInsightsTracker-OnPrem.ps1— for SharePoint Server on-premises.
-
Example execution:
.\InstallSPOInsightsTracker.ps1 -ConfigFileName "MyConfig.json".
-
The first time it runs, it’ll need to save credentials in a secure-string file. A login box will appear; use the same username as configured in AdminUsername, set the password and click "OK".
The script will test if the user has site-collection admin rights. If it does it’ll save the credentials in a secure string.
ERROR: Problem reading password cipher from SecureString.txt. Please enter the password for <admin@contoso.onmicrosoft.com> in a sec... Refreshing secure-string file - please enter credentials Updated .\\SecureString.txt with refreshed password SUCCESS! .\\SecureString.txt updated with new password hash. Please run the script again & hopefully it'll work now! Couldn't upload tracker JS - see above!
-
Run the PowerShell script again to now successfully install the tracker.
AITracker uploads results to Application Insights to track "page views" and "custom events", containing the time the users spent on the previous page. Accurate time-tracking for users on pages is not standard Application Insights functionality.
Read configuration for environment name 'Contoso Development'...
Read encrypted password from .\\SecureString.txt. Installing AITracker.js...
Checking if <https://contoso.sharepoint.com/sites/spoinsights/Style%20Library/AITracker.js> exists...
AITracker.js doesn't exist for user <admin@contoso.onmicrosoft.com>!
AITracker.js uploaded to <https://contoso.sharepoint.com/sites/spoinsights/Style%20Library/AITracker.js>
File is checked-out. Checking in major version of AITracker.js...
Setting custom-action on all subsites to include AITracker.js in the HTML header...
Checking SPWeb.UserCustomActions...
Inserted custom-action into web: '<https://contoso.sharepoint.com/sites/spoinsights>'...
Checking sub-webs for site 'Microsoft 365 Advanced Analytics Engine Classic'...
18:39:04 - AITracker.js uploaded to site-collection root & referencing custom-actions inserted in all sub-sites!This is what you should see if it worked.
.\InstallSPOInsightsTracker.PnP.ps1 -ConfigFileName "MyConfig.json" -UninstallOnlyOn current releases you can instead use Remove AITracker on the installer's SharePoint tab — see Uninstall.
Older Prerequisites listed the SharePoint Online Management Shell as an optional installer-machine component, because the legacy PowerShell scripts above depend on it, as does the Set-SPOsite command used to allow custom scripts.
Current releases do not need it for the installer itself. Install it only if you plan to run the legacy scripts, or if you need Set-SPOsite -DenyAddAndCustomizePages 0 to enable classic-page tracking on a site collection (see Prerequisites → Tenant & subscription configuration).
You almost certainly don't need this.
Any OAuth sign-in needs an Entra ID app registration — an identity that the sign-in prompt is issued for. Rather than make you create one, the installer reuses one Microsoft already publishes: the app behind the SharePoint Online Management Shell PowerShell module, client ID 9bc3ab49-b65d-410a-85ad-de819febfddc. It's the same identity Connect-SPOService signs in with.
Using it means:
- Nothing to register or consent to in most tenants — it's a Microsoft-owned app that is already present.
- It's already configured as a public client with the
http://localhostreply URL and SharePoint delegated permissions, which is exactly what the installer needs. - It grants no standing access. It's a delegated sign-in: the installer can only ever do what the administrator sitting at the keyboard could already do, and only while they're signed in.
Register your own app only if one of these applies:
- Your tenant has disabled or blocked the SharePoint Online Management Shell enterprise application.
- Your security policy requires a consent record and sign-in audit trail owned by your organisation.
- Sign-in fails with
AADSTS65001(no consent),AADSTS7000112(application disabled),AADSTS700016(application not found in tenant) orAADSTS50105(user not assigned to the application).
In Entra ID → App registrations → New registration:
| Setting | Value |
|---|---|
| Name | e.g. Microsoft 365 Advanced Analytics - SharePoint Setup
|
| Supported account types | Accounts in this organizational directory only (single tenant) |
| Platform | Mobile and desktop applications (public client) |
| Redirect URI | http://localhost |
| Allow public client flows | Yes — there is no client secret, and none should be created |
| API permission |
SharePoint → Delegated → AllSites.FullControl ("Have full control of all site collections") |
| Admin consent | Grant admin consent for the SharePoint delegated permission |
AllSites.FullControl is the single delegated scope that covers everything the installer does in SharePoint: uploading and deploying the SPFx package, creating and securing the SPOInsights library, and registering the per-web custom actions.
This is a delegated permission, not an application permission. The app can only ever do what the signed-in administrator can already do — it grants the tool no standing access to SharePoint, and nothing happens under it unless an admin is actively signed in at the keyboard.
On the installer's SharePoint tab, paste the application (client) ID into Sign-in app ID (optional) and your tenant into Sign-in tenant.
The tenant is required when you use your own app ID. A new app registration is single-tenant by default, and Entra rejects the shared multi-tenant sign-in endpoint for those with
AADSTS50194. The installer validates this up-front so you don't hit it at sign-in time. This field is also the fix if you administer the tenant as a guest (B2B) account — without it you'd be signed in against your home tenant and SharePoint would return 401.
You can also set both directly in the saved installer configuration file (config schema 2.2.0 and later):
"SharePointConfig": {
"AppCatalogueURL": "https://contoso.sharepoint.com/sites/appcatalog",
"TargetSites": [ "https://contoso.sharepoint.com/sites/corp" ],
"AuthClientId": "00000000-0000-0000-0000-000000000000",
"AuthTenantId": "contoso.onmicrosoft.com"
}| Key | Meaning |
|---|---|
AuthClientId |
Application (client) ID of the app registration above. Blank = use the SharePoint Online Management Shell app. |
AuthTenantId |
Tenant (directory) ID or domain to sign in against. Required when AuthClientId is set. Blank = organizations, which is correct for the built-in default app. Also set this if you administer several tenants, or are a guest (B2B) administrator, and need to force a specific directory. |
Older configuration files load unchanged — both keys are optional and default to blank, which reproduces the built-in behaviour.