> 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/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope.md). # Azure Manual Onboarding: Management group or tenant scope This guide walks you through manually creating the required Azure resources for the Cortex integration at the management group scope or tenant/root management group scope using az CLI commands. Both flows are nearly identical, differing only by the value assigned to the single variable `` used throughout: | Scope | Value of `` | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Management group |

The management group's name (NOT displayName). To view the name, run:
az account management-group list -o table

| | Tenant | Azure Entra tenant ID. The tenant ID is also the name of the root management group. | ### Target deployment scopes For your reference, the resource paths and scopes used throughout this guide are constructed as follows: | Scope | Resource path | | ---------------- | ----------------------------------------------------------------- | | Management group | `/providers/Microsoft.Management/managementGroups/` | | Subscription | `/subscriptions/` | | Resource group | `/subscriptions//resourceGroups/` | *** ## Overview of the onboarding process The following table lists every step in the procedure for manually onboarding Microsoft Azure. Use it as a checklist to track your progress. Steps marked as Required must be completed for every onboarding. Optional steps depend on the Cortex security capabilities you choose to enable. | Step | Procedure | Required? | Required for capability | Platform | | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------------- | -------- | | **Prerequisites** | | | | | | P.1 | [P.1 Cortex service principal](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/prerequisites.md) | Required | | Azure | | **Phase 1: Create Azure cloud instance in Cortex** | | | | | | 1.1 | [Start the Azure onboarding wizard](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-1-create-azure-cloud-instance-in-cortex.md) | Required | | Cortex | | 1.2 | [Download the customized identifiers file](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-1-create-azure-cloud-instance-in-cortex.md) | Required | | Cortex | | **Phase 2: Deploy identity and base role** | | | | | | 2.1 | [Grant Microsoft Graph API application permission to the Cortex service principal](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-2-platform-identity-and-base-role.md) | Required for tenant scope only. Skip for MG scope. | | Azure | | 2.2 | [Create the Cortex-Platform-Base custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-2-platform-identity-and-base-role.md) | Required | Assets Discovery | Azure | | 2.3 | [Assign Cortex-Platform-Base at the root management group scope](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-2-platform-identity-and-base-role.md) | Required | Assets Discovery | Azure | | 2.4 | [Create the Cortex-Asset Discovery-Data custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-2-platform-identity-and-base-role.md) | Required | Assets Discovery | Azure | | 2.5 | [Assign Cortex-AssetDiscovery-Data](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-2-platform-identity-and-base-role.md) | Required | Assets Discovery | Azure | | **Phase 3: Create security capability roles** | | | | | | 3.1 | [DSPM- Data Security Posture Management](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.1.1 | [Create the Cortex-DSPM custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.1.2 | [Assign the Cortex-DSPM custom role at root management group](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.1.3 | [Create the Cortex-DSPM-Data custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.1.4 | [Provision the Cortex resource group and the Cortex-DSPM-RG custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.1.5 | [Assign the three subscription-level DSPM roles to each child subscription](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | DSPM | Azure | | 3.2 | [ADS-Agentless Disk Scanning](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.2.1 | [Create the Cortex-ADS custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.2.2 | [Assign the Cortex-ADS custom role at root management group](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.2.3 | [Create the shared image gallery](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.2.4 | [Create the Cortex-ADS-RG custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.2.5 | [Assign Cortex-ADS-RG custom role at the resource group scope](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | ADS | Azure | | 3.3 | [Registry Scanning](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Registry Scanning | Azure | | 3.3.1 | [Create the Cortex-Registry custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Registry Scanning | Azure | | 3.3.2 | [Assign the Cortex-Registry custom role at the root management group scope](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Registry Scanning | Azure | | 3.4 | [Automation](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Automation | Azure | | 3.4.1 | [Create the Cortex-Automation custom role for the control plane only](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Automation | Azure | | 3.4.2 | [Assign the Cortex-Automation custom role at the root management group scope](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Automation | Azure | | 3.4.3 | [Create the Cortex-Automation-Data custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Automation | Azure | | 3.4.4 | [Assign the Cortex-Automation-Data custom role to each child subscription](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Automation | Azure | | 3.5 | [Serverless Scanning](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Serverless Scanning | Azure | | 3.6 | [Kubernetes Security](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Kubernetes | Azure | | 3.6.1 | [Create the Cortex-KSPM custom role](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Kubernetes | Azure | | 3.6.2 | [Assign the Cortex-KSPM custom role to each child subscription](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-3-create-security-capability-roles.md) | Optional | Kubernetes | Azure | | **Phase 4: Connect audit logs** | | | | | | 4 | [Audit Logs](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.1 | [Create the shared resource group in the host subscription](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.2 | [Create the user-assigned managed identity (UAMI)](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.3 | [Configure workload identity federation for the UAMI](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.4 | [Create the storage account](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.5 | [Grant the UAMI Storage Blob Data Contributor role on the storage account](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.6 | [Create and secure the Event Hubs namespace](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.7 | [Create the Event Hub](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.8 | [Create an authorization rule on the namespace](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.9 | [Create the consumer group](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.10 | [Grant the UAMI Azure Event Hubs Data Receiver role on the namespace](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.11 | [Route the (Root) management group's Activity Log to the shared Event Hub](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | 4.12 | [Create the tenant-level Microsoft Entra ID diagnostic settings](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-4-audit-logs.md) | Optional | Audit Logs | Azure | | **Phase 5: Complete the onboarding wizard** | | | | | | 5.1 | [Enter the Azure details in Cortex](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-5-complete-the-azure-onboarding-wizard-in-cortex.md) | Required | | Cortex | | 5.2 | [Azure value reference guide](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-5-complete-the-azure-onboarding-wizard-in-cortex.md) | Reference | | Cortex | | 5.3 | [Complete onboarding](/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope/phase-5-complete-the-azure-onboarding-wizard-in-cortex.md) | Required | | Cortex | *** ## 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 Cloud 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 Cloud to scan or manage the broader Azure tenant environment. If you enable audit log collection with Entra ID-only onboarding, Cortex 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. ### Required steps for Microsoft Entra ID only onboarding * **Phase 1:** Select the Onboard Microsoft Entra ID only option during onboarding with Tenant scope. * **Phase 2:** Execute only step 2.1 (Grant Microsoft Graph API Application Permissions to the Cortex service principal). * **Phase 3:** Skip the entire phase. * **Phase 4:** Execute all of phase 4 except for step 4.11 (Route the (Root) management group's Activity Log to the shared Event Hub) * **Phase 5:** Execute all of the steps. *** ## Prerequisites > **Note:** Custom roles containing `DataActions` cannot be assigned directly at the management group scope. However, Microsoft allows these roles to include a management group in their `AssignableScopes`, provided they are assigned at the subscription scope. This guide strictly follows this supported pattern. 1. Ensure `az cli` is installed and authenticated. 2. Ensure you have the necessary permissions: * In Cortex, you must have a Cortex role with Data Sources - View & Edit permissions (to add/configure cloud accounts in Cortex). This role is included in the following built-in roles: Instance Administrator, Security Admin, and IT Admin. * In Microsoft Azure, to create the service principal and assign the required `Application.Read.All` Microsoft Graph permission to Cortex, the onboarding user must have the Application Administrator built-in Entra ID role. 3. Create the Cortex service principal. 4. Decide on your resource naming convention. Throughout this manual onboarding process, you will need to choose your own names for the resource group, custom roles, Event Hub namespace, storage account, UAMI. Use the Configuration values reference to keep track of the names as you will need to refer to them throughout the process. 5. Gather and record the following required Azure deployment variables. You will need to substitute these values throughout the configuration steps. | Variable | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | Your Microsoft Entra ID tenant ID. | | `` |

For MG onboarding: the child management group's name (not its displayName). Run az account management-group list -o table to find it.
For tenant root management group onboarding: the tenant ID (same value as \). The tenant ID is also the root MG name.

| | `` | A stable, long-lived subscription under the target management group to host the audit logs infrastructure (Event Hub, UAMI, and Storage Account). Required only if audit log collection is enabled. | ### P.1 Create the Cortex service principal The Cortex service principal is Cortex's primary runtime identity in your tenant. It is the identity that all subsequent custom role assignments bind to and Cortex uses it to read your Azure resources and perform actions for the capabilities you enable. When you enter your Azure tenant ID in the onboarding wizard, Cortex checks whether this service principal already exists in your tenant. If it does, no action is needed. If it is not found, you must create it: 1. Open Azure Cloud Shell in the tenant you are onboarding, or open a local terminal with the Azure CLI installed, and log in to the target tenant before executing the command below. 2. Run the following command: ```bash az ad sp create --id ``` Where `` is the tenant ID of your Azure tenant. *** --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/microsoft-azure-manual-onboarding/azure-manual-onboarding-guide/azure-manual-onboarding-management-group-or-tenant-scope.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.