Manage Data access governance reports by using SharePoint Online PowerShell

While Data access governance is available in the SharePoint admin center, some organizations prefer to use PowerShell to manage settings at scale through scripting and automation. This article describes how to use the SharePoint Online PowerShell module to manage Data access governance reports.

Before you begin

Make sure your organization meets the Prerequisites for SharePoint Advanced Management, including SharePoint Online PowerShell module requirements.

PowerShell support for Data access governance is available from module Microsoft.Online.SharePoint.PowerShell and version 16.0.25409 or later.

When you connect to SharePoint, run the Connect-SPOService command without the Credential parameter. In line with security best practices, signing in by using the credential parameter isn't supported.

Create reports by using PowerShell

For syntax, parameters, and examples, see Start-SPODataAccessGovernanceInsight.

Generate a site permission state report

You need to understand the permissions setup in your organization, particularly in the wake of Copilot adoption, as it respects user and content permissions. Copilot's data exposure risk increases with the number of users having permissions or access. The site permission state report provides deep insights into potential exposure, based on the unique number of users who have permissions to every SharePoint and OneDrive site in your organization.

Run this report first to get a quick overview of permissions in your organization. This report is a snapshot report. It provides the latest snapshot or status of the entire organization as of the report generation date.

To generate a report for all your SharePoint sites, run the following command:

Start-SPODataAccessGovernanceInsight -ReportEntity PermissionedUsers -ReportType Snapshot -Workload SharePoint -CountOfUsersMoreThan 0  -Name "OrgWidePermissionedUsersReportSharePoint"

To generate a report for all your OneDrive for business accounts, run the following command:

Start-SPODataAccessGovernanceInsight -ReportEntity PermissionedUsers -ReportType Snapshot -Workload OneDriveForBusiness -CountOfUsersMoreThan 0  -Name "OrgWidePermissionedUsersReportODB"

Keep these important points in mind about the report:

  • Because these reports are comprehensive and likely to cover all data in your tenant, you can create up to two reports. You can create one report per workload.
  • The first report always takes up to five days to complete, regardless of the size of your organization. Subsequent reports complete within 24 hours.
  • These reports capture data up to 48 hours before the report generation.
  • Once generated, you can run these reports again once every 30 days.

These commands generate a list of all sites where at least one user can access any content within the site. For more information about how to interpret the report, see How to view the site permissions for your organization report.

Once you understand the extent of oversharing in your tenant, you can track further deviations specifically from active sites in last 28 days. You can generate reports on sites that are active in key factors of potential oversharing such as "Sharing links" or content shared with "Everyone except external users" in the last 28 days.

Generate a user permission state report

While the site permission report for the entire organization helps you understand the current state of permissions in the entire tenant, some scenarios require discovering sites accessible to a given user. For more information, see Get your organization's site permissions baseline with the snapshot report. The following section describes how data access governance helps you generate such a report by using PowerShell.

First, fetch the UPN or User principal name of the user for whom you want to generate the report by using the Get-MgUser command. Then run the following PowerShell command, which triggers the report listing SharePoint sites accessible to those users.

Start-SPODataAccessGovernanceInsight -ReportEntity PermissionsReport -ReportType Snapshot -Workload SharePoint -Name "UserSharePointReport" -UserEmailList "a@contoso.com","b@contoso.com"

Important

While the parameter is named UserEmailList, the report requires user principal names. You can include up to 100 users in a single request.

To list OneDrive accounts accessible to the given users, specify the workload as OneDriveForBusiness.

Start-SPODataAccessGovernanceInsight -ReportEntity PermissionsReport -ReportType Snapshot -Workload OneDriveForBusiness -Name "UserOneDriveReport" -UserEmailList "a@contoso.com","b@contoso.com"

Generate a sensitivity label in files report with PowerShell

Run this PowerShell command to trigger the report to list sites where specific items were labeled with a given label, as of the report generation date.

First, retrieve the label name or label GUID by using the Security & Compliance PowerShell module.

Get-Label | Format-Table -Property DisplayName, Name, GUID, ContentType

Then, use the name and GUID to retrieve sites with files labeled with the given label name or GUID.

Start-SPODataAccessGovernanceInsight -ReportEntity SensitivityLabelForFiles -Workload SharePoint -ReportType Snapshot -FileSensitivityLabelGUID "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" -FileSensitivityLabelName Secret

Note

Currently, the report for OneDriveForBusiness accounts with labeled files isn't supported.

Use sharing link activity reports to identify sites that are active in collaboration and need quicker intervention to mitigate any potential oversharing risk. These recent activity based reports identify sites that generate the most sharing links in the last 28 days.

Generate the following sharing link activity reports:

  • Sites that created Anyone sharing links in the last 28 days
  • Sites that created People in your organization sharing links in the last 28 days
  • Sites that created Specific people (guests) sharing links in the last 28 days
