Documents new Azure deployment methods for 8.12 (#4551)

* First complete draft - 8.12 Azure onboarding updates

* Minor changes to related docs for 8.12 Azure CSPM GA update

* minor updates

* minor update

* updates based on conversation with Kostas

* addresses Tinsae's feedback

* minor update

* incorporates Nastasha's review

docs/cloud-native-security/cspm-get-started-azure.asciidoc

@@ -15,14 +15,14 @@ This page explains how to get started monitoring the security posture of your cl
 ** `logs-cloud_security_posture.findings_latest-*`
 ** `logs-cloud_security_posture.scores-*`
 ** `logs-cloud_security_posture.findings`
-* The user who gives the CSPM integration permissions must be an Azure subscription `admin`.
+* The user who gives the CSPM integration permissions in Azure must be an Azure subscription `admin`.
 --
 
 [discrete]
 [[cspm-setup-azure]]
 == Set up CSPM for Azure
 
-To set up CSPM for Azure, first add the CSPM integration, then enable cloud account access.
+You can set up CSPM for Azure by by enrolling an Azure organization (management group) containing multiple subscriptions, or by enrolling a single subscription. Either way, first add the CSPM integration, then enable cloud account access.
 
 
 [discrete]
@@ -31,45 +31,52 @@ To set up CSPM for Azure, first add the CSPM integration, then enable cloud acco
 . From the Elastic Security *Get started* page, click *Add integrations*.
 . Search for `CSPM`, then click on the result.
 . Click *Add Cloud Security Posture Management (CSPM)*.
-. Under **Configure integration**, select **Azure**.
-. Give your integration a name that matches the purpose or team of the Azure subscription you want to monitor, for example, `azure-CSPM-1`.
+. Under **Configure integration**, select **Azure**, then select either **Azure Organization** or **Single Subscription**, depending on which resources you want to monitor. 
+. Give your integration a name that matches the purpose or team of the Azure resources you want to monitor, for example, `azure-CSPM-dev-1`.
 
 [discrete]
 [[cspm-set-up-cloud-access-section-azure]]
 === Set up cloud account access
 
-NOTE: To set up CSPM for an Azure subscription, you will need admin privileges for that subscription.
+NOTE: To set up CSPM for an Azure organization or subscription, you will need admin privileges for that organization or subscription.
 
 For most users, the simplest option is to use an Azure Resource Manager (ARM) template to automatically provision the necessary resources and permissions in Azure. If you prefer a more hands-on approach or require a specific configuration not supported by the ARM template, you can use one of the manual setup options described below.
 
 [discrete]
 [[cspm-set-up-ARM]]
 == ARM template setup (recommended)
 
+NOTE: If you are deploying to an Azure organization, you need the following permissions: `Microsoft.Resources/deployments/*`, `Microsoft.Authorization/roleAssignments/write`. You also need to https://learn.microsoft.com/en-us/azure/role-based-access-control/elevate-access-global-admin[elevate access to manage all Azure subscriptions and management groups].
+
 . Under *Setup Access*, select *ARM Template*.
 . Under **Where to add this integration**:
 .. Select **New Hosts**.
-.. Name the {agent} policy. Use a name that matches the purpose or team of the cloud account or accounts you want to monitor. For example, `azure-dev-policy`. Click **Save and continue**. The *ARM Template deployment* window appears.
+.. Name the {agent} policy. Use a name that matches the resources you want to monitor. For example, `azure-dev-policy`. Click **Save and continue**. The *ARM Template deployment* window appears.
 .. In a new tab, log in to the Azure portal, then return to {kib} and click **Launch ARM Template**. This will open the ARM template in Azure.
+.. If you are deploying to an Azure organization, select the management group you want to monitor from the drop-down menu. Next, enter the subscription ID of the subscription where you want to deploy the VM that will scan your resources.
+.. Copy the `Fleet URL` and `Enrollment Token` that appear in {kib} to the corresponding fields in the ARM Template, then click **Review + create**.
 .. (Optional) Change the `Resource Group Name` parameter. Otherwise the name of the resource group defaults to a timestamp prefixed with `cloudbeat-`.
-.. Copy the `Fleet URL` and `Enrollment Token` that appear in {kib} to the corresponding fields in the ARM Template, then click *Review + create*.
 . Return to {kib} and wait for the confirmation of data received from your new integration. Then you can click **View Assets** to see your data.
 
 [discrete]
 [[cspm-set-up-manual-azure]]
 == Manual setup
 
-For manual setup, there are two authentication methods: using managed identities (recommended), or using environment variables with authentication secrets. The first method requires you to deploy {agent} to a VM in the Azure subscription you want to monitor with CSPM; the second method allows {agent} to be deployed anywhere, including a VM outside Azure or a personal laptop.
+For manual setup, multiple authentication methods are available: 
+
+* Managed identity (recommended)
+* Service principal with client secret
+* Service principal with client certificate
 
 [discrete]
 [[cspm-azure-managed-identity-setup]]
 === Option 1: Managed identity (recommended)
 
-This method involves creating an Azure VM (or using an existing one), giving it read access to the subscription you want to monitor with CSPM, and installing {agent} on it.
+This method involves creating an Azure VM (or using an existing one), giving it read access to the resources you want to monitor with CSPM, and installing {agent} on it.
 
 . Go to the Azure portal to https://portal.azure.com/#create/Microsoft.VirtualMachine-ARM[create a new Azure VM].
 . Follow the setup process, and make sure you enable **System assigned managed identity** under the **Management** tab.
-. Go to your Azure subscription list and select the subscription you want to monitor with CSPM.
+. Go to your Azure subscription list and select the subscription or management group you want to monitor with CSPM.
 . Go to **Access control (IAM)**, and select **Add Role Assignment**.
 . Select the `Reader` function role, assign access to **Managed Identity**, then select your VM.
 
@@ -83,39 +90,80 @@ After assigning the role:
 Wait for the confirmation that {kib} received data from your new integration. Then you can click **View Assets** to see your data.
 
 [discrete]
-[[cspm-azure-environment-variables-setup]]
-=== Option 2: Environment variables with authentication secrets
+[[cspm-azure-client-secret]]
+=== Option 2: Service principal with client secret
 
 Before using this method, you must have set up a https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in[Microsoft Entra application and service principal that can access resources]. 
 
+. On the **Add Cloud Security Posture Management (CSPM) integration** page, scroll to the **Setup access** section, then select **Manual**.
+. Under **Preferred manual method**, select **Service principal with Client Secret**.
 . Go to the **Registered apps** section of https://ms.portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps[Microsoft Entra ID].
 . Click on **New Registration**, name your app and click **Register**.
-. Copy your new app's `Directory (tenant) ID` and `Application (client) ID`.
-. Select **Certificates & secrets**, then select **New client secret**. Copy the new secret.
-. Go to your Azure subscription list and select the subscription you want to monitor with CSPM.
+. Copy your new app's `Directory (tenant) ID` and `Application (client) ID`. Paste them into the corresponding fields in {kib}.
+. Return to the Azure portal. Select **Certificates & secrets**, then go to the **Client secrets** tab. Click **New client secret**. 
+. Copy the new secret. Paste it into the corresponding field in {kib}.
+. Return to Azure. Go to your Azure subscription list and select the subscription or management group you want to monitor with CSPM.
 . Go to **Access control (IAM)** and select **Add Role Assignment**. 
 . Select the `Reader` function role, assign access to **User, group, or service principal**, and select your new app.
+. Return to the **Add CSPM** page in {kib}. 
+. Under **Where to add this integration**, select **New hosts**.
+. Click **Save and continue**, then follow the instructions to install {agent} on your selected host.
 
-On the VM where you plan to install {agent}, create the file `/etc/sysconfig/elastic-agent`. Paste the following content into the new file, substituting the values you copied for the placeholder values:
+Wait for the confirmation that {kib} received data from your new integration. Then you can click **View Assets** to see your data.
 
+[discrete]
+[[cspm-azure-client-certificate]]
+=== Option 3: Service principal with client certificate
+
+Before using this method, you must have set up a https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in[Microsoft Entra application and service principal that can access resources]. 
+
+. On the **Add Cloud Security Posture Management (CSPM) integration** page, under **Setup access**, select **Manual**. 
+. Under **Preferred manual method**, select **Service principal with client certificate**.
+. Go to the **Registered apps** section of https://ms.portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps[Microsoft Entra ID].
+. Click on **New Registration**, name your app and click **Register**.
+. Copy your new app's `Directory (tenant) ID` and `Application (client) ID`. Paste them into the corresponding fields in {kib}.
+. Return to Azure. Go to your Azure subscription list and select the subscription or management group you want to monitor with CSPM.
+. Go to **Access control (IAM)** and select **Add Role Assignment**. 
+. Select the `Reader` function role, assign access to **User, group, or service principal**, and select your new app.
+
+Next, create a certificate. If you intend to use a password-protected certificate, you must use a pkcs12 certificate. Otherwise, you must use a pem certificate.
+
+Create a pkcs12 certificate, for example:
+```shell
+# Create PEM file
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
+
+# Create pkcs12 bundle using legacy flag (CLI will ask for export password)
+openssl pkcs12 -legacy -export -out bundle.p12 -inkey key.pem -in cert.pem
 ```
-AZURE_TENANT_ID=<Directory (tenant) ID>
-AZURE_CLIENT_ID=<Application (client) ID>
-AZURE_CLIENT_SECRET=<Secret Value>
+
+Create a PEM certificate, for example:
+```shell
+# Generate certificate signing request (csr) and key
+openssl req -new -newkey rsa:4096 -nodes -keyout cert.key -out cert.csr
+
+# Generate PEM and self-sign with key
+openssl x509 -req -sha256 -days 365 -in cert.csr -signkey cert.key -out signed.pem
+
+# Create bundle
+cat cert.key > bundle.pem
+cat signed.pem >> bundle.pem
 ```
 
-After creating the file:
+After creating your certificate:
 
+. Return to Azure.
+. Navigate to the **Certificates & secrets** menu. Select the **Certificates** tab.
+. Click **Upload certificate**. 
+.. If you're using a PEM certificate that was created using the example commands above, upload `signed.pem`.
+.. If you're using a pkcs12 certificate that was created using the example commands above, upload `cert.pem`.
+. Upload the certificate bundle to the VM where you will deploy {agent}.
+.. If you're using a PEM certificate that was created using the example commands above, upload `bundle.pem`.
+.. If you're using a pkcs12 certificate that was created using the example commands above, upload `bundle.p12`.
 . Return to the **Add CSPM** page in {kib}. 
-. Under **Configure integration**, select **Azure**. Under **Setup access**, select **Manual**.
+. For **Client Certificate Path**, enter the full path to the certificate that you uploaded to the host where you will install {agent}. 
+. If you used a pkcs12 certificate, enter its password under **Client Certificate Password**.
 . Under **Where to add this integration**, select **New hosts**.
 . Click **Save and continue**, then follow the instructions to install {agent} on your selected host.
 
-If you created `/etc/sysconfig/elastic-agent` after installing {agent}, you might need to restart it with the following commands:
-
-```
-systemctl daemon-reload 
-systemctl restart elastic-agent
-```
-
 Wait for the confirmation that {kib} received data from your new integration. Then you can click **View Assets** to see your data.

docs/cloud-native-security/cspm-get-started-gcp.asciidoc

@@ -22,7 +22,7 @@ This page explains how to get started monitoring the security posture of your GC
 [[cspm-setup-gcp]]
 == Initial setup
 
-To set up CSPM for GCP, you need to first add the CSPM integration, then enable cloud account access.
+You can set up CSPM for GCP either by enroling a single project, or by enroling an organization containing multiple projects. Either way, you need to first add the CSPM integration, then enable cloud account access.
 
 
 [discrete]

docs/cloud-native-security/cspm.asciidoc

@@ -3,7 +3,7 @@
 
 The Cloud Security Posture Management (CSPM) feature discovers and evaluates the services in your cloud environment — like storage, compute, IAM, and more — against configuration security guidelines defined by the https://www.cisecurity.org/[Center for Internet Security] (CIS) to help you identify and remediate risks that could undermine the confidentiality, integrity, and availability of your cloud data.
 
-This feature currently supports Amazon Web Services (AWS) and Google Cloud Platform (GCP). For step-by-step getting started guides, refer to <<cspm-get-started,Get started with CSPM for AWS>> or <<cspm-get-started-gcp, Get started with CSPM for GCP>>.
+This feature currently supports Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. For step-by-step getting started guides, refer to <<cspm-get-started,Get started with CSPM for AWS>>, <<cspm-get-started-gcp, Get started with CSPM for GCP>>, or <<cspm-get-started-azure, Get started with CSPM for Azure>>.
 
 .Requirements
 [sidebar]