Skip to content

Portal Permissions

Sam Betts edited this page Nov 12, 2026 · 19 revisions

In this section: Portal Permission Verification

Who can use the web portal, and what they can see there, is decided in Microsoft Entra ID on the runtime app registration — the one the portal signs in with. Three settings work together:

Layer Decides Configured on Until you change it
Sign-in Who can open the portal at all. Everyone who signs in sees the aggregate insights. The enterprise application's Assignment required? property Every account in your directory, guests included
Administration permission Who can use the Administration area App role Portal.Administration Nobody
See PII permission Who can see data about identifiable people App role Portal.SeePII Nobody

The two permissions are independent: Administration does not include See PII, so the service can be run by someone who never sees data about an individual. The web app enforces both on every request; hiding a control in the browser is not the security boundary.

Separately, and only if you use it, Teams deep analytics needs two delegated Microsoft Graph permissions. See Teams deep analytics: delegated Graph permissions.

Upgrading to Stable build 1846 or later? The roles are enforced from that build, and nobody holds them until you assign them — including whoever runs the installer. Until you do, everyone who signs in still sees the aggregate insights, but the Administration area and per-person detail are hidden, and the APIs behind them answer 403 portalPermissionRequired. Create and assign the roles before you upgrade, or switch enforcement off for the changeover.

What each permission unlocks

With neither permission, a signed-in user sees the Insights area's aggregate figures: overview counts, reports, adoption and usage trends, and department or country breakdowns. The service-health snapshot on the Insights overview is part of the administrative side, so only holders of Administration see it.

Administration (Portal.Administration) unlocks the Administration area. The portal groups its pages like this:

