Add documentation for cloud-based authentication for the agent

content/en/account_management/cloud_provider_authentication.md

@@ -1,14 +1,17 @@
 ---
 title: Cloud-based Authentication
-description: Authenticate the Datadog Terraform provider using cloud credentials instead of static API keys with AWS STS authentication and identity mapping.
+description: Authenticate the Datadog Terraform provider and Datadog Agent using cloud credentials instead of static API keys with AWS STS authentication and identity mapping.
 aliases:
     - /account_management/cloud_authentication/
 algolia:
-  tags: ['cloud authentication', 'aws authentication', 'terraform provider']
+  tags: ['cloud authentication', 'aws authentication', 'terraform provider', 'agent authentication', 'delegated auth']
 further_reading:
 - link: "/getting_started/integrations/terraform/"
   tag: "Documentation"
   text: "Managing Datadog with Terraform"
+- link: "/agent/configuration/"
+  tag: "Documentation"
+  text: "Agent Configuration"
 - link: "/account_management/api-app-keys/"
   tag: "Documentation"
   text: "API and Application Keys"
@@ -23,31 +26,46 @@
 
 ## Overview
 
-Cloud-based authentication lets you authenticate the Datadog Terraform provider using cloud credentials instead of static API and application keys.
+Cloud-based authentication lets you authenticate the Datadog Terraform provider and the Datadog Agent using cloud credentials instead of static API and application keys.
 
 During the preview period, AWS is the only supported cloud provider.
 
+Cloud-based authentication is available for:
+- **Terraform provider**: Authenticate Terraform operations using AWS credentials mapped to a Datadog user or service account
+- **Datadog Agent**: Authenticate the Agent using AWS credentials to receive automatically managed and rotated API keys
+
 ## How it works: AWS authentication process
 
-The authentication process uses the [AWS Security Token Service (STS)][1] to verify your identity:
+The authentication process uses the [AWS Security Token Service (STS)][1] to verify your identity.
+
+### Terraform provider authentication flow
 
 1. **Proof generation:** The Datadog Terraform provider creates a signed AWS STS `GetCallerIdentity` request using your current AWS credentials
 2. **Proof validation:** Datadog validates the proof by calling AWS STS, which returns your AWS ARN, user ID, and account ID
 3. **Identity mapping:** Your AWS identity is mapped to a Datadog service account or user account based on your organization's configuration
 4. **Token issue:** If validation succeeds, Datadog issues a temporary JWT token for API access
 5. **API authentication:** The token is used for subsequent Datadog API calls
 
-
 <div class="alert alert-info">If possible, map ARNs to a Datadog service account rather than a user account. Using a service account avoids associating your authentication process with a specific person.</div>
 
+### Agent authentication flow
+
+1. **Credential detection:** The Agent retrieves AWS credentials from the environment it runs in
+2. **Proof generation:** The Agent creates a signed AWS STS request to prove access to the credentials
+3. **Proof validation:** Datadog validates the signed request against AWS and verifies it against your organization's intake mapping configuration
+4. **API key issue:** If validation succeeds, Datadog issues a managed API key that is automatically rotated
+5. **Agent configuration:** The Agent uses the issued API key for all subsequent Datadog API calls
+
+<div class="alert alert-info">If the delegated authentication flow fails, the Agent falls back to the API key configured in your <code>datadog.yaml</code> file. This fallback behavior allows you to onboard with limited risk to your existing configuration.</div>
+
 ## Set up cloud-based authentication for AWS
 
 **Requirements**:
 - Datadog Terraform provider version 3.70 or later.
 - You have configured the [Datadog-AWS integration][4] and added your AWS account. See the [AWS Integration docs][3].
 - The `cloud_auth_config_read` and `cloud_auth_config_write` permissions. These permissions are available only after you are onboarded to the preview.
 
