Track and revoke document access

Article
08/01/2024

Document tracking provides information for administrators about when a protected document was accessed. If necessary, both admins and users can revoke document access for tracked documents.

A document must be registered for tracking before an admin can track access details, including successful access events and denied attempts, and revoke access if needed. See the next section for minimum versions of Office apps for built-in labeling that support file registration the next time they're opened.

Note

Track and revoke features are supported for Office file types only.

Requirements

Use the capabilities table and the row Document tracking and revocation to identify the minimum versions of Word, Excel, and PowerPoint that automatically register label-protected local Office documents (if not already registered) the next time they're opened.

PowerShell cmdlets in this article use the AIPService PowerShell module, which you can install from the PowerShell Gallery. You must run Connect-AipService to connect to your tenant before you run any of the documented cmdlets.

Limitations

Password-protected documents aren't supported by track and revoke features.
If you attach multiple documents to an email, and then protect the email and send it, each of the attachments gets the same ContentID value. This ContentID value will be returned only with the first file that had been opened. Searching for the other attachments won't return the ContentID value required to get tracking data.

Additionally, revoking access for one of the attachments also revokes access for the other attachments in the same protected email.
Documents protected with admin-defined permissions that are uploaded to SharePoint or OneDrive lose their ContentID value, and access can't be tracked or revoked.
If a user downloads a file protected with admin-defined permissions from SharePoint or OneDrive, a new ContentID is applied to the document. Using the original ContentID value to track data won't include any access performed for the user's downloaded file. Additionally, revoking access based on the original ContentID value won't revoke access for any of the downloaded files.

If administrators have access to the downloaded files, they can use PowerShell to identify a document's ContentID for track and revoke actions.

Track document access

Admins can track access for protected documents via PowerShell using the ContentID generated for the protected document during registration.

To view document access details:

Use the following cmdlets to find details for the document you want to track:

Find the ContentID value for the document you want to track.

Use the Get-AipServiceDocumentLog to search for a document using the filename or the email address of the user who applied protection.

For example;
```
Get-AipServiceDocumentLog -ContentName "test.docx" -Owner “alice@contoso.com” -FromTime "12/01/2020 00:00:00" -ToTime "12/31/2020 23:59:59"
```
This command returns the ContentID for all matching, protected documents that are registered for tracking.

Note

Protected documents are registered for tracking when they're first opened in an Office app that supports file registration. If this command does not return the ContentID for your protected file, open it in an Office app that supports file registration.
Use the Get-AipServiceTrackingLog cmdlet with your document's ContentID to return your tracking data.

For example:
```
Get-AipServiceTrackingLog -ContentId c03bf90c-6e40-4f3f-9ba0-2bcd77524b87
```
Tracking data is returned, including emails of users who attempted access, whether access was granted or denied, the time and date of the attempt, and the domain and location where the access attempt originated.

Revoke document access from PowerShell

Admins can revoke access for any protected document stored in their local content shares, using the Set-AIPServiceDocumentRevoked cmdlet.

Note

If offline access is allowed, users will continue to be able to access the documents that have been revoked until the offline policy period expires.

Find the ContentID value for the document you want to revoke access for.

Use the Get-AipServiceDocumentLog to search for a document using the filename or the email address of the user who applied protection.

For example:
```
Get-AipServiceDocumentLog -ContentName "test.docx" -Owner “alice@contoso.com” -FromTime "12/01/2020 00:00:00" -ToTime "12/31/2020 23:59:59"
```
The data returned includes the ContentID value for your document.

Tip

Only documents that have been protected and registered for tracking have a ContentID value. If your document has no ContentID, open it in an Office app that supports file registration.

Use the Set-AIPServiceDocumentRevoked with your document's ContentID to revoke access.

For example:

Set-AipServiceDocumentRevoked -ContentId 0e421e6d-ea17-4fdb-8f01-93a3e71333b8 -IssuerName testIssuer

By using the Sensitivity menu in their Office apps, users can also revoke access for any documents that they protected.

Restore access

If you've accidentally revoked access to a specific document, use the same ContentID value with the Clear-AipServiceDocumentRevoked cmdlet to restore the access.

For example:

Clear-AipServiceDocumentRevoked -ContentId   0e421e6d-ea17-4fdb-8f01-93a3e71333b8 -IssuerName testIssuer

Document access is granted to the user you defined in the IssuerName parameter.

Turn off track and revoke features for your tenant

If you need to turn off track and revoke features for your tenant, such as for privacy requirements in your organization or region, run the Disable-AipServiceDocumentTrackingFeature cmdlet.

Document tracking and options to revoke access are turned off for your tenant:

Opening protected documents no longer registers the documents for track and revoke.
Access logs aren't stored when protected documents that are already registered are opened. Access logs that were stored before turning off these features are still available.
Admins won't be able to track or revoke access via PowerShell, and although end-users still see the Revoke menu option in their Office apps, the site displays a message that tracking and revocation has been disabled by their administrator.

If you need to turn track and revoke back on, run the Enable-AipServiceDocumentTrackingFeature cmdlet.

If you need to remove the Track & Revoke button from the sensitivity menu on Office clients, use PowerShell advanced settings with the Set-LabelPolicy cmdlet.

Example PowerShell command:

Set-LabelPolicy -Identity Global -AdvancedSettings @{EnableRevokeGuiSupport="False"}

Share via