Group Pages
Service Service health, Service configuration, Install log, Profiling
Connections Teams permissions (including Connect to Microsoft Teams), Copilot Studio billing connection, Copilot credit history (preview)
Users & scope User import, User scope (including its purge), User organisations, User data lookup
Copilot & reporting Report filter, Copilot Adoption settings, Copilot investment assumptions (since Stable 1857, PR #787), Leadership group, Prompt categories, Copilot audit backfill, Agent 365 catalogue

So Administration includes decisions that reach beyond the portal. Its holders can switch on prompt categorisation, which sends Copilot users' prompts to your Azure AI Foundry model, and can connect the accounts that read billing data: a billing administrator for Copilot Studio, and a reader for Copilot credit history. Administration doesn't include See PII, and it grants no permission in Microsoft Graph or the other source APIs: each connection needs its own sign-in and consent. Two pages in the area need See PII as well: User data lookup, because it is about one person, and Report filter, because its value picker lists people.

Current permission rule (since 1852): bypassing the global report filter requires Administration AND See PII. Neither alone is sufficient; direct exports/API calls follow the same check. Older 1850 behaviour allowed Administration alone. Upgrading tightens the check without changing role assignments.

See PII (Portal.SeePII) unlocks data about identifiable people wherever it appears:

Page What needs See PII
Copilot Adoption The Licensed users tab, including its detail of the time already saved by seat holders (the headline card still shows that estimate, without a link to the tab); the people lists for licence opportunities and Cowork readiness; their CSV exports; the Direct manager breakdown; the page-wide user filter; the per-person sheets of the Excel report
Copilot Adoption → Agents Heaviest agent users, a targeted named ranking for licence/advocate review; not a general employee-performance score
Licence activity The People tab (ranking, search and paging) and the people in its Excel export
Activity analysis Every filter (people, licence and activity range), because any of them can narrow the figures to one person; a department's people; and Top people, the champions
Teams Explorer Named lists (top meeting organisers and attendees, champions, dormant users) and the people sections of its export
DLP impact The table of people affected
Agent costs Who is spending the credits
Copilot investment (since Stable 1857) The People tab and a person's detail, the user filter, grouping by manager or a custom attribute, and the People sheet of the Excel report. Saving the assumptions needs Administration instead, and Administration does not include See PII
Copilot spend (since Stable 1857) The People tab and a person's detail, the user filter, grouping by manager, individual amounts in the spread, and the per-person sheets of the Excel report
User data lookup (Administration area) The whole page. It needs both permissions
Report filter (Administration area) The whole page. It needs both permissions

Without See PII those parts are hidden: Copilot Adoption's Licensed users tab and Licence activity's People tab disappear, and other sections say "Individual details are hidden" in their place. The aggregate figures on the same page are unaffected. The user filter needs See PII even though it only narrows aggregate figures, because a narrow enough filter can single out a handful of people. For the same reason, Activity analysis withholds figures that describe fewer than five people from readers without See PII, and Copilot Adoption leaves out segments of fewer than five seats for every reader (see Portal permission verification).

Since Stable 1859 (PR #805, PR #806, PR #807, PR #818): more figures that describe fewer than five people are withheld from readers without See PII: in Licence activity and Teams Explorer, which fold small groups into one combined row; in Copilot spend and Copilot investment, including Copilot investment's own totals and, when one to four seat holders were billed for Copilot Studio, its return; and in Copilot Adoption's department and manager breakdowns, there for every reader. Licence activity's department and country filters need See PII, and so does choosing which licence types Copilot Adoption counts as Copilot seats, even for Administration holders.

The same reasoning applies to the report filter an administrator sets for everyone. A reader without See PII never sees the sign-in names it uses, and their reports are refused while it leaves them fewer than five people. See Report filter → Readers without See PII.

Small groups withheld from readers without See PII

Since Stable build 1860, a reader without See PII isn't shown figures about one to four people on most report pages: Teams Explorer, Web activity, Agent costs, the Copilot agents, Office apps and Prompt insights reports, DLP impact, Copilot spend, Copilot investment, Copilot Adoption and Licence activity. Stable 1859 began this on some of them. The same rules apply everywhere:

  • Groups of fewer than 5 people are withheld.
  • A dash means withheld, not zero. A withheld figure shows as a dash or as Withheld, with the reason, and each page says when it has left something out.
  • Totals can't give a hidden row back. When a row is left out of a list, the smallest row still shown is usually left out too; otherwise the total less the rows shown would reveal it. So these readers can see fewer rows, and lower totals, than a reader with See PII.
  • Exports and workbooks follow the same rules as the page.
  • Readers with See PII see no change.
  • With EnforcePortalRoles=false, every reader holds See PII, so none of this applies.

Tell report readers that a dash means withheld, not zero, and review who holds See PII. What each page leaves out is described with the page: Teams Explorer, Web activity, the Copilot agents and Office apps reports, Prompt insights, Agent costs, DLP impact, Copilot spend, Copilot investment, Copilot Adoption and Licence activity.

Known gaps. A few combinations are still open, tracked in #844: comparing the same figure across report windows that all end today; tenants with only a few Copilot consumers; very small Copilot investment views; and, on DLP impact, a policy's figures compared with its rows under each agent, when every match for that policy came through an agent.

Before you start

  • Entra roles: creating app roles needs Cloud Application Administrator or Application Administrator, or ownership of the runtime app registration. Assigning them needs the same roles, or ownership of the enterprise application.
  • Which app registration: the runtime app registration's Application (client) ID is the web app's ClientID app setting. The portal also shows it on its "You do not have access to this page" message.
  • The installer neither creates nor assigns these roles. They are app roles, not API permissions, so they need no admin consent.

Step 1: create the app roles

  1. In the Microsoft Entra admin center, go to Entra ID → App registrations and open the runtime app registration.

  2. Select App roles → Create app role, fill in the first role below and select Apply. Repeat for the second.

    Field Administration role See PII role
    Display name Portal Administration Portal See PII
    Allowed member types Users/Groups Users/Groups
    Value Portal.Administration Portal.SeePII
    Description Use the Administration area of the Microsoft 365 Advanced Analytics portal. See data about individual people in the Microsoft 365 Advanced Analytics portal.
    Do you want to enable this app role? Ticked Ticked

Things to get right:

  • The Value is the only field the portal reads. It must be Portal.Administration or Portal.SeePII. Letter case is ignored, but spelling is not: a misspelt value grants nothing and reports no error. The display name and description are labels you can change.
  • Allowed member types must include Users/Groups. A role limited to Applications can't be assigned to people.
  • Roles belong to the app registration. Every deployment that signs in with the same runtime app registration (a test site and a production site, say) shares the same assignments. Use a separate runtime app registration if different people must run each one.

Or with the Azure CLI, in Windows PowerShell 5.1 or PowerShell 7. This adds the two roles and keeps any roles the app already has:

$ErrorActionPreference = 'Stop'
$appId = '<runtime app client ID>'
# ForEach-Object unrolls the array the same way in both PowerShell editions. origin is read-only in
# Microsoft Graph, so it is left out of what is sent back.
$roleJson = az ad app show --id $appId --query appRoles -o json | Out-String
if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($roleJson)) {
    throw 'Could not read existing app roles. Nothing will be replaced.'
}
$existing = @($roleJson | ConvertFrom-Json |
    ForEach-Object { $_ } | Select-Object -Property * -ExcludeProperty origin)
$wanted = @(
    [ordered]@{ allowedMemberTypes = @('User'); displayName = 'Portal Administration'; value = 'Portal.Administration'
        description = 'Use the Administration area of the Microsoft 365 Advanced Analytics portal.'; id = (New-Guid).Guid; isEnabled = $true },
    [ordered]@{ allowedMemberTypes = @('User'); displayName = 'Portal See PII'; value = 'Portal.SeePII'
        description = 'See data about individual people in the Microsoft 365 Advanced Analytics portal.'; id = (New-Guid).Guid; isEnabled = $true }
)
$roles = @($existing) + @($wanted | Where-Object { $_.value -notin @($existing | ForEach-Object { $_.value }) })
$file = New-TemporaryFile
try {
    [IO.File]::WriteAllText($file.FullName, (ConvertTo-Json -InputObject $roles -Depth 5),
        [Text.UTF8Encoding]::new($false))
    az ad app update --id $appId --app-roles "@$($file.FullName)"
    if ($LASTEXITCODE -ne 0) { throw 'App-role update failed; verify the current assignments.' }
} finally {
    Remove-Item $file -ErrorAction SilentlyContinue
}

--app-roles replaces the whole list, so the script refuses to proceed after a failed native CLI read. Running it again preserves existing values; check for an enabled User/Group role with the exact Value. Avoid concurrent app-role editors, then verify the result before assigning people.

Step 2: assign the roles

Assignments are made on the app's enterprise application (its service principal), not on the app registration.

  1. On the runtime app registration's Overview, select the link next to Managed application in local directory. Alternatively, go to Entra ID → Enterprise apps → All applications and search for it by name or Application ID.
  2. Select Users and groups → Add user/group.
  3. Under Users and groups, select None Selected, choose the people or groups, then Select. If someone doesn't come up when you search by name, search for the start of their sign-in name (UPN) instead.
  4. Under Select a role, choose Portal Administration or Portal See PII, then Assign.

One assignment carries one role. To give someone both permissions, repeat steps 2–4 for the same person and choose the other role: they then appear twice in Users and groups, once for each role. Membership of two assigned groups works too.

  • Don't use Edit assignment to add a second role. It replaces the role on the assignment you select, so the person loses the role they had. The application's Audit logs record each edit as Remove app role assignment from user and Add app role assignment grant to user in the same second, with the old and new role under Modified Properties.
  • Groups: assigning a group needs Microsoft Entra ID P1 or P2, and only direct members receive the role — nested groups are not supported. See Manage users and groups assignment to an application.
  • Who gets what: give Administration to the people who run the service. Give See PII only to people whose work needs named individuals, such as a licence reclaim review or a data-subject access request.

When a change takes effect

The portal reads the roles from the person's sign-in. A new assignment reaches them when they next sign in: at once if they select Sign out (top right of the portal) and sign back in, and otherwise within about an hour, when their sign-in expires.

Removals work the same way: a portal session that is already open keeps the role for up to about an hour.

To withdraw a permission, remove the assignment. Disabling the app role is not enough: Entra ID keeps issuing a disabled role to everyone who is still assigned it. See Add app roles and get them from a token.

Teams deep analytics permissions (moved)

The delegated Graph permissions for Teams deep analytics, and the Connect to Microsoft Teams steps, are now on Portal permission verification: see Add the permissions and Connect and authorise Teams.

Start here

Copilot analytics

Using the portal

Install & configure

Beyond Copilot

Operate

Upgrading from an older build

Reference

Project

Clone this wiki locally