> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/data-security-documentation/cortex-data-security-data-sources-and-connectors/vendor-specific-data-sources-and-connectors/microsoft/microsoft-security.md).
# Microsoft Security
Use Microsoft Security data with Cortex Data Security.
{% hint style="warning" %}
## **Beta**
Data Loss Prevention - Policies Discovery is currently in beta.
{% endhint %}
This connector includes the following capabilities and sub-capabilities:
* **Data Loss Prevention**
* **Policies Discovery:** Discover the Microsoft Purview DLP policies, normalize them into the Cortex DLP schema, and list them alongside every other connected DLP provider on the Unified Policies page. This sub-capability is available to tenants on the Cortex Data Security (D1), Cortex XSIAM Premium (X5), or Cortex Cloud Runtime Security (C3) tenants, or tenants with the Data Security add-on
Setting up the connector required running a script that Cortex generates for you in Azure Cloud Shell.
### What Cortex collects
Cortex re-scans Purview every 12 hours and picks up new, updated, and deleted policies without user intervention. Each policy becomes an asset in the Cortex Data Inventory, carrying its rules, detection conditions, data profiles, channels, origins, actions, and audit metadata. See [DLP harmonization](/data-security-documentation/data-security/dlp-harmonization.md) for more information about how the collected data is stored and made accessible in Cortex.
If you disable the connector, the policies already collected remain in the inventory but are no longer updated, and they are deleted 30 days after the last successful scan.
### About the script
Cortex generates a PowerShell script in the connector wizard. You run it once in Azure Cloud Shell to create a read-only application identity in Microsoft Entra ID, then enter the credentials it prints back into the connector.
What the script creates and the access it grants
The generated script creates a single application identity in your Entra ID directory. It creates the following:
* One Entra ID application registration, single-tenant, named `panw-purview-dlp-collector-`
* One service principal for that application
* Seven read-only application API permissions, with administrator consent granted as the script runs
* One client secret
No Azure resources are created.
The permissions it requests are the following:
| API | Permission | Purpose |
| -------------------------- | ------------------------ | ---------------------------------------------------------------- |
| Microsoft Graph | `Group.Read.All` | Read all groups. |
| Microsoft Graph | `Organization.Read.All` | Read organization information. |
| Microsoft Graph | `SecurityAlert.Read.All` | Read all security alerts. |
| Microsoft Graph | `User.Read.All` | Read all users' full profiles. |
| Office 365 Exchange Online | `Exchange.ManageAsApp` | Required for application-only, read-only access to DLP policies. |
| Office 365 Management APIs | `ActivityFeed.Read` | Read activity data for the organization. |
| Office 365 Management APIs | `ActivityFeed.ReadDlp` | Read DLP policy events, including detected sensitive data. |
The script also assigns the application the **Compliance Data Administrator** directory role, which is what allows it to read the DLP policy configuration. The role grants read access to compliance data only.
With these permissions, the application can read DLP policy and rule definitions, DLP policy events and detected sensitive-data matches, security alerts raised in the tenant, and the user, group, and organization information needed to attribute an event to the identity it came from. It cannot read the contents of files, mail items, chats, or documents, and it cannot read mailboxes, SharePoint sites, or OneDrive content.
The script requests a client secret with a 24-month lifetime. If a credential lifetime policy in your directory rejects that, it retries with 12, 6, and then 3 months, and reports the lifetime it was granted along with the expiry date.
{% hint style="warning" %}
**Important:** The connector stops collecting data when the secret expires. You must keep track of the secret's remaining lifetime and update it when necessary.
{% endhint %}
{% hint style="info" %}
**Note:** Each run of the script deletes and recreates the application. The Application ID and secret change on every run, and any credential issued by a previous run stops working immediately. Re-running is the supported way to recover from a failed or partial run, but if Cortex is already collecting from this directory, collection stops until you supply the new values.
{% endhint %}
To revoke this access at any time, delete the application registration in **Microsoft Entra ID → App registrations**. Access ends immediately.
### Prerequisites
The following are required before you start:
* **Global Administrator access to the Azure portal.** Sign in to the Microsoft Azure portal as a Global Administrator of the directory you want to connect. Creating an application and granting administrator consent for its API permissions both require this role. If the role is PIM-eligible, activate it before you begin. The script checks for the role but does not require it: if it cannot confirm Global Administrator, it prints a warning and continues, then stops with an error at whichever step the missing permission first blocks.
* **The following values from your Azure tenant.** Both are on the tenant properties page in the Azure portal:
* **Tenant ID:** The directory (tenant) ID of the Microsoft Entra ID directory that holds your Purview policies.
* **Domain name:** The initial domain of that directory, in the form `.onmicrosoft.com`.
### How to configure the Microsoft Security connector
To configure this connector, follow these steps:
#### Task 1. Add the connector and generate the script
1. In Cortex, navigate to **Settings** → **Data Sources & Integrations**.
2. Click **+ Add new**.
3. On the **Add Data Source** page, search for **Microsoft Security**, hover over it, and click **Add**.
4. On the **Services** page, select **Microsoft Purview**, then click **Next**.
5. On the **Capabilities** page:
1. Enter a unique name for the new connector instance.
2. Under **Select capabilities**, select **DLP Orchestration** and **Policies Discovery**.
3. Click **Next**.
6. On the **Connection** page:
1. Enter the **Tenant ID** and **Initial domain name**.
2. Click **Generate** to generate the script.
3. The script is generated and displayed in a text field below. Click the download icon above the text field to download the script.
To complete the setup now, proceed to task 2.
If you want to run the script later, you can leave the setup in a pending state and return to it when you're ready. To do so:
1. Leave the **Confirm script execution** toggle off.
2. Click **Save**.
3. Click **Next**.
4. On the **Summary** page, verify that the table lists the **DLP Orchestration** capability with a **Verification Pending** status.
5. Click **Create instance**.
The incomplete instance configuration is saved and you can reopen it to finish the setup once the script has run.
#### Task 2. Run the script in Azure Cloud Shell
1. Open the [Microsoft Azure portal](https://portal.azure.com/) and sign in with a Global Administrator account.
2. Click the account avatar in the top-right corner and confirm that the directory shown matches the one the script expects. If it does not, click **Switch directory** and select the correct one. The script also verifies this and stops if the directory is wrong.
3. Click the Cloud Shell icon (**>\_**) in the top toolbar, or go to .
4. When prompted to choose **Bash** or **PowerShell**, choose **PowerShell**. If a session is already open in Bash, switch it using the environment dropdown at the top-left of the Cloud Shell pane.
5. On first use only, Cloud Shell displays a **Getting started** dialog. Either storage option works for this script; **No storage account required** is sufficient. A subscription must be selected even when no storage account is used, because Cloud Shell needs one to start a session. The script creates nothing in it. Click **Apply** and wait for the `PS /home/>` prompt.
6. In the Cloud Shell toolbar, click **Manage files** → **Upload**, and select the script file. Wait for the upload to complete. The file is placed in your home folder.
7. Confirm that the upload succeeded:
```powershell
Get-ChildItem $HOME/Cortex-Purview-Onboarding.ps1
```
The file should be listed with a size greater than zero.
8. Run the script:
```powershell
cd $HOME
./Cortex-Purview-Onboarding.ps1
```
If `./` is not recognized, run `& "$HOME/Cortex-Purview-Onboarding.ps1"` instead.
The script runs for one to two minutes.
9. When the script finishes, copy the three values it prints under **Enter the following values in the Microsoft Security connector**:
* **Application ID**
* **Secret ID**
* **Secret Value**
The script also prints a JSON block recording everything it created. Keep it: it identifies the application in your directory later and is useful if you contact Palo Alto Networks support. Treat it as a credential, because it contains the secret value in full. There is no obligation to share the secret value with support; Palo Alto Networks does not need it.
10. Close the Cloud Shell session once the values have been copied. The secret value stays visible in the terminal scrollback until you do.
{% hint style="info" %}
**Note:**
* The secret value is displayed once and cannot be retrieved again. If it is lost, re-run the script to issue a replacement. Because each run recreates the application, the new run prints a new Application ID and Secret ID as well; enter all three values again.
* Allow ten minutes after the script finishes for the directory role assignment to take effect across Microsoft's services before collection can succeed.
* In the Azure portal, the role assignment shows an empty **Start time**. That column is filled in only for assignments made manually through the portal and says nothing about whether the role is active. The row reading **Assigned / Direct / Permanent** is what confirms it.
* Some directories restrict programmatic role assignment. If the script cannot assign the **Compliance Data Administrator** role, it does not fail; it prints step-by-step portal instructions at the end. Everything else is already in place, and the three values it printed stay valid once you complete the assignment manually.
* If the script fails, it stops without changing anything further and prints an Azure error code and a **Request ID**. It is safe to re-run. If the problem persists, send the entire failure message, including the Request ID, to your Palo Alto Networks contact.
{% endhint %}
#### Task 3. Complete the connection
{% hint style="warning" %}
**Important:** Before proceeding with this task, ensure you have waited 10 minutes after running the script for the directory role assignment to take effect.
{% endhint %}
1. Return to the **Connection** page of the connector wizard. If you closed the wizard, reopen the pending connector from **Settings** → **Data Sources & Integrations**.
2. Turn on the **Confirm script execution** toggle to enable the credential fields.
3. Enter the values printed by the script:
* **Application ID**
* **Secret ID**
* **Secret Value**
4. Click **Save**.
5. Click **Next**.
6. On the **Summary** page, verify that the table lists the **DLP Orchestration** capability with a **Verified** status.
If the connection can't be completed successfully, the interface shows a warning status for he connector, along with a description containing the reason and required remediation actions. Possible causes are a secret that was mistyped or has expired, a script run that ended with a permission error, and a role assignment that has not yet propagated. If you re-run the script to reissue a credential, it recreates the application. You'll need to enter the new **Application ID**, **Secret ID**, and **Secret Value** together, because all three change.
7. Click **Create Instance**.
{% hint style="info" %}
**Note:**
* Data profiles marked as irrelevant to your environment are omitted from the inventory. Change this in the [data profile settings](https://cortex-docs.paloaltonetworks.com/data-security-documentation/data-security/data-classification/what-is-cortex-data-classification), not in Unified Policies.
* A policy deleted in Purview disappears from the inventory on the next scan.
{% endhint %}
### AURL enrichment
Advanced URL (AURL) enrichment extends our internal link analysis capabilities by using real-time machine learning and redirect tracing to generate alerts with specific threat verdicts and defanged links. AURL enrichment is enabled by default, but you can disable it and rely exclusively on the baseline link checking by toggling Settings > Configuration > Cortex Analytics > "Enable phishing analysis for SaaS”.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://cortex-docs.paloaltonetworks.com/data-security-documentation/cortex-data-security-data-sources-and-connectors/vendor-specific-data-sources-and-connectors/microsoft/microsoft-security.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.