Skip to content

Portal Permission Verification

Sam Betts edited this page Nov 4, 2026 · 5 revisions

Portal Permissions → Portal Permission Verification

Check what someone holds

  • In Entra ID, for one person: go to Entra ID → Users, open the person and select Applications. Filter to the Runtime enterprise application. Read the Role and assignment source for each row: a person assigned both Portal.Administration and Portal.SeePII has two role assignments. Group inheritance and direct assignment are different sources; verify the intended one. See assign app roles.

  • In Entra ID, for the whole app: the enterprise application's Users and groups list has a row per assignment, so someone with both permissions appears twice. The role is in the Role assigned column, which is often off the right-hand edge of the list: the columns are a fixed width, so on many screens only Display name and Object type fit. Hold Shift and turn the mouse wheel over the list (or swipe sideways on a touchpad) to scroll it, or zoom the browser out until the column appears. It is normally already ticked under Manage view → Edit columns, so ticking it there doesn't help.

  • Give that list a few minutes. A new assignment can take a few minutes to show in Users and groups. Straight after a second role was added, the list showed only the new one for a minute or two. Refresh before deciding a role was replaced.

  • To withdraw one permission, find the person's row for that role in Users and groups, tick it and select Remove assignment. Their other roles are separate rows and are not affected.

  • In the portal: only holders of Portal.Administration see Administration in the area switcher. A page the person can't use shows "You do not have access to this page", with the permission, the app role to assign, and the Application ID the portal signs in with. If that ID isn't the app you assigned roles on, the roles are on the wrong app.

  • From a script or an export link: a refused request gets 403. A script receives JSON like the example below; a browser that opens an export link directly gets the message as plain text.

    {
      "code": "portalPermissionRequired",
      "permission": "seePii",
      "role": "Portal.SeePII",
      "message": "This shows information about individual people, which needs the See PII permission. Ask an Entra ID administrator to assign you the Portal.SeePII app role."
    }

Restrict who can sign in

The roles decide what people can see once they are in. They don't decide who gets in. By default any account in your directory, guests included, can sign in and read the aggregate insights. To limit sign-in to people you name:

  1. Open the enterprise application (see Step 2) and select Properties.
  2. Set Assignment required? to Yes (older versions of the portal call it User assignment required?), then select Save.

From then on only people assigned to the application, directly or through a group, can sign in. Anyone else is stopped at sign-in with AADSTS50105 ("…to block users unless they are specifically granted ('assigned') access to the application").

  • Everyone now needs an assignment, including people who should only see aggregates. Both portal roles grant more than that, so create a third app role for them — for example with the Value Portal.Reader, the display name Portal reader (aggregate insights only) and Users/Groups — and assign that. The portal ignores roles it doesn't recognise, so this role only lets the person sign in.
  • Assignments made before the roles existed show the role Default Access. They grant neither permission.
  • Global Administrators can always sign in, whatever this setting says. Without a role they too see only the aggregates.
  • Leave Enabled for users to sign-in? at Yes. Setting it to No switches off the whole application, including for the import web-jobs, which authenticate as the same app.

See Restrict a Microsoft Entra app to a set of users.

Switching enforcement off temporarily

If you can't assign the roles in time for an upgrade, set the web app's EnforcePortalRoles app setting to false (App Service → Environment variables → App settings). Saving app settings restarts the web app.

  • false restores the behaviour from before build 1846: everyone who can sign in holds both permissions, including access to data about individual people. While it's off, the Administration area shows a warning.
  • While it's off, an administrator's report filter is not a security boundary: anyone can change it, or switch it off for their own view.
  • Only false, in any letter case, switches enforcement off. A missing or empty setting, or any other value (0, no, a typo), leaves the roles enforced: a typo in a security switch never widens access.
  • The installer doesn't write this setting, and keeps it when you re-run it. Remove it, or set it to true, once the roles are assigned.

Teams deep analytics: delegated Graph permissions

Teams deep analytics is one of two optional features that use Microsoft Graph as a signed-in person. The other is Copilot credit history (preview), which has its own, separate connection: someone holding Portal.Administration connects a reader account with an active Global Reader role, using four delegated CopilotCostManagement…Read.All Microsoft Graph permissions (with admin consent) plus offline_access. Its delegated token reads every person's credit balance, so decide deliberately who may connect it; see its connection permissions and setup. Signing in to the portal asks for openid email profile and nothing else, so the rest of the portal works without anything in this section. (Before Stable build 1846, every sign-in asked for the Teams permissions — see Known issues.)

Add the permissions

On the runtime app registration:

  1. Select API permissions → Add a permission → Microsoft Graph → Delegated permissions.
  2. Select Team.ReadBasic.All and ChannelMessage.Read.All, then Add permissions.
  3. Select Grant admin consent for your organisation. ChannelMessage.Read.All always needs an administrator's consent, and when Assignment required? is Yes, users can't consent to anything themselves.

Choose Delegated permissions, not Application permissions. Both names exist as both types, and the application versions don't help here.

Connect and authorise Teams

  1. Someone holding Portal.Administration opens Administration → Teams permissions.
  2. If the page has no Graph access for them yet, it offers Connect to Microsoft Teams. The portal asks Entra ID for openid email profile offline_access Team.ReadBasic.All ChannelMessage.Read.All, Entra ID sends them straight back, and the page lists the Teams they belong to.
  3. Authorising a Team stores that person's delegated refresh token for it in the TeamsAuth partition of the AnalyticsState table, in the solution's own storage account. The importer reads that Team's channels with it on its next cycle.