Start-SPODataAccessGovernanceInsight -ReportEntity SharingLinks_Anyone -Workload SharePoint -ReportType RecentActivity

Provide the workload value as OneDriveForBusiness to get all OneDrive accounts with the same criteria.

Start-SPODataAccessGovernanceInsight -ReportEntity SharingLinks_PeopleInYourOrg -Workload SharePoint -ReportType RecentActivity

Provide the workload value as OneDriveForBusiness to get all OneDrive accounts with the same criteria.

Start-SPODataAccessGovernanceInsight -ReportEntity SharingLinks_Guests -Workload SharePoint -ReportType RecentActivity

Provide the workload value as OneDriveForBusiness to get all OneDrive accounts with the same criteria.

Identify content shared with "Everyone except external users" in last 28 days

While sharing links can contribute to potential oversharing, another key contributor is "Everyone except external users" (EEEU). EEEU makes content public (visible to the entire organization) and makes it easy for others to discover content and get access. These reports identify sites that actively used EEEU at various scopes in the last 28 days.

You can generate the following EEEU activity reports:

  • Sites shared with Everyone except external users in last 28 days
  • Items shared with Everyone except external users in last 28 days

Important

Currently, the EEEU report for OneDrive for Business only supports the item level. EEEU reports for OneDrive for Business at the site level aren't supported. If you don't have a Microsoft SharePoint Advanced Management license, you must enable data collection for recent activity based reports so that relevant audit data is collected to build the report. After you enable it, the data is collected and stored for 28 days. You can generate the report 24 hours later, and it contains data from the point of collection. If you don't generate reports even once in three months, data collection is paused and you must enable it again. To enable data collection for these reports, see the section Manage data collection for recent activity based reports.

Identify sites shared with "Everyone except external users" in last 28 days

When you add EEEU to a site membership (owners, members, or visitors), the entire content of the site becomes public and more prone to oversharing. Run the following PowerShell command to trigger the report to capture such sites in the last 28 days for SharePoint sites:

Start-SPODataAccessGovernanceInsight -ReportEntity EveryoneExceptExternalUsersAtSite -Workload SharePoint -ReportType RecentActivity -Name "PublicSiteViaEEEU"

Identify items shared with "Everyone except external users" in last 28 days

Run the following PowerShell command to trigger the report to capture specific items (files, folders, or lists) that you shared with EEEU in the last 28 days for SharePoint sites:

Start-SPODataAccessGovernanceInsight -ReportEntity EveryoneExceptExternalUsersAtSite -Workload SharePoint -ReportType RecentActivity -Name "PublicSiteViaEEEU"

Note

Replace the workload value with OneDriveForBusiness to get items shared with "Everyone except external users" for all OneDrive accounts with the same criteria.

Manage data collection for recent activity based reports

Important

If you don't have a Microsoft SharePoint Advanced Management license, you must enable data collection for recent activity based reports so that relevant audit data is collected to build the report. After you enable it, you can generate the report 24 hours later, and it will contain data from the point of collection. Data is stored for 28 days. If you don't generate reports even once in three months, data collection is paused and you must enable it again.

Enable data collection for recent activity based reports

This PowerShell command starts collecting audit data for reports on activities from the last 28 days.

Start-SPOAuditDataCollectionForActivityInsights -ReportEntity SharingLinks_Anyone

The applicable values for the ReportEntity parameter are SharingLinksAnyone, SharingLinksPeopleInYourOrg, SharingLinksGuests, EveryoneExceptExternalUsersAtSite, EveryoneExceptExternalUsersForItems, CopilotAppInsights

Disable data collection for recent activity based reports

This PowerShell command stops collecting audit data for reports on activities from the last 28 days.

Stop-SPOAuditDataCollectionForActivityInsights -ReportEntity SharingLinks_Anyone

Check the data collection status for recent activity based reports

Once data collection is enabled, the reports can be generated after 24 hours. To check whether reports can be generated, use the PowerShell command Get-SPOAuditDataCollectionStatusForActivityInsights. The command returns the current data collection status, which can be NotInitiated, InProgress, or Paused. Reports can be generated when the status is InProgress.

Get-SPOAuditDataCollectionStatusForActivityInsights -ReportEntity SharingLinks_Anyone

Track reports by using PowerShell

Important

Each report creation returns a GUID that you can use to track the report status.

Start-SPODataAccessGovernanceInsight -ReportEntity SensitivityLabelForFiles -Workload SharePoint -ReportType Snapshot -FileSensitivityLabelGUID "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" -FileSensitivityLabelName Secret

ReportId                             Status
--------                             ------
a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 NotStarted

