Microsoft Purview

Import the data stores Microsoft Purview has classified or labeled, tagged by classification, and your recent Purview DLP alerts into Guard.

The Microsoft Purview integration brings your data-sensitivity context from Microsoft Purview into the Praetorian Guard Platform (PGP). Guard reads the Purview Data Map to find the hosts that store classified or labeled data, tags them in Guard, and imports your Purview data loss prevention (DLP) alerts as risks. This guide walks you through creating a Microsoft Entra application and connecting it to Guard.

What the integration does

Each time the integration runs, Guard signs in to Microsoft with your Entra application and imports two kinds of data.

Sensitive data stores. Guard searches every entity in your Purview Data Map and keeps the ones that carry at least one classification or sensitivity label. Columns are skipped. For each entity, Guard adds the host that stores it, such as a domain, an IP address, or an Amazon S3 bucket, as an asset. Entities whose host is none of these are skipped. Guard tags each asset with:

  • purview
  • purview-classification:<classification> for each classification, for example purview-classification:microsoft.personal.email
  • purview-sensitivity:<label> for each sensitivity label

Tag values are lowercase, with spaces, colons, and slashes replaced by -. When several entities share a host, Guard combines their tags on one asset. Guard also records the Purview entity type, the Purview account name, and the entity ID on the asset. When several entities share a host, Guard keeps these details from the first entity only.

DLP alerts. Guard reads the Purview DLP alerts from Microsoft Graph that were updated in the last 30 days and adds each open alert as a risk. Guard attaches these risks to the Purview integration rather than to a host:

  • The risk's title is the alert title.
  • Its severity follows the alert: high, medium, and low map to the same severity in Guard, and any other level becomes informational.
  • New risks start as Detected. Alerts that were already resolved when Guard first saw them are not imported.
  • Its description comes from the alert, or from the title when the alert has none. A title-less alert is titled Purview DLP policy incident.
  • Guard builds the risk's impact from the alert's severity, category, classification, and determination. The recommendation and reference link come from the alert, and the proof records the alert's IDs, status, classification, determination, and activity times.

Guard re-reads the alerts on every run. When you later resolve an alert or mark it a false positive in Purview, Guard moves its Detected risk to Resolved or Accepted. Statuses you set in Guard take precedence. Guard does not import the alert's evidence or the users involved.

The integration only reads from Microsoft. It does not change classifications, labels, policies, or alerts.

Prerequisites

  • A Microsoft Purview account. You need its account name, the <account> part of <account>.purview.azure.com.
  • Permission in Microsoft Entra ID to register an application and grant admin consent.
  • Permission in Purview to assign roles on the account's root collection.
  • Permission to add integrations in Guard.

Step 1: Register an application in Microsoft Entra ID

  1. In the Microsoft Entra admin center, go to App registrations and create a new registration.
  2. Copy the Application (client) ID and Directory (tenant) ID.
  3. Under Certificates & secrets, create a client secret and copy its value.
  4. Under API permissions, add the Microsoft Graph application permission SecurityAlert.Read.All, then grant admin consent.

Step 2: Give the application read access in Purview

In the Microsoft Purview portal, open the Data Map and assign the application the Data Reader role on your root collection, so it can read every entity. Guard's error messages call this role Data Map Reader.

Step 3: Connect Purview in Guard

  1. In Guard, go to Integrations and open SaaS Security → Purview.
  2. Enter:
    • Purview Account Name: the account name from <account>.purview.azure.com, for example example-purview.
    • Client ID: the application's client ID from step 1.
    • Client Secret: the client secret from step 1.
    • Tenant ID: your directory (tenant) ID from step 1.
  3. Click Connect.

Before saving, Guard signs in with the application, runs a test search of your Purview Data Map, and reads your security alerts from Microsoft Graph. If any check fails, Guard shows the error and does not save the integration.

Verify the integration

After the first run, go to Assets and filter by the purview tag. The hosts that store classified or labeled data should appear. On Vulnerabilities, Purview DLP alerts updated in the last 30 days that were open when Guard first saw them should appear as risks.

Troubleshooting

Message

What to do

Missing Required Field

Enter the client ID, client secret, and tenant ID. An empty account name returns Invalid Format instead.

Invalid Format: Enter a valid Microsoft Purview account name

Enter only the account name, such as example-purview, not the full purview.azure.com URL.

Authentication Failed: Microsoft Purview rejected the supplied tenant ID, client ID, or client secret

Check all three values, and that the client secret has not expired.

Authentication Failed: Microsoft Purview rejected the supplied credentials

Guard signed in, but Purview or Microsoft Graph rejected the token. Check that the application is in the tenant that owns the Purview account.

Insufficient Permissions: cannot search the catalog; assign Data Map Reader on the Purview account

Assign the application the Data Reader role on the root collection, as in step 2.

Insufficient Permissions: cannot read security alerts; grant the application SecurityAlert.Read.All

Add the SecurityAlert.Read.All application permission and grant admin consent, as in step 1.

Connection Failed: Could not reach the Microsoft Purview API

Check that the account name is spelled correctly, then try again.

Validation Failed: Microsoft Purview returned HTTP 400 or 404 during validation

Check the account name, client ID, and tenant ID.

A classified data store is missing from Assets

Its host may not be a domain, IP address, or S3 bucket, or the Data Reader role may not cover its collection.

A DLP alert is missing from Vulnerabilities

It was resolved before Guard first saw it, or it was last updated more than 30 days ago.

If you need help with this integration, contact support@praetorian.com.