A single-page summary of every change the toolkit makes when you run
Deploy-PurviewBestPractice.ps1. Read this before deploying so you (and your
customer) know exactly what will land in the tenant, what is on by default, and what is
explicitly opt-in.
Every change is applied to the tenant. The script asks for confirmation once at
the start (skip with -NonInteractive).
Walks through every step and prints what would happen, without writing anything to the tenant. Use this for change-approval review.
Pauses before each individual change. Useful when migrating an existing tenant and you want to inspect each step.
Skips the preflight confirmation. Combined with -AutoInstallModules
the script runs end-to-end with no human input. Tenant-identity guard still aborts
on mismatch before any write.
Foundational on/off switches: unified audit log, AIP×SPO integration, PDF labels.
Creates 3 label groups (Public is standalone) & 6 assignable children, orders them, applies encryption to Highly Confidential and Confidential\Trusted People, and publishes the user-facing subset.
Two policies block external sharing of Confidential / Highly Confidential content — one for Exchange, one for SharePoint+OneDrive.
7-year retain-then-delete on Exchange mailboxes. Off by default — you must pass -ApplyRetention after confirming the duration matches the customer's vertical.
Blocks Microsoft 365 Copilot from grounding on Highly Confidential content. Default ON for E5 / Purview Suite tenants; auto-skipped on Business Premium.
| Setting | Value | Mode | What it does in your tenant |
|---|---|---|---|
| Unified Audit Log | Enabled | Default | Turns on the cross-workload activity log used by every Purview investigation, eDiscovery and DLP report. |
| AIP integration in SharePoint Online | Enabled | Default | Lets SPO/OneDrive open, index and search content encrypted by sensitivity labels. |
| Sensitivity label for PDF | Enabled | Default | Office can apply (and persist) sensitivity labels when saving as PDF. |
| Label co-authoring | Enabled | -EnableLabelCoAuthoring | Tenant-wide switch that lets multiple users edit encrypted Office files at once. One-way change — disabling it later loses labels on unencrypted Office files, breaks third-party tools that read labels from the old metadata location (AIP scanner < v3.0, OneDrive sync < 19.002, MIP SDK < 1.7, custom DLP scanners, custom Exchange mail-flow rules). Off by default. |
| Container labels (Teams / Sites / Groups) | Group.Unified.EnableMIPLabels | Default | Lets sensitivity labels be applied to M365 Groups, Teams and SharePoint sites. Requires Microsoft Graph beta consent. Enabled by default on every run — Business Premium is the toolkit's licensing floor and BP includes Entra ID P1, the AAD-side requirement. Pass -SkipContainerLabels to opt out. License auto-detect skips it automatically when the tenant has no recognised M365 BP/E5/Purview Suite SKU. |
| Premium audit (mailbox SearchQueryInitiated) | per-mailbox | -EnablePremiumAudit | Adds the SearchQueryInitiated audit event to nominated mailboxes. Requires E5 / Audit (Premium) licensing. |
Ten labels — Public plus three label groups (General, Confidential,
Highly Confidential), each with two assignable children — ordered from least sensitive
(top) to most sensitive (bottom). Labels are identified/created by Microsoft's stable
internal signature so the same taxonomy lands correctly on any tenant, locale, or label
scheme (classic or modern). Encryption is intentionally only applied to
Highly Confidential\All Employees (Template), Highly Confidential\Specific
People and Confidential\Trusted People (both UserDefined); every other
label carries footer/watermark marking only, which is the SMB-friendly profile that
minimises breakage with third-party tooling.
The Applies to line under each label reflects the scope the script sets.
The four published labels (Public,
General — Anyone (unrestricted),
Confidential — All Employees,
Highly Confidential — All Employees) are the only ones shown in the
Office Sensitivity picker; the other three (General \ All Employees
(unrestricted), Confidential \ Trusted People, Highly
Confidential \ Specific People) are created so DLP can match on them but stay off
the client UI. Of the published set, General — Anyone (unrestricted),
Confidential — All Employees and
Highly Confidential — All Employees ship with
Files · Emails · Groups & sites so they appear in the
Sensitivity picker when a user creates a new Team, M365 Group or SharePoint site;
every other label starts at Files · Emails only. Pass
-SkipContainerLabels to drop the Groups & sites bits
(labels still ship with Files & Emails). You can widen any label later in the
Purview portal without losing the deployment baseline — adoption uses
UNION-not-replace, so any scope you add by hand is preserved on the next re-run.
The colored dot beside each label name matches the per-label
Color the script writes to the label (with drift correction
on re-run). Operators see this same color in the Purview portal and end
users see it on the Sensitivity button in Word, Excel,
PowerPoint and Outlook.
EncryptionRightsDefinitions in PurviewConfig.psd1;
labels without an override fall back to the global default. Edit either
and validate in a pilot tenant before rolling out.
EnableContentMarking = $true in PurviewConfig.psd1.
This lets you stage the rollout without surprising end-users.
All ten labels are created in the tenant.
Only the labels below are published to end users via the
SMBTool - Default Label Policy. Sub-label names are auto-expanded to include their
parent so the Purview hierarchy stays valid.
| Setting | Value | What it means for end users |
|---|---|---|
| Published labels | Public · General / Anyone (unrestricted) · Confidential / All Employees · Highly Confidential / All Employees | The four labels that appear in the Office "Sensitivity" picker for every licensed user. |
| Default for documents | Confidential / All Employees | Every new Word, Excel and PowerPoint document is automatically tagged so it carries the Confidential footer. |
| Default for email | General / Anyone (unrestricted) | Every new Outlook message is pre-tagged General so routine internal mail doesn't trigger DLP. General itself is a non-applicable label group. |
| Inherit label from attachments ON | AttachmentAction = 'Automatic' |
If an outgoing email has a labelled attachment with a higher-priority label than the email's current label, Outlook silently upgrades the email to match — no prompt. |
| Mandatory labelling ON | $true |
Office prompts the user to pick a sensitivity label before saving a new document or sending a new email. Closes the untagged-content hole that breaks DLP, auto-classification and Copilot exclusions. |
| Downgrade justification ON | $true |
Users must give a written reason when downgrading a label (e.g. Confidential → General). |
Both policies start in simulation (TestWithoutNotifications) with Purview's native "Turn the policy on if it's not edited within fifteen days of simulation" flag set. Purview itself owns the countdown; the toolkit does not auto-enforce.
-BPOnly.Retains every mailbox item for 7 years from creation, then permanently deletes it tenant-wide.
Off by default — you must pass -ApplyRetention. The 7-year
default is wrong for some regulated verticals (law, accounting, healthcare, financial advisors,
construction, real estate); confirm against the customer's record-keeping obligations before enabling.
Prevents Microsoft 365 Copilot (paid & free Copilot Chat) from grounding, summarising or returning search results from any document or email labelled Highly Confidential.
/subscribedSkus).-BPOnly),
because the Copilot DLP location is not licensed there.-SkipAIControls on any tenant.The script can be re-run any number of times. Existing labels, policies and rules created by the toolkit are updated in place, not duplicated.
Every object the toolkit creates carries [Managed by SMBTool Purview Toolkit] in
its description. Untagged objects are left alone unless you pass -AdoptExisting.
After sign-in the script checks the connected tenant's verified domains against the expected
domain (from -DelegatedOrganization or your admin UPN suffix). On mismatch the
script aborts before any write.
DLP policies are created in TestWithoutNotifications by default. Validate in DLP Activity
Explorer first, then let Purview's 15-day flag flip them to enforce — or set
DlpStartInSimulation = $false in the config to enforce immediately.
Each invocation writes an offline plan from config and switches. It includes fingerprints,
action intent, the supplied Good / Better / Best SMB guide comparison, and a separate
Microsoft Learn supporting reference. A short plan reference identifies the HTML and JSON
pair. The JSON carries a sanitized intended-state snapshot for a dependent stacked
tenant-validation feature. It remains private customer-sensitive evidence because configured
names needed for matching can appear. The snapshot uses the canonical
Microsoft365Copilot token for the public Copilot location, opaque digests for
custom AI locations, records unsupported retention destinations separately, and rejects malformed
built-in label signatures before sign-in.
The plan does not inspect tenant state or declare compliance.
The Action Preview labels the guide tiers as
Deployment Priority Level values: Priority 1 (Good), Priority 2 (Better), and Priority 3
(Best), and includes a closed explanation panel for intent, priority, and comparison terms.
Good includes audit, baseline labels, container and SharePoint/OneDrive label enablement,
and core DLP; Better adds Exchange retention; Best adds advanced DLP, auto-labeling,
encryption, custom SITs, and DSPM. Unassigned capabilities are labeled as toolkit
extensions.
Test-PurviewTenantConfiguration.ps1 is a separate command you run later. It reads the
tenant and compares it with schema 1.2 intended state, or runs a guide-only assessment, reporting each action as Matched, Drift,
Not evaluated, Informational or Collection failed. It changes nothing and it is not a
compliance assessment. It also refuses a Graph token with resource permissions beyond its two documented read scopes; retry from a fresh PowerShell session first, then use an approved isolated public client if the shared Graph client still returns broader consent.
Each run writes Deploy-PurviewBestPractice-Report-<timestamp>.html and a
machine-readable .json sidecar to the selected output location. This separate
report records what the tenant deployment actually did.
The report HTML-encodes every value and strips any parameter whose name matches password / token / secret / credential / key, so logs are safe to email.