Use the Get-SPODataAccessGovernanceInsight command to get the current status of a specific Data access governance report by using the report ID.

Get-SPODataAccessGovernanceInsight -ReportID a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1

ReportId          : a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
ReportEntity      : SharingLinks_Anyone
Status            : InQueue
Workload          : SharePoint
TriggeredDateTime : 11/13/2024 19:32:34
CreatedDateTime   : 11/13/2024 20:09:23
ReportStartTime   : 10/17/2024 19:32:33
ReportEndTime     : 11/13/2024 19:32:33
ReportType        : RecentActivity
SitesFound        : 120

The ReportStartTime and ReportEndTime show the period of data for the report. The status changes to Completed when the report generation finishes.

You can also view the current status of DAG reports by using the filter ReportEntity instead of ID. The reportID appears in the output and is needed later to download a specific report.

Get-SPODataAccessGovernanceInsight -ReportEntity PermissionedUsers

ReportId             : a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
ReportName           : PermissionReportFor1AsOfSept
ReportEntity         : PermissionedUsers
Status               : Completed
Workload             : SharePoint
TriggeredDateTime    : 09/18/2024 11:06:16
CreatedDateTime      : 09/22/2024 12:12:48
ReportType           : Snapshot
CountOfUsersMoreThan : 1
CountOfSitesInReport : 7
CountOfSitesInTenant : 22
Privacy              : All
Sensitivity          : {All}
Templates            : {All}

ReportId             : b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2
ReportName           : PermissionReportFor1AsOfOct
ReportEntity         : PermissionedUsers
Status               : Completed
Workload             : SharePoint
TriggeredDateTime    : 10/09/2024 14:15:40
CreatedDateTime      : 10/09/2024 15:18:23
ReportType           : Snapshot
CountOfUsersMoreThan : 100
CountOfSitesInReport : 0
CountOfSitesInTenant : 26
Privacy              : All
Sensitivity          : {All}
Templates            : {All}

View and download reports by using PowerShell

To download a specific report, you need the reportID. Get the reportID by using the Get-SPODataAccessGovernanceInsight command. Then, use the Export-SPODataAccessGovernanceInsight command to download the report to a path you specify.

Export-SPODataAccessGovernanceInsight -ReportID a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 -DownloadPath "C:\Users\TestUser\Documents\DAGReports"

This command downloads a CSV file to the path you specify. You can find details about the CSV and view for each report in How to access the Data access governance reports in the SharePoint admin center.

Note

The default download path is the Downloads folder.

Perform remedial actions by using PowerShell

After you generate data access governance reports, you can perform remedial actions as described in Remedial actions from Data access governance reports.

The following section describes PowerShell commands to initiate and track site access reviews as a remedial action.

Initiate site access review by using PowerShell

Use the Start-SPOSiteReview command to initiate a site access review for a specific site, listed under a data access governance report. The data access governance report provides the context under which you should initiate the review. Retrieve the report ID and site ID from the CSV file and provide comments to give clarity to the site owner regarding the purpose of the review.

Start-SPOSiteReview -ReportID a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 -SiteID c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3 -Comment "Check for org wide access"

ReviewId                : a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
SiteId                  : c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3
ReviewInitiatedDateTime : 13-11-2024 20:55:41
ReportEntity            : PermissionedUsers
Status                  : Pending
AdminComment            : Check for org wide access
SiteName                : All Company

This command generates emails to site owner as described in How to initiate a site access review.

Track site access reviews by using PowerShell

Use Start-SPOSiteReview command to track the status of site access reviews. For specific reviews, use the ReviewID value as shown in the output. To retrieve all reviews related to a reporting module, use the ReportEntity parameter.

Get-SPOSiteReview -ReportEntity PermissionedUsers

ReviewId                : a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
SiteId                  : c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3
ReviewInitiatedDateTime : 13-11-2024 20:55:41
ReviewCompletedDateTime :
ReportCreatedDateTime   : 13-11-2024 23:25:41
ReportEndDateTime       : 13-11-2024 23:25:41
ReportEntity            : PermissionedUsers
Status                  : Pending
AdminComment            : Check for org wide access
SiteName                : All Company
ReviewerEmail           :
ReviewerComment         :

ReviewId                : a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
SiteId                  : c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3
ReviewInitiatedDateTime : 24-10-2024 11:07:39
ReviewCompletedDateTime : 15-11-2024 11:07:39
ReportCreatedDateTime   : 15-10-2024 09:24:47
ReportEndDateTime       : 15-10-2024 11:39:52
ReportEntity            : PermissionedUsers
Status                  : Completed
AdminComment            : Check for org wide access
SiteName                : All Company
ReviewerEmail           : Jon@contosofinance.com
ReviewerComment         : Removed EEEU for sensitive documents
  • Last updated on