> 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/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/microsoft-azure-cloud-onboarding/onboard-microsoft-azure.md).

# Onboard Microsoft Azure

Follow the Azure onboarding wizard, and Cortex XDR creates a custom authentication template to be executed in Azure.

Use the cloud onboarding wizard to integrate a Microsoft Azure environment with Cortex XDR. The onboarding wizard requires minimal configuration to set up the integration. To complete the minimum configuration, define the scope of the Microsoft Azure accounts and specify the scan mode. Alternatively, configure the advanced settings for full control of the onboarding process.

Cortex XDR generates a Terraform or ARM authentication template based on the configuration settings. The authentication template establishes trust with Microsoft Azure. The authentication template also grants required permissions to Cortex XDR. Execute the authentication template in Microsoft Azure to complete the onboarding process. Executing the authentication template notifies Cortex XDR of the execution details. Cortex XDR then creates a new cloud instance.

### Onboard Microsoft Entra ID only

You can onboard Microsoft Entra ID independently of a full tenant-level onboarding. When you select the Onboard Microsoft Entra ID only option during onboarding with Tenant scope, Cortex XDR connects to Entra ID to unlock identity-based capabilities, including Cloud Infrastructure Entitlement Management (CIEM), identity posture assessment, and Entra ID sign-in log ingestion. This approach enables identity visibility without requiring Cortex XDR to scan or manage the broader Azure tenant environment.

When you onboard Entra ID only, Cortex XDR operates in collection-only mode. Scan mode selection and scope modification are not available for this configuration. Both Terraform and ARM authentication templates are supported, and manual onboarding is also available. Cortex XDR generates the appropriate authentication template based on your selection, and you execute it in Microsoft Azure to complete the onboarding process.

If you enable audit log collection with Entra ID-only onboarding using automated collection, Cortex XDR ingests sign-in and activity log categories including: SignInLogs, AuditLogs, NonInteractiveUserSignInLogs, ServicePrincipalSignInLogs, ManagedIdentitySignInLogs, ProvisioningLogs, ADFSSignInLogs, and MicrosoftGraphActivityLogs. Administrative category logs are excluded from automated collection. If you configure custom diagnostic settings, log ingestion follows your specified configuration.

You can later expand an Entra ID-only configuration to full tenant scope by editing the onboarding configuration. This approach lets you to begin with identity-focused onboarding and transition to comprehensive tenant coverage as requirements evolve.

### About the Cortex XDR service principal

A service principal is an identity that an application uses to authenticate and interact with Azure resources. When Cortex XDR connects to your Azure tenant, Cortex XDR uses a service principal as its runtime identity in that tenant.

Cortex XDR uses the service principal to:

* Authenticate to your Azure tenant without requiring interactive user sign-in during ongoing operations.
* Operate within the custom roles and scoped permissions you grant, following the principle of least privilege.

When you onboard an Azure tenant for the first time, Cortex XDR checks automatically whether the Cortex service principal already exists in your tenant when you enter your tenant ID in the onboarding wizard. If the Cortex service principal does not yet exist in your tenant, the authentication template creates it when you execute the template. Alternatively, you can create it before you deploy the template by running the Azure CLI command that Cortex XDR displays in the onboarding wizard. The user who creates the service principal must have the Cloud Application Administrator Entra ID role or higher. The Cloud Application Administrator role is required only to create the Cortex service principal. After the service principal exists in your tenant, you do not need this role to complete the rest of the onboarding process. If you onboard with the manual deployment method, you must create the service principal before you save the configuration in the onboarding wizard.

If your tenant is already onboarded to Cortex XDR, the Cortex service principal already exists in your tenant. You don't need to create it again.

### Automated deployment per subscription with Azure policy

Cortex XDR deploys resources into each subscription only when a capability that you enable requires them. The following capabilities require per-subscription resources:

* Agentless Disk Scanning (ADS)
* Data Security Posture Management (DSPM)
* Kubernetes Security Posture Management (KSPM)
* Secret Security Posture and Correlation (Azure Key Vault discovery)

When you onboard an Azure management group or tenant and enable at least one of these capabilities, Cortex XDR uses a native Azure policy with the `deployIfNotExists` effect to deploy the resources. The policy keeps every subscription under that scope covered, including subscriptions that you create after onboarding.