The connection is held in the portal session. When the session ends, or the token stops working, the page offers Connect to Microsoft Teams again; Teams that are already authorised keep their own stored token. Teams deep analytics also needs the Storage connection string, which the installer sets. Without it the page says so, and nothing can be authorised.

Since Stable 1856 (PR #768):

  • If the web app can't reach Microsoft Entra ID to refresh your connection (Entra ID unreachable, a timeout, throttling or a server error), the page says Couldn't reach Microsoft Entra ID to refresh your Teams connection. Try again in a few minutes. and offers Try again instead of Connect to Microsoft Teams. Connecting again wouldn't help: it ends by asking the same Entra ID endpoint, from the same server. Connect to Microsoft Teams is still offered when your connection has expired, been revoked, or needs you to sign in again (for example for MFA or a Conditional Access policy).
  • The importer keeps each Team's stored token unless Entra ID or Microsoft Graph shows the token itself is no good: a Conditional Access block, an outage, throttling, or the importer's own expired client secret no longer delete it. It also stores each renewed refresh token, so an authorisation no longer lapses about 90 days after it was given. See Teams and calls troubleshooting → when a Team's authorisation is kept or removed.

Upgrading from a build before 1846? Team authorisations used to be kept in Redis, which is no longer used, and they were not carried over. Authorise each Team again after upgrading.

If Entra ID refuses

The admin comes back to the page, still signed in, with "Microsoft Teams isn't connected" and the Entra ID error code:

What happened Typical codes What to do
The permissions aren't granted to the runtime app AADSTS65001, AADSTS65005, AADSTS90094, AADSTS650056, AADSTS650057 Add the permissions and grant admin consent, then connect again
The request was cancelled or declined AADSTS65004 Connect again and accept. If Entra ID asked for an administrator's approval, grant admin consent first
Anything else Any other Look in the web app's Application Insights under the operation name Web Teams connection

Troubleshooting

Symptom Likely cause Fix
No Administration in the area switcher The sign-in carries no Portal.Administration Assign it (Step 2), then sign out and back in
"You do not have access to this page" The permission it names is missing Assign the app role it names, on the app whose Application ID it shows
"Individual details are hidden" No Portal.SeePII Assign it, if that person should see individual people
A role is assigned but nothing changed The session started before the assignment; the person is only in a nested group; the role's Value is misspelt; or the role is on another app registration Sign out and back in; assign a group they belong to directly; correct the Value; compare the Application ID on the access-denied message
Someone who should hold both permissions has only one The second role was given with Edit assignment, which replaces the role instead of adding one Add the missing role with Add user/group (Step 2), then check the person's Applications page (Check what someone holds)
Users and groups doesn't show which role someone has The Role assigned column is off the right-hand edge of the list Scroll the list sideways (Shift + mouse wheel) or zoom out, or use the person's Applications page — see Check what someone holds
AADSTS50105 at sign-in Assignment required? is Yes and the person has no assignment Assign them a role — the reader role if they should only see aggregates
"Portal permissions could not be checked, so administration features and individual details are hidden." The portal couldn't read /api/PortalAccess Reload. If it persists, check the web app's Application Insights
"Role checks are switched off for this deployment (EnforcePortalRoles=false)…" EnforcePortalRoles is false Remove the setting once the roles are assigned
"Microsoft Teams isn't connected" The delegated Teams permissions are missing or not consented See If Entra ID refuses
"Couldn't reach Microsoft Entra ID to refresh your Teams connection. Try again in a few minutes." (since Stable 1856) The web app couldn't reach Microsoft Entra ID, or Entra ID timed out, throttled or failed Wait, then select Try again. If it persists, check the web app's outbound access to Microsoft Entra ID
A report is refused with a message about "the filter a portal administrator set", or with the See PII message while a report filter applies The administrator's report filter can't be applied, or it leaves a reader without See PII fewer than five people See Report filter → When reports are refused or empty
AADSTS50011 at sign-in The reply URL doesn't match See Runtime app reply URLs

What this does and does not protect

  • It controls what the portal shows, not what the database holds. Anyone with direct access to the SQL database can read everything, including every table these permissions hide in the portal. Give database access only to people who may see data about individuals: see Security model → Give yourself access to query the database.
  • Aggregates are shown to everyone who can sign in. Copilot Adoption leaves out segments smaller than its minimum size (MinSeatsPerSegment, 5 seats), but other reports can show a small count, and a small enough group can point to a person.
  • Page addresses are not treated as personal. Web activity lists the pages people visited, and every portal user sees those addresses. An address can contain a person's name, as a OneDrive address does.
  • Azure resource names and tags are not treated as personal. Agent costs can break Azure spend down by resource, resource group, subscription, or the tag you chose to import (TagKey: in AzureCostGroupBy). If a name or tag value identifies a person, for example an Owner tag holding an email address, every portal user sees it. Import a tag such as a cost centre instead if that matters to you.
  • The Administration area shows operational records, not reports about people, but they can still name accounts. The install log records who ran the installer and the installer configuration, which includes the SQL administrator and database user accounts. Service health can show an error message that names a user. Assign Administration to people you trust with that.

Related pages


Return to Portal Permissions · All topics in this guide

Start here

Copilot analytics

Using the portal

Install & configure

Beyond Copilot

Operate

Upgrading from an older build

Reference

Project

Clone this wiki locally