[DOCS-15112] Document Azure Secretless Auth setup and migration

content/en/getting_started/integrations/azure.md

@@ -64,10 +64,25 @@ The `Datadog Admin Role`, or any other role with the `azure_configurations_manag
 
 ## Setup
 
-Follow the instructions on this page to set up the {{< ui >}}Azure integration{{< /ui >}} through an app registration, available for all Datadog sites.
+Follow the instructions on this page to set up the {{< ui >}}Azure integration{{< /ui >}} through an app registration, available for all Datadog sites. During setup, choose whether the app registration authenticates with Datadog using **Secretless Auth** (recommended) or a **Client Secret**.
 
 {{< img src="/getting_started/integrations/azure/GSwAzure_siteSelector.mp4" alt="Site selector for US3 site" video=true >}}
 
+### Authentication methods
+
+<div class="alert alert-info">Secretless Auth is in Preview.</div>
+
+The Azure integration supports two authentication methods:
+
+| Method | How it works | What you manage |
+|---|---|---|
+| **Secretless Auth** (recommended) | Datadog and Azure establish a trusted identity relationship using an Azure federated credential and OpenID Connect (OIDC) [workload identity federation][54]. The app registration trusts Datadog's OIDC identity instead of a stored secret, and Datadog never stores a secret. | Nothing to rotate or renew, which reduces the risk of ingestion gaps from expired credentials. |
+| **Client Secret** | Datadog stores and authenticates with a client secret from your app registration. | Keep the secret up to date before it expires. |
+
+You select the authentication method when you create or configure an app registration.
+
+{{< img src="/getting_started/integrations/azure/GSwAzure_authenticationMethod.png" alt="The Authentication Method step in the Azure integration setup, showing the recommended Secretless Auth and Client Secret options" style="width:100%;" >}}
+
 {{% collapse-content title="Quickstart (recommended)" level="h4" expanded=false id="quickstart-setup" %}}
 
 ### Choose the Quickstart setup method if...
@@ -82,7 +97,8 @@ Follow the instructions on this page to set up the {{< ui >}}Azure integration{{
 2. Copy the setup script, and run it in the Azure Cloud shell.
 3. Return to the Datadog UI. You should see {{< ui >}}CONNECTED{{< /ui >}} at the top right corner of the setup script.
 4. Select the subscriptions and management groups to collect data from.
-5. Optionally, click the metric collection toggle to disable all metric collection from Azure. You can also expand the {{< ui >}}Advanced Configuration{{< /ui >}} dropdown to filter metrics by:
+5. Under {{< ui >}}Authentication Method{{< /ui >}}, select {{< ui >}}Secretless Auth{{< /ui >}} (recommended) to authenticate with a federated credential, or {{< ui >}}Client Secret{{< /ui >}} to store and authenticate with a client secret.
+6. Optionally, click the metric collection toggle to disable all metric collection from Azure. You can also expand the {{< ui >}}Advanced Configuration{{< /ui >}} dropdown to filter metrics by:
    - Resource provider
    - Tags
    - Hosts
@@ -91,8 +107,8 @@ Follow the instructions on this page to set up the {{< ui >}}Azure integration{{
 
 You can also click to enable custom metric collection from [Azure Application Insights][36], and disable the collection of usage metrics.
 
-6. Optionally, click the resource collection toggle to disable the collection of configuration information from your Azure resources.
-7. Enable log collection to set up and configure the services and diagnostic settings needed to forward logs to Datadog:
+7. Optionally, click the resource collection toggle to disable the collection of configuration information from your Azure resources.
+8. Enable log collection to set up and configure the services and diagnostic settings needed to forward logs to Datadog:
    1. If a log forwarder already exists in the tenant, it is modified to extend its scope. Any changed settings apply to existing as well as newly-selected subscriptions or management groups.
    2. If you're creating a new log forwarder:
       1. Enter a resource group name to store the log forwarder control plane
@@ -103,7 +119,7 @@ You can also click to enable custom metric collection from [Azure Application In
 
    See the [Architecture section][34] of the automated log forwarding guide for more information about this architecture.
 
-8. Click {{< ui >}}Confirm{{< /ui >}} to finish the setup.
+9. Click {{< ui >}}Confirm{{< /ui >}} to finish the setup.
 
 {{% /collapse-content %}}
 
@@ -124,24 +140,25 @@ Follow these steps to deploy the Datadog Azure integration through [Terraform][2
 
 1. In the [Azure integration tile][100], click {{< ui >}}+ Add New App registration{{< /ui >}}, then select {{< ui >}}Terraform{{< /ui >}}.
 2. Select the subscriptions and management groups to collect data from.
-3. Optionally, click the metric collection toggle to disable all metric collection from Azure. You can also expand the {{< ui >}}Advanced Configuration{{< /ui >}} dropdown to filter metrics by:
+3. Under {{< ui >}}Authentication Method{{< /ui >}}, select {{< ui >}}Secretless Auth{{< /ui >}} (recommended) to authenticate with a federated credential, or {{< ui >}}Client Secret{{< /ui >}} to store and authenticate with a client secret.
+4. Optionally, click the metric collection toggle to disable all metric collection from Azure. You can also expand the {{< ui >}}Advanced Configuration{{< /ui >}} dropdown to filter metrics by:
    - Resource provider
    - Tags
    - Hosts
    - App Service Plans
    - Container Apps
 
    You can also click to enable custom metric collection from [Azure Application Insights][101], and disable the collection of usage metrics.
-4. Optionally, click the resource collection toggle to disable the collection of configuration information from your Azure resources.
-5. Configure log collection:
+5. Optionally, click the resource collection toggle to disable the collection of configuration information from your Azure resources.
+6. Configure log collection:
    - If a log forwarder already exists in the tenant, extend its scope to include any new subscriptions or management groups.
    - If you're creating a new log forwarder:
      1. Enter a resource group name to store the log forwarder control plane.
      1. Select a control plane subscription for the log-forwarding orchestration (LFO).
      1. Select a region for the control plane.
 
    See the [Architecture section][102] of the automated log forwarding guide for more information about this architecture.
-6. Copy and run the command under {{< ui >}}Initialize and apply the Terraform{{< /ui >}}.
+7. Copy and run the command under {{< ui >}}Initialize and apply the Terraform{{< /ui >}}.
 
 [100]: https://app.datadoghq.com/integrations/azure/
 [101]: https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview
@@ -155,19 +172,21 @@ Follow these steps to deploy the Datadog Azure integration through [Terraform][2
 - You already have an app registration configured with the {{< ui >}}Monitoring Reader{{< /ui >}} role for Datadog to monitor the provided scope (subscriptions or management groups), and don't want to create new resources.
 
 1. Configure the [Datadog Terraform provider][200] to interact with the Datadog API through a Terraform configuration.
-2. Set up your Terraform configuration file using the example below as a base template. Ensure to update the following parameters before you apply the changes:
+2. Set up your Terraform configuration file using the example below as a base template. Update the following parameters before you apply the changes:
     * `tenant_name`: Your Azure Active Directory ID.
     * `client_id`: Your Azure application (client) ID.
-    * `client_secret`: Your Azure web application secret key.
+    * `secretless_auth_enabled`: Set to `true` to authenticate with a federated credential instead of a client secret (recommended). To authenticate with a client secret instead, remove this parameter and set `client_secret` to the app registration's secret value.
+
+   Secretless Auth requires a federated credential on the app registration that trusts Datadog's identity. See [Authentication methods](#authentication-methods).
 
    See the [Datadog Azure integration resource][201] page in the Terraform registry for further example usage and the full list of optional parameters, as well as additional Datadog resources.
 
 {{< code-block lang="hcl" filename="" disable_copy="false" collapsible="false" >}}
 
 resource "datadog_integration_azure" "sandbox" {
-  tenant_name   = "<AZURE_TENANT_NAME>"
-  client_id     = "<AZURE_CLIENT_ID>"
-  client_secret = "<AZURE_CLIENT_SECRET_KEY>"
+  tenant_name             = "<AZURE_TENANT_NAME>"
+  client_id               = "<AZURE_CLIENT_ID>"
+  secretless_auth_enabled = true
 }
 
 {{< /code-block >}}
@@ -228,6 +247,64 @@ You can also click to enable custom metric collection from [Azure Application In
 
 {{% /collapse-content %}}
 
+{{% collapse-content title="Migrate an existing app registration to Secretless Auth" level="h4" expanded=false id="secretless-migration-setup" %}}
+
+If you already connected an app registration using a client secret, you can migrate it to Secretless Auth in place. You don't need to recreate the app registration.
+
+1. In the [Azure integration tile][20], on the {{< ui >}}Configuration{{< /ui >}} tab, select the app registration you want to migrate.
+2. On the {{< ui >}}General{{< /ui >}} tab, under {{< ui >}}Authentication{{< /ui >}}, click {{< ui >}}Set Up Secretless Auth{{< /ui >}}.
+
+   {{< img src="/getting_started/integrations/azure/GSwAzure_secretlessMigration.png" alt="The General tab for an app registration, with a callout recommending Secretless Auth and a Set Up Secretless Auth button" style="width:100%;" >}}
+
+In the {{< ui >}}Secretless Authentication Setup{{< /ui >}} dialog, select a setup method, then complete the steps for that method:
+
+{{< img src="/getting_started/integrations/azure/GSwAzure_secretlessSetupModal.png" alt="The Secretless Authentication Setup dialog with the Azure CLI, Terraform, and Azure Portal setup methods and steps to create a federated credential, verify it, and complete setup" style="width:100%;" >}}
+
+{{< tabs >}}
+{{% tab "Azure CLI" %}}
+
+1. Run the provided `az ad app federated-credential create` command in a terminal with the Azure CLI configured for the correct tenant, or click {{< ui >}}Open Azure Cloud Shell{{< /ui >}}.
+2. Click {{< ui >}}Verify Credential{{< /ui >}} to test the authentication.
+3. Click {{< ui >}}Confirm{{< /ui >}}. Your client secret is removed when setup succeeds.
+
+{{% /tab %}}
+{{% tab "Terraform" %}}
+
+This method requires the `azuread` provider version 3.7.0 or later.
+
+1. Add the federated credential resource shown in the dialog to the same configuration that manages your Datadog Azure integration, then apply it. Copy the `issuer` and `subject` values from the dialog.
+
+   {{< code-block lang="hcl" filename="" disable_copy="false" collapsible="false" >}}
+resource "azuread_application_federated_identity_credential" "datadog_federated_credential" {
+  # Reference the ID of this app registration
+  application_id = azuread_application.datadog_app.id
+  display_name   = "datadog"
+  description    = "Federated credential that permits Datadog to authenticate without storing a client secret"
+  audiences      = ["api://AzureADTokenExchange"]
+  issuer         = "<ISSUER>"
+  subject        = "<SUBJECT>"
+}
+   {{< /code-block >}}
+
+2. Click {{< ui >}}Verify Credential{{< /ui >}} to test the authentication.
+3. Modify your `datadog_integration_azure` resource to use Secretless Auth:
+   - Add the federated credential resource to the integration's dependency list.
+   - Replace the `client_secret` setting with `secretless_auth_enabled = true`.
+   - Apply the changes.
+
+{{% /tab %}}
+{{% tab "Azure Portal" %}}
+
+1. In the Azure portal, open the app registration and go to {{< ui >}}Certificates & secrets{{< /ui >}} > {{< ui >}}Federated credentials{{< /ui >}} > {{< ui >}}Add credential{{< /ui >}}.
+2. Select {{< ui >}}Other issuer{{< /ui >}}, then enter the {{< ui >}}Issuer{{< /ui >}}, {{< ui >}}Subject{{< /ui >}}, and {{< ui >}}Audience{{< /ui >}} values exactly as shown in the dialog.
+3. Click {{< ui >}}Verify Credential{{< /ui >}} to test the authentication.
+4. Click {{< ui >}}Confirm{{< /ui >}}. Your client secret is removed when setup succeeds.
+
+{{% /tab %}}
+{{< /tabs >}}
+
+{{% /collapse-content %}}
+
 ## Metric collection
 
 Datadog's Azure integration is built to collect all metrics from [Azure Monitor][8]. The [Integrations page][9] shows a curated list of predefined sub-integrations that provide additional out-of-the-box dashboards and monitors for specific Azure services. Many of these integrations are installed by default when Datadog recognizes data coming in from your Azure account. However, Datadog can ingest metrics from **any Azure Monitor-supported resource**, even if it doesn't have a dedicated sub-integration tile.
@@ -435,3 +512,4 @@ Still need help? Contact [Datadog support][17].
 [51]: https://app.datadoghq.com/logs
 [52]: https://portal.azure.com/#create/Microsoft.Template/uri/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2FDataDog%2Fintegrations-management%2Fmain%2Fazure%2Flogging_install%2Fdist%2Fforwarder.json
 [53]: https://learn.microsoft.com/azure/azure-monitor/platform/diagnostic-settings
+[54]: https://learn.microsoft.com/entra/workload-id/workload-identity-federation

content/en/integrations/guide/azure-advanced-configuration.md

@@ -53,6 +53,8 @@ After this is completed, data collection begins automatically. The app registrat
 
 {{< img src="integrations/guide/azure_architecture_and_configuration/app_registration_metric_collection.png" alt="Workflow diagram showing Azure metric collection process: the Datadog backend reads configuration, authenticates through service principal to Azure Active Directory, collects subscription and resource metadata using RBAC permissions, filters resources by tags, then retrieves metrics from Azure Monitor for ingestion into Datadog." >}}
 
+The metric and log collection diagrams above use authentication with a client secret. With **Secretless Auth**, the app registration trusts Datadog's identity through an Azure federated credential and OpenID Connect (OIDC) workload identity federation. This replaces the stored client secret. To move an existing app registration to Secretless Auth, see [Migrate an existing app registration to Secretless Auth][39].
+
 ## Log collection
 
 The diagram below provides a reference architecture for forwarding logs from Azure to Datadog using [automated log forwarding][29]. A control plane deployed in your chosen subscription discovers resources and configures their diagnostic settings. Log forwarders, consisting of an Azure Container Apps job and a storage account, are deployed in each region where your resources generate logs, and they scale up or down to match log volume.
@@ -674,3 +676,4 @@ The `azure.*.count` metric should show in Datadog within 5 - 10 minutes.
 [36]: /help/
 [37]: https://www.datadoghq.com/blog/azure-log-forwarding/
 [38]: /logs/log_configuration/indexes/#exclusion-filters
+[39]: /getting_started/integrations/azure/#secretless-migration-setup

content/en/integrations/guide/azure-resource-manager.md

@@ -75,6 +75,7 @@ A form to create a new app registration is displayed:
 
 ## Next steps
 
+- [Migrate this app registration to Secretless Auth][5] to remove the client secret
 - Check out the [Azure Overview dashboard][3] to start getting insights into your Azure environment
 - Check out [Azure monitor templates][4] to start getting alerts for the data that's important to your organization
 
@@ -85,3 +86,4 @@ A form to create a new app registration is displayed:
 [2]: /security/cloud_security_management/
 [3]: https://app.datadoghq.com/dash/integration/71/azure-overview
 [4]: https://app.datadoghq.com/monitors/templates?q=azure
+[5]: /getting_started/integrations/azure/#secretless-migration-setup