If you enable none of these capabilities, Cortex XDR does not create the policy, the managed identity, or the per-subscription resource group. Registry scanning, serverless scanning, and automation use roles that Cortex XDR assigns once at the management group, so they do not need per-subscription resources. Cortex XDR never deploys the policy when you onboard Microsoft Entra ID only. If you onboarded with an earlier authentication template, see [Remove legacy per-subscription Azure roles](https://cortex-docs.paloaltonetworks.com/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/update-cloud-permissions-after-cortex-release-updates.md#remove-legacy-per-subscription-azure-roles-optional).

#### Why Cortex XDR needs resources in each subscription

The following Azure constraints require Cortex XDR to deploy resources into each in-scope subscription:

* **Ephemeral scan resource containment:** ADS and DSPM create short-lived artifacts during scans. Cortex XDR creates a dedicated resource group (`cortex-{suffix}`) in each subscription for these artifacts. The resource group limits write and delete permissions to that group rather than the whole subscription, and gives you a single container for auditing, cost attribution, and cleanup.
* **Scoped role placement:** DSPM, KSPM, and Secret Security Posture and Correlation use roles with data actions, such as reading blob or file data, reading Kubernetes resources in AKS clusters, and reading Key Vault keys and certificates. Azure doesn't allow custom roles with data actions at the management group level, so Cortex XDR defines and assigns these roles in each subscription.

#### How it works

Cortex XDR uses Azure Policy with the `deployIfNotExists` (DINE) effect, a standard first-party Azure capability. Cortex XDR creates the policy only when you enable ADS, DSPM, KSPM, or Secret Security Posture and Correlation. During onboarding, the authentication template creates the following components at your selected management group (or tenant root management group):

* **Policy definition and assignment:** A custom policy definition and its assignment. The assignment applies to subscriptions only.
* **Managed identity:** A user-assigned managed identity (`cortex-mi-{suffix}`) that is attached to the policy assignment, and its custom role (`cortex-mi-role-{suffix}`). Azure Policy uses this identity to deploy the per-subscription resources.
* **Remediation role:** A custom role (`cortex-policy-{suffix}`) that is assigned to the Cortex XDR service principal. The role allows only reading and creating policy remediation tasks.

Azure then evaluates all current and future subscriptions under that scope on its own schedule, and deploys any missing Cortex XDR resources through its own control plane.

The deployment flow is as follows:

1. Azure Policy detects a non-compliant subscription.
2. The Azure Policy control plane launches the embedded deployment with the managed identity in Incremental mode, adding or updating only Cortex XDR resources.
3. The managed identity creates the `cortex-{suffix}` resource group and the per-subscription resources for the enabled capabilities.

The managed identity holds the privileged write and delete permissions needed for deployment, and only the Azure Policy control plane uses it. Cortex XDR has no access to it.

On first onboarding, Cortex XDR uses the service principal's `remediations/write` permission to trigger an initial re-evaluation. This only re-runs the existing remediation logic and cannot change what gets deployed.

For more information, see the following Microsoft documentation:

* [Azure Policy deployIfNotExists effect](https://learn.microsoft.com/en-us/azure/governance/policy/concepts/effect-deploy-if-not-exists)
* [Remediate non-compliant resources with Azure Policy](https://learn.microsoft.com/en-us/azure/governance/policy/how-to/remediate-resources)
* [Get Azure Policy compliance data](https://learn.microsoft.com/en-us/azure/governance/policy/how-to/get-compliance-data)

#### What Cortex XDR creates in each subscription

Cortex XDR creates the following resources in each in-scope subscription, depending on the capabilities that you enable. Resources are created in the `cortex-{suffix}` resource group or assigned at the subscription. If you enable none of these capabilities, Cortex XDR creates no per-subscription resources.

* **ADS:** A Compute Gallery named `cortex_ads_{suffix}` inside the `cortex-{suffix}` resource group, and a role for ephemeral scan resources that is scoped to the resource group. The Compute Gallery is an empty, no-cost container that holds temporary image versions during scans. Cortex XDR assigns the other ADS roles once at the management group.
* **DSPM:** Roles that read data in storage accounts and other supported data services, assigned at the subscription, and a role for ephemeral scan resources that is scoped to the `cortex-{suffix}` resource group.
* **KSPM:** A read-only role for Kubernetes resources in AKS clusters, assigned at the subscription.
* **Secret Security Posture and Correlation:** A read-only role for Key Vault keys, certificates, and key rotation policies, assigned at the subscription.

{% hint style="info" %}
**Note:** If you onboarded with an earlier authentication template, your existing resources keep their names. When you deploy the updated template, Cortex XDR updates the existing deployment in place.
{% endhint %}

#### Roles and permissions reference

For the complete list of permissions and roles for each capability, see [Microsoft Azure provider permissions](https://cortex-docs.paloaltonetworks.com/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/microsoft-azure-cloud-onboarding/microsoft-azure-provider-permissions.md).


---

# 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/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/microsoft-azure-cloud-onboarding/onboard-microsoft-azure.md?ask=<question>&goal=<user_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.
