SharePoint and OneDrive
Proofroom reads policy files kept in SharePoint document libraries or OneDrive through Microsoft Graph, with an app registration that reads: each file’s version history and the approval of its linked Proofroom policy become evidence of the yearly review, who can edit the file becomes an access list to review, and a Word, PDF or text file can be imported as a Proofroom draft. Add it on Policies → Where your policies live → SharePoint and OneDrive → Connect.
What each collector shows
| Collector | Kind | Default cadence | What it shows | Suggested controls |
|---|---|---|---|---|
| Policy document reviews | snapshot | quarterly | Each tracked file with when it last changed and who changed it, its versions in the last 12 months and whether a review was recorded: its linked Proofroom policy approved (with changes, or reviewed with no changes) in the 12 months before the run. A change in SharePoint is shown with its date but is not counted as a review; the version Proofroom writes when publishing back is not counted as a change. | PCI DSS 12.1.2; SOC 2 CC5.3 |
| Who can edit policy documents | snapshot | quarterly | For each tracked file, every permission with edit or full control: people, groups, the site’s groups (such as Members and Owners), and sharing links that let people edit, marked when inherited from the library or a folder. The run fails when Microsoft Graph returns no owner of a file, because the list is then partial (see below). | SOC 2 CC6.2, CC6.3 |
SharePoint keeps as many versions as the library’s versioning settings allow. Proofroom lists files with these extensions: .docx, .doc, .pdf, .md, .txt, .html, .odt and .rtf. It can import the text of .docx, .pdf, .md, .txt and .html.
Create the app registration
- In the Microsoft Entra admin center, go to App registrations → New registration. Name it “Proofroom policies” and register it. Note the Application (client) ID and Directory (tenant) ID.
- Certificates & secrets → New client secret. Copy the secret’s Value.
- API permissions → Add a permission → Microsoft Graph → Application permissions. Choose one:
- Sites.Selected (recommended): the app can reach only the sites you grant it. After admin consent, grant a
role on each policy site: read for the review history and text, fullcontrol if you also collect who can
edit (see “Who can edit: the full list” below). A SharePoint admin runs, for example in Microsoft Graph PowerShell signed in with
Sites.FullControl.All:
New-MgSitePermission -SiteId "<host>.sharepoint.com:/sites/<site>" -BodyParameter @{ roles = @("read"); grantedToIdentities = @(@{ application = @{ id = "<client id>"; displayName = "Proofroom policies" } }) } - Files.Read.All: every site and OneDrive in the tenant. Needed only for policies in someone’s OneDrive. It is broader than Proofroom needs, so prefer Sites.Selected.
- Sites.Selected (recommended): the app can reach only the sites you grant it. After admin consent, grant a
role on each policy site: read for the review history and text, fullcontrol if you also collect who can
edit (see “Who can edit: the full list” below). A SharePoint admin runs, for example in Microsoft Graph PowerShell signed in with
Sites.FullControl.All:
- Grant admin consent.
- Optional: Application.Read.All lets Proofroom warn before the client secret expires.
Connect
| Field | Value |
|---|---|
| Directory (tenant) ID, Application (client) ID, client secret | From steps 1 and 2 |
| Sites | One per line, such as contoso.sharepoint.com/sites/Policies |
| OneDrive users | Optional: sign-in names, one per line (needs Files.Read.All) |
Test connection lists the sites’ libraries and their top-level folders.
Then, on Policies → Where your policies live → the connection: pick the libraries or folders (five folder levels are read below each), press Check now, tick Track for each policy file and link it to its Proofroom policy (links are suggested by title; press Use suggestion or choose one), and use Import as draft to start a Proofroom draft from a file. SharePoint records edits, not reviews, so a review is recorded in Proofroom: approve each linked policy once a year (with changes, or as reviewed with no changes). A tracked file whose policy was not approved in 12 months becomes a task; editing the file in SharePoint does not answer it.
Who can edit: the full list
Microsoft Graph returns every permission on a file only to a caller with the owner role on it; any other caller gets only the permissions that apply to itself (List who has access to a file). Every file has an owner (the site’s Owners group, or the OneDrive’s owner), so when Graph returns no owner Proofroom fails the “Who can edit policy documents” run, naming the file, rather than file a short list.
To get the full list, grant the app the fullcontrol role on each policy site (Sites.Selected), the role that makes it an owner there. That role can also change the site, so give it to this app only, keep its secret as tightly as any admin credential, and leave the editor collector switched off if you do not want to grant it. The review history and import need only the read role.
Publishing approved policies back (optional, off by default)
When a linked Proofroom policy is approved, Proofroom can upload the approved text as a new version of the linked Word file (a plain Word document: headings, paragraphs, lists and tables). This needs write access, so it uses a second app registration:
- Register another app (“Proofroom publishing”) with a client secret, and give it Sites.Selected with the write role on the policy sites only (or Files.ReadWrite.All).
- On the connection’s settings, tick Publish approved policies and enter that app’s client ID and secret.
Only .docx files are published to. The version Proofroom writes is not counted as a change in SharePoint. A failure is shown on the document and retried daily.
After the first run
- Compare the versions in the evidence with the file’s Version history in SharePoint.
- Compare the editor list with the file’s Manage access panel.