== Authorize Prisma Cloud to access Azure APIs

Connecting Prisma Cloud to your Azure cloud account enables you to analyze and monitor traffic logs, and detect potential malicious network activity or compliance issues. During the built-in onboarding process you have the option of using one of the following three methods to create the required Azure resources to authorize Prisma Cloud to access Azure APIs:

* <<terraform>> (Recommended) 
This workflow automates the process of setting up the Prisma Cloud application on Azure Active Directory and enables read-only or read-write access to your Azure subscription.

[NOTE]
====
Azure China workflows do not support the use of Terraform templates.
====
* <<json>>
Using a manually created Custom Role you also have the option to enforce least access privilege to restrict access. To achieve this you will need to manually set up the Prisma Cloud application on Active Directory and Create a Custom Role to authorize access to Azure APIs. 
* <<manual>>
If your organization restricts the use of Terraform scripts, you can choose to manually create the required Azure resources for Prisma Cloud to call the Azure APIs.

[.task]
[#terraform]
=== Automated Terraform Script for Tenant Workflow

Follow the steps below to use the Automated Terraform script method to create the Azure Tenant resources for Prisma Cloud onboarding. 

[.procedure]
. Before you begin, ensure your system has Terraform installed and that it is also authenticated to Azure via the CLI.
. Download the Terraform script using Prisma Cloud Azure Onboarding User Interface or Azure Template Generation API.
+
[NOTE]
====

We recommend that you create a directory to store the Terraform template you download. This allows you to better manage the templates when you add new Azure resources to Prisma Cloud or update existing roles. Give this directory a unique name for example, _onboard-tenant-<tenant-name>_.
====
. Run the command *terraform init > terraform apply* and click *Confirm*.
. This generates outputs with the following values: 
+
image::connect/so-az-automate-tenant.png[] 
+
Input these Terraform Output Key values in the associated UI fields as indicated:
+
* Application (Client) ID: b_application_id
* Application Client Secret: c_application_key
* Enterprise Application Object ID: e_service_principal_object_id

. Use the Azure portal to *Grant admin consent* for API permissions. This authorizes Prisma Cloud to access Azure resources. This is required to ingest Azure resources associated with subscriptions and management groups, only during the initial onboarding of your Azure accounts. 
.. On your Azure portal, clink on the *e_consent_link* to be redirected to the API permissions section.
.. Click on *Grant admin consent* and select *Yes*. A success message appears indicating *Grant Consent successful*.
.. Verify that the status column has green check marks.
+
image::connect/so-az-authorize-permissions.png[] 

[.task]
=== Automated Terraform Script for Subscription Workflow

Follow the steps below to use the Automated Terraform script method to create the Azure Subscription resources for Prisma Cloud onboarding. 

[.procedure]
. Before you begin, ensure your system has Terraform installed and that it is also authenticated to Azure via the CLI.
. Download the Terraform script using Prisma Cloud Azure Onboarding User Interface or Azure Template Generation API.
+
[NOTE]
====
We recommend that you create a directory to store the Terraform template you download. This allows you to better manage the templates when you add new Azure resources to Prisma Cloud or update existing roles. Give this directory a unique name that indicates its purpose, for example, _onboard-subscription-<subscription-name>_.
====
. Run the command _terraform init > terraform apply_ and click *Confirm*.
. This generates outputs with the following values as shown below: 
+
image::connect/so-az-automate-subscription.png[]
+
Input the following Terraform Output Key values in the associated UI fields as indicated:
+
* Application (Client) ID: c_application_id
* Application Client Secret: d_application_key
* Enterprise Application Object ID: e__enterprise_application_object_id

==== Terraform for Active Directory Workflow

Follow the steps listed under the Tenant flow above. For step 2, remember to name the directory you use to store your Terraform template something intuitive such as, _onboard-active-directory-<tenant-name>_.

[.task]
[#json]
=== Custom Roles to Authorize Prisma Cloud Access

In addition to the automated Terraform authorization method, you also have the option to create a custom role so that you can enforce the principal of least access privileges to limit user access to the bare minimum. To create a custom role on Azure, you must have an Azure Active Directory Premium 1 or Premium 2 license plan.

[.procedure]
. Create a custom role using Azure CLI. You can create custom roles using Azure PowerShell, Azure CLI, or the REST API. The following instructions use the Azure CLI command (run on PowerShell or on the DOS command prompt) to create the custom role.

. https://docs.microsoft.com/en-us/cli/azure/install-azure-cli[Install the Azure CLI] and log in to Azure.

. Download the JSON files which contains the permissions:
+
* https://redlock-public.s3.amazonaws.com/azure/azure_prisma_cloud_lp_read_only.json[Commercial]
* https://redlock-public.s3.amazonaws.com/azure/azure_prisma_cloud_read_only_role_gov.json[Government]
* https://redlock-public.s3.amazonaws.com/azure/azure_prisma_cloud_read_only_role_china.json[China]

+
[NOTE]
====
Microsoft recommends using a wildcard to configure NSG flow log permissions (Microsoft.Network/networkWatchers/queryFlowLogStatus/*), listed in the JSON files. Refer to https://docs.microsoft.com/en-us/azure/network-watcher/required-rbac-permissions#nsg-flow-logs[Microsoft documentation] for more details.
====
. Open a text editor (such as Notepad) and save the custom role JSON files from the above links in the JSON format and give it a descriptive name.
. Depending on whether you are creating a custom role for the Tenant or Subscription workflow, complete the following steps:
.. Tenant Workflow: Edit the saved custom role JSON file in a text editor and update the value for AssignableScopes with the value below and save your changes:
+
[userinput]
----
AssignableScopes": [
  "providers/Microsoft.Management/managementGroups/<tenant-id>"
  ]
----
+
.. Subscription Workflow: Edit the saved custom role JSON file in a text editor and update the value for AssignableScopes with the value below and save your changes:
+
[userinput]
----
AssignableScopes": [
     "/subscriptions/<subscription-id>"
  ]
----
. Log in to the Azure portal from the same local system where the JSON file was saved and complete the following steps:
.. Open a PowerShell window or a DOS Command Prompt Window.
.. Go to the directory where you stored the JSON file.
.. Enter the following Azure CLI command (replacing the JSON filename to match the name of your custom role JSON file): 
... Commercial
+ 
[userinput]
----
az role definition create --role-definition "azure_prisma_cloud_lp_read_only.json"
----
... Government 
+
[userinput]
----
az role definition create --role-definition "azure_prisma_cloud_read_only_role_gov.json"
----
... China 
+
[userinput]
----
az role definition create --role-definition "azure_prisma_cloud_read_only_role_china.json"
----
+
The command generates the sample output below indicating successful creation of a custom role:
+
[%collapsible]
[, json]
----
{"assignableScopes": [    "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  ], 
 "description": "Allows Reading Flow Logs Settings", 
 "id": "/subscriptions/16dfdbcc-e407-4fbe-9096-e7a97ee23fb5/providers/Microsoft.Authorization/roleDefinitions/088c8f48-201c-4f8d-893f-7716a8d58fa1",  "name": "088c8f48-201c-4f8d-893f-7716a8d58fa1",  
 "permissions": [{      "actions": [        "<a list of all actions>"],      "dataActions": [],      "notActions": [],      "notDataActions": []    }],  "roleName": "Flow Log Settings Reader",  "roleType": "CustomRole",  "type": "Microsoft.Authorization/roleDefinitions"]
----
 

[.task]
==== Assign the Custom Role

Complete the following steps to *assign the custom role to an app registration*, add role assignments and configure it to access the flow logs:

[.procedure]
. Log in to the Microsoft Azure Portal.
. Follow the navigation path for your selected workflow:
.. Tenant scope:  Navigate to *All Services > Management Groups*. Click on *Tenant Root Group*.
.. Subscription scope:  Navigate to *All services > Subscriptions*
. Select *Access control (IAM) > Add role assignment*.
. Verify that you can see the newly created custom role in the *Roles* drop-down.
+
image::connect/so-az-authorize-custom-role-tenant.png[]
. Assign the custom role to the Prisma Cloud app registration. Enable the permission to query flow log status and save your changes.


[#manual]
=== Manually Authorize Prisma Cloud

If your organization restricts the use of Terraform templates, you also have the option to manually onboard your Azure Active Directory (AD), Government or Azure China account resources to Prisma Cloud by creating an app registration (service principal) on Azure. Here is a preview of the required steps based on your chosen onboarding flow:

==== *Azure Tenant*

* Create a custom role at the tenant level.
* Assign IAM roles at the tenant root level. 
* Assign GraphAPI permissions at the tenant level.
* Grant admin consent for Azure AD Graph APIs.

==== *Azure Subscription*

* Create a custom role at the Subscription level.
* Assign IAM roles at the subscription level.

==== *Azure Active Directory*
* Assign GraphAPI permissions at the tenant level.
* Grant admin consent for Azure AD Graph APIs.


==== Prerequisites

* A Prisma Cloud tenant with permissions to onboard a cloud account.
* Access the https://portal.azure.com[Azure portal] with permissions to register an application and create and assign roles.

[.task]
==== Steps

[.procedure]
. Elevate access for a https://learn.microsoft.com/en-us/azure/role-based-access-control/elevate-access-global-admin#elevate-access-for-a-global-administrator[Global Administrator] on the Azure portal. This allows Prisma Cloud to access Azure subscriptions or management groups. This is required for ingesting resources associated with subscriptions and management groups only during the initial onboarding of your Azure accounts. You have the option to disable this after onboarding is complete. 

. Follow the steps below to *Register a new application*.
+
.. Log in to https://portal.azure.com[Azure portal].

.. Select *Azure Active Directory[App registrations > + New registration]*.

.. Enter the application name.

.. Select the supported account types.
+
Choose from single tenant, multitenant, multitenant and personal Microsoft accounts, or personal Microsoft accounts only.

.. tt:[Optional]—Enter the Redirect URI.
+
The authentication response of the app will be returned to this URI.

.. Click *Register*.

.. Copy *Application (client) ID* and *Directory (tenant) ID* to a secure location on your computer. You will later enter these details into the Prisma Cloud UI.

. Create the client secret.
+
The client secret is a secret string that the application uses to prove its identity when requesting a token.
+
.. Select *Certificates & secrets[+ New client secret*.

.. Enter a client *Description*, select *Expires* to configure how long the client secret lasts, and *Add*.

.. Copy *Value* to a secure location. Make sure that you copy *Value* and not *Secret ID*. 

. Get the Object ID.
+
.. Select *Azure Active Directory[Enterprise applications]*, and search for the app you previously created in the search box.
+
image::connect/azure-enterprise-applications-object-id.png[]

.. Copy *Object ID* to a secure location on your computer. Make sure that you get the *Object ID* for the Prisma Cloud application from *Enterprise Applications > All applications* on the Azure portal—not from *App Registrations*.

. Add roles to the root group.
+
The following roles should be added to the root group:
+
** https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#reader[Reader]: Required to ingest configuration and activity logs.

** https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#reader-and-data-access[Reader and Data Access]: Required to fetch flow logs and storage account attributes to detect vulnerabilities.

** https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#network-contributor[Network Contributor]: Required to access and read flow logs settings for all network security groups (NSGs) and auto-remediation of network-related incidents.

** https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#storage-account-contributor[Storage Account Contributor]: Optional but required if you want to enable auto-remediation of policy violations.

** https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#key-vault-crypto-service-encryption-user[Key Vault Crypto Service Encryption User]: Required for Agent-based Workload Protection.

** Create Custom Roles for Agentless Scanning, and Serverless Scanning (These functions are not supported for Azure China.)

. Verify that all the roles have been added.
+
.. Select *Role assignments*.

.. Enter the name of your app in the search form and confirm that the roles that have been added.
+
image::connect/azure-account-view-roles.png[]

. Assign the created roles. Skip this step if your following the Azure Active Directory onboarding flow.
.. Complete the steps below to add role assignments.
... For Tenant workflow: Select *Management groups > Tenant Root Group > Access control (IAM) > Role assignments > + Add > Add role assignment*.
... For Subscription workflow: Select *All Services > Subscriptions > Access Control (IAM) > Role assignments > + Add > Add role assignment*.
... Enter the name of the role, for example, Reader, in the search box. Click on the role name in the results, and select *Next*.
... Assign members to the role, navigate to *Select members > Assign access*. Under *Assign Access to*, select *Assign the role to a User, group, or service principal*. 
... Click *+ Select members* and then enter the name of the app you previously created, in the search box to assign the role to your app. 
... Click *Select* and then *Next*.
... Select *Review + Assign* to complete adding the role assignment.
... Confirm that all the newly created roles were added.

. Add the Microsoft Graph APIs.
.. Navigate to the app you previously registered. Select *Azure Active Directory > App registrations*, and select your app.
.. Navigate to Microsoft Graph. Select *API permissions > Add a permission > Microsoft Graph > Application permissions*.
.. Add the permissions. Enter the permission name in *Select permissions*, and select the name from *Permission*. Add the following permissions:

* User.Read.All
* Policy.Read.All
* Group.Read.All
* GroupMember.Read.All
* Reports.Read.All
* Directory.Read.All
* Domain.Read.All
* Application.Read.All
+
If you have enabled additional functions like Agentless Scanning or Workload Protection additional permissions will be required. Review the *Roles and Permissions* list for the required permissions. 

. Grant admin consent for Default Directory.
.. Select Yes under *Grant admin consent for Default Directory*.
.. Verify that the permissions are granted.
.. Confirm that you can see green check marks under the *Status* column.