-Setting up cloud-provider based authentication for AWS involves two parts: 
+Setting up cloud-provider based authentication for AWS involves two parts:
 1. [Configuring your AWS identity mapping in Datadog](#configure-aws-identity-mapping-in-datadog)
 2. [Updating your Terraform provider configuration](#update-your-terraform-provider-configuration)
 
@@ -206,6 +224,147 @@
 
 The Terraform provider automatically uses your configured AWS credentials to authenticate with Datadog.
 
+## Set up cloud-based authentication for the Datadog Agent
+
+Cloud-based authentication for the Agent allows you to authenticate your Agent using AWS credentials instead of managing static API keys. The Agent exchanges an AWS authentication proof for a managed API key that Datadog automatically rotates.
+
+**Requirements**:
+- The version `7.78.0` or later of the Datadog Agent.
+- The Agent runs in an AWS environment with access to AWS credentials (for example, an EC2 instance with an IAM role, ECS task, or EKS pod).
+- You have configured the [Datadog-AWS integration][4] and added your AWS account. See the [AWS Integration docs][3].
+- The `cloud_auth_config_read` and `cloud_auth_config_write` permissions. These permissions are available only after you are onboarded to the preview.
+
+Setting up cloud-based authentication for the Agent involves two parts:
+1. [Configuring your AWS intake mapping in Datadog](#configure-aws-intake-mapping-in-datadog)
+2. [Updating your Agent configuration](#update-your-agent-configuration)
+
+### Configure AWS intake mapping in Datadog
+
+<div class="alert alert-info">For intake mapping to work, your AWS account <strong>must be integrated</strong> with Datadog through the <a href="https://app.datadoghq.com/integrations/amazon-web-services">Datadog-AWS integration</a>. If an AWS account is not integrated, the authentication flow cannot verify the caller, and mapping fails.</div>
+
+First, configure intake mappings to authorize specific AWS ARN patterns for Agent authentication. Unlike persona mapping used for Terraform, intake mapping only requires an ARN pattern—no Datadog account identifier is needed because the Agent authenticates to send data rather than perform user actions.
+
+If you need to create IAM roles in AWS, see the [AWS IAM role creation documentation][5].
+
+#### Create an intake mapping
+
+**Example**: An API call that authorizes Agents running with a specific IAM role to authenticate.
+
+```bash
+curl -X POST "{{< region-param key=dd_api code="true" >}}/api/v2/cloud_auth/aws/intake_mapping" \
+-H "Content-Type: application/json" \
+-H "DD-API-KEY: ${DD_API_KEY}" \
+-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
+-d '{
+  "data": {
+    "type": "aws_cloud_auth_intake_mapping",
+    "attributes": {
+      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*"
+    }
+  }
+}'
+```
+
+#### Using wildcards in ARN patterns
+
+ARN patterns support wildcard matching to handle dynamic or variable portions of resource ARNs. This is useful when working with assumed roles that include session identifiers or when you have multiple Agent instances.
+
+**Wildcard rules**:
+- Wildcards (`*`) are only allowed in the last portion of the resource ARN
+- You must specify a specific resource before the wildcard
+- Wildcards cannot be placed in the middle of the ARN
+
+**Example**: Match any session assuming the `DatadogAgentRole`:
+
+```bash
+curl -X POST "{{< region-param key=dd_api code="true" >}}/api/v2/cloud_auth/aws/intake_mapping" \
+-H "Content-Type: application/json" \
+-H "DD-API-KEY: ${DD_API_KEY}" \
+-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
+-d '{
+  "data": {
+    "type": "aws_cloud_auth_intake_mapping",
+    "attributes": {
+      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*"
+    }
+  }
+}'
+```
+
+This pattern matches actual assumed role ARNs like:
+- `arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/i-0abc123def456`
+- `arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/eks-datadog-agent-xyz`
+
+#### List existing intake mappings
+
+```bash
+curl -X GET "{{< region-param key=dd_api code="true" >}}/api/v2/cloud_auth/aws/intake_mapping" \
+-H "DD-API-KEY: ${DD_API_KEY}" \
+-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
+```
+
+#### Delete an intake mapping
+
+```bash
+curl -X DELETE "{{< region-param key=dd_api code="true" >}}/api/v2/cloud_auth/aws/intake_mapping/<MAPPING_UUID>" \
+-H "DD-API-KEY: ${DD_API_KEY}" \
+-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
+```
+
+### Update your Agent configuration
+
+After you configure the intake mapping, update your Agent configuration to use cloud-based authentication.
+
+#### Basic configuration
+
+Add the `delegated_auth` section to your `datadog.yaml` file:
+
+```yaml
+delegated_auth:
+  org_uuid: <YOUR_ORG_UUID>
+```
+
+To get your `org_uuid`, call this endpoint, or click the link (requires an active session in the target org): [{{< region-param key=dd_api >}}/api/v2/current_user][2]
+
+The Agent auto-detects if it runs in an AWS environment and uses the available AWS credentials.
+
+#### Specify the cloud provider explicitly
+
+To explicitly configure AWS as your authentication provider:
+
+```yaml
+delegated_auth:
+  org_uuid: <YOUR_ORG_UUID>
+  provider: aws
+```
+
+#### Provider-specific options
+
+For AWS-specific configuration options, use the `aws` subsection:
+
+```yaml
+delegated_auth:
+  org_uuid: <YOUR_ORG_UUID>
+  provider: aws
+  aws:
+    region: <AWS_REGION>
+```
+
+Replace `<AWS_REGION>` with the AWS region to use for STS authentication (for example, `us-east-1`).
+
+#### Fallback behavior
+
+If the delegated authentication flow fails for any reason, the Agent automatically falls back to using the API key configured in your `datadog.yaml` file. This fallback behavior provides a safety net during onboarding and protects against authentication service disruptions.
+
+To take advantage of this fallback, keep your existing `api_key` configuration alongside the new `delegated_auth` configuration:
+
+```yaml
+api_key: <YOUR_API_KEY>
+
+delegated_auth:
+  org_uuid: <YOUR_ORG_UUID>
+```
+
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
@@ -214,4 +373,4 @@
 [2]: https://app.datadoghq.com/api/v2/current_user
 [3]: /integrations/amazon-web-services/
 [4]: https://app.datadoghq.com/integrations/amazon-web-services
-[5]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html
+[5]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html