--- title: Workload Identity Federation description: >- Authenticate the Datadog Terraform provider and Datadog Agent with Workload Identity Federation, using cloud credentials instead of static API keys with AWS STS authentication and identity mapping. breadcrumbs: Docs > Account Management > Workload Identity Federation --- # Workload Identity Federation ## Overview{% #overview %} Workload Identity Federation lets you authenticate the Datadog Terraform provider and the Datadog Agent using cloud credentials instead of static API and application keys. AWS is the only supported cloud provider. Workload Identity Federation is available for the following: {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com - Terraform provider: Authenticate Terraform operations using AWS credentials mapped to a Datadog user or service account. Available for all customers. - Datadog Agent: Authenticate the Agent using AWS credentials to receive automatically managed and rotated API keys. Available for Enterprise plans only. {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com - Terraform provider: Authenticate Terraform operations using AWS credentials mapped to a Datadog user or service account. Available for all customers. {% /callout %} ## How it works: AWS authentication process{% #how-it-works-aws-authentication-process %} The authentication process uses the [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) to verify your identity. ### Terraform provider authentication flow{% #terraform-provider-authentication-flow %} 1. **Proof generation:** The Datadog Terraform provider creates a signed AWS STS `GetCallerIdentity` request using your current AWS credentials 1. **Proof validation:** Datadog validates the proof by calling AWS STS, which returns your AWS ARN, user ID, and account ID 1. **Identity mapping:** Your AWS identity is mapped to a Datadog service account or user account based on your organization's configuration 1. **Token issue:** If validation succeeds, Datadog issues a temporary JWT token for API access 1. **API authentication:** The token is used for subsequent Datadog API calls {% alert level="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. {% /alert %} ### Agent authentication flow{% #agent-authentication-flow %} 1. **Credential detection:** The Agent retrieves AWS credentials from the environment it runs in 1. **Proof generation:** The Agent creates a signed AWS STS request to prove access to the credentials 1. **Proof validation:** Datadog validates the signed request against AWS and verifies it against your organization's intake mapping configuration 1. **API key issue:** If validation succeeds, Datadog issues a managed API key that is automatically rotated 1. **Agent configuration:** The Agent uses the issued API key for all subsequent Datadog API calls {% alert level="info" %} If the delegated authentication flow fails, the Agent falls back to the API key configured in your `datadog.yaml` file. This fallback behavior allows you to onboard with limited risk to your existing configuration. {% /alert %} ## Set up Workload Identity Federation for AWS{% #set-up-workload-identity-federation-for-aws %} **Requirements**: - Datadog Terraform provider version 3.70 or later. - You have configured the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services) and added your AWS account. See the [AWS Integration docs](https://docs.datadoghq.com/integrations/amazon-web-services.md). - Your account has the `workload_identity_federation_config_read` and `workload_identity_federation_config_write` permissions. Setting up Workload Identity Federation for AWS involves two parts: 1. Configuring your AWS identity mapping in Datadog 1. Updating your Terraform provider configuration ### Configure AWS identity mapping in Datadog{% #configure-aws-identity-mapping-in-datadog %} {% alert level="info" %} For identity mapping to work, your AWS account **must be integrated** with Datadog through the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services). If an AWS account is not integrated, the authentication flow cannot verify the caller, and mapping fails. {% /alert %} Map your AWS identities (ARNs) to Datadog service accounts or user accounts. You can configure identity mappings from the UI or using the API. If you need to create IAM roles in AWS, see the [AWS IAM role creation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html). #### Using the UI{% #using-the-ui %} Navigate to [**Organization Settings** > **Workload Identity Federation**](https://app.datadoghq.com/organization-settings/workload-identity-federation) and click the **Identity Mappings** tab. Each mapping grants a cloud role the permissions of a specific Datadog user or service account. {% image source="https://docs.dd-static.net/images/account_management/workload_identity_federation/identity-mappings-list.39b6c401ce1d5c9e3f643ae5adbebefb.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/workload_identity_federation/identity-mappings-list.39b6c401ce1d5c9e3f643ae5adbebefb.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Identity Mappings tab in the Workload Identity Federation page, showing the Org UUID field and a list of AWS ARN patterns mapped to Datadog users and service accounts" /%} {% alert level="warning" %} Datadog requires the **assumed-role ARN** in the Source Pattern field, not the IAM role ARN. These two formats are different: {% /alert %} - **IAM role ARN** (shown in the AWS Console): `arn:aws:iam::123456789012:role/my-role` - **Assumed-role ARN** (required by Datadog): `arn:aws:sts::123456789012:assumed-role/my-role/session-name` To find the assumed-role ARN for your workload, run `aws sts get-caller-identity` from your workload environment and use the value in the `Arn` field of the response. To create an identity mapping: 1. Click + New Mapping. 1. Select a **Cloud Provider**. 1. Enter a **Source Pattern (ARN)**. Use the assumed-role ARN format and `*` for wildcard patterns (for example, `arn:aws:sts::123456789012:assumed-role/terraform-runner/*`). 1. Search for and select a **Target Identity**. This is the Datadog user or service account this cloud identity authenticates as. 1. Click Create Mapping. {% image source="https://docs.dd-static.net/images/account_management/workload_identity_federation/identity-mapping-create.909b9245439dc9b4b9c4dad330295f67.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/workload_identity_federation/identity-mapping-create.909b9245439dc9b4b9c4dad330295f67.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Create Identity Mapping dialog with fields for Cloud Provider, Source Pattern ARN, and Target Identity, with a helper text describing wildcard pattern support" /%} {% alert level="info" %} Prefer service accounts over user accounts to avoid tying access to individuals. {% /alert %} #### Using the API{% #using-the-api %} ##### Map an AWS ARN to a Datadog user account{% #map-an-aws-arn-to-a-datadog-user-account %} For `account_identifier`, use the email shown in the user's Datadog profile. **Example**: An API call that maps an AWS ARN to a Datadog user account, `john.doe@myorg.com`. ```bash # Example: map an AWS ARN to a Datadog User curl -X POST "/api/v2/cloud_auth/aws/persona_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_config", "attributes": { "account_identifier": "john.doe@myorg.com", "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner" } } }' ``` ##### Map an AWS ARN to a Datadog service account{% #map-an-aws-arn-to-a-datadog-service-account %} For `account_identifier`, you can use either: - The service account's **UUID**: Go to Organization settings > Service accounts, click the service account you want to map, and copy the `service_account_id` from the URL. For example, if the URL ends in `/organization-settings/service-accounts?service_account_id=3fa85f64-5717-4562-b3fc-2c963f66afa6`, then use `3fa85f64-5717-4562-b3fc-2c963f66afa6`. - The service account's **email address**: Use the email address shown in the service account's details. **Example**: An API call that maps an AWS ARN to a Datadog service account using the UUID, `3fa85f64-5717-4562-b3fc-2c963f66afa6`. ```bash # Example: map an AWS ARN to a Datadog Service Account using UUID curl -X POST "/api/v2/cloud_auth/aws/persona_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_config", "attributes": { "account_identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner" } } }' ``` **Example**: An API call that maps an AWS ARN to a Datadog service account using the email address, `terraform-service-account@myorg.com`. ```bash # Example: map an AWS ARN to a Datadog Service Account using email curl -X POST "/api/v2/cloud_auth/aws/persona_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_config", "attributes": { "account_identifier": "terraform-service-account@myorg.com", "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner" } } }' ``` ##### Using wildcards in ARN patterns{% #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 other variable components. **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 `DatadogTerraformerRole`: ```bash curl -X POST "/api/v2/cloud_auth/aws/persona_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_config", "attributes": { "account_identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/*" } } }' ``` This pattern matches actual assumed role ARNs like: - `arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/run-abcdefghijk` - `arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/session-xyz789` {% alert level="info" %} Wildcard matching is particularly useful for CI/CD pipelines where role sessions have dynamically generated identifiers. {% /alert %} ##### List existing mappings{% #list-existing-mappings %} ```bash curl -X GET "/api/v2/cloud_auth/aws/persona_mapping" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" ``` ### Update your Terraform provider configuration{% #update-your-terraform-provider-configuration %} After you configure the identity mapping, update your Datadog Terraform provider configuration to use Workload Identity Federation: #### Remove your existing configuration{% #remove-your-existing-configuration %} ```hcl # Old configuration provider "datadog" { api_key = var.datadog_api_key app_key = var.datadog_app_key } ``` #### Add the new Workload Identity Federation configuration{% #add-the-new-workload-identity-federation-configuration %} To get your `org_uuid`, find it directly on the [**Organization Settings** > **Workload Identity Federation**](https://app.datadoghq.com/organization-settings/workload-identity-federation) page, or call this endpoint (requires an active session in the target org): [{% placeholder "user-datadog-api-url" /%}/api/v2/current_user](https://app.datadoghq.com/api/v2/current_user) ```hcl # New configuration using AWS authentication provider "datadog" { org_uuid = var.datadog_org_uuid cloud_provider_type = "aws" } ``` #### Optional - Specify AWS credentials explicitly{% #optional---specify-aws-credentials-explicitly %} As an alternative to using environment variables or AWS credential files, you can specify AWS credentials directly in your Terraform configuration: ```hcl provider "datadog" { org_uuid = var.datadog_org_uuid cloud_provider_type = "aws" aws_access_key_id = var.aws_access_key_id aws_secret_access_key = var.aws_secret_access_key aws_session_token = var.aws_session_token # If using temporary credentials } ``` The Terraform provider automatically uses your configured AWS credentials to authenticate with Datadog. ## Set up Workload Identity Federation for the Datadog Agent{% #set-up-workload-identity-federation-for-the-datadog-agent %} {% callout %} ##### Enterprise feature Workload Identity Federation for the Datadog Agent is available for customers on an enterprise plan only. Request access by contacting support. [Request Access](https://docs.datadoghq.com/help/) {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} Workload Identity Federation for the Datadog Agent is not available for the selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md) ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} Workload Identity Federation 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**: - 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](https://app.datadoghq.com/integrations/amazon-web-services) and added your AWS account. See the [AWS Integration docs](https://docs.datadoghq.com/integrations/amazon-web-services.md). - Your account has the `workload_identity_federation_config_read` and `workload_identity_federation_config_write` permissions. Setting up Workload Identity Federation for the Agent involves two parts: 1. Configuring your AWS intake mapping in Datadog 1. Updating your Agent configuration ### Configure AWS intake mapping in Datadog{% #configure-aws-intake-mapping-in-datadog %} {% alert level="info" %} For intake mapping to work, your AWS account **must be integrated** with Datadog through the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services). If an AWS account is not integrated, the authentication flow cannot verify the caller, and mapping fails. {% /alert %} Configure intake mappings to authorize specific AWS ARN patterns for Agent authentication. Unlike identity mappings, intake mappings only require an ARN pattern. No Datadog account identifier is needed, because the Agent authenticates to send data rather than perform user actions. Datadog automatically provisions, configures, and rotates the underlying API key on your behalf. If you need to create IAM roles in AWS, see the [AWS IAM role creation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html). #### Using the UI{% #using-the-ui-1 %} Navigate to [**Organization Settings** > **Workload Identity Federation**](https://app.datadoghq.com/organization-settings/workload-identity-federation) and click the **Intake Mappings** tab. {% image source="https://docs.dd-static.net/images/account_management/workload_identity_federation/intake-mappings-list.42d8c876405805f6fd7105bcb0724593.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/workload_identity_federation/intake-mappings-list.42d8c876405805f6fd7105bcb0724593.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Intake Mappings tab in the Workload Identity Federation page, showing the Org UUID field and a list of AWS ARN patterns authorized for Agent authentication" /%} {% alert level="warning" %} Datadog requires the **assumed-role ARN** in the Source Pattern field, not the IAM role ARN. These two formats are different: {% /alert %} - **IAM role ARN** (shown in the AWS Console): `arn:aws:iam::123456789012:role/my-role` - **Assumed-role ARN** (required by Datadog): `arn:aws:sts::123456789012:assumed-role/my-role/session-name` To find the assumed-role ARN for your workload, run `aws sts get-caller-identity` from your workload environment and use the value in the `Arn` field of the response. To create an intake mapping: 1. Click + New Mapping. 1. Select a **Cloud Provider**. 1. Enter a **Source Pattern (ARN)**. Use the assumed-role ARN format and `*` for wildcard patterns (for example, `arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*`). 1. Click Create Mapping. {% image source="https://docs.dd-static.net/images/account_management/workload_identity_federation/intake-mapping-create.6ad6f46a6630eccd7caf3d96f2b802d4.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/workload_identity_federation/intake-mapping-create.6ad6f46a6630eccd7caf3d96f2b802d4.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Create Intake Mapping dialog with fields for Cloud Provider and Source Pattern ARN, with helper text describing wildcard pattern support" /%} #### Using the API{% #using-the-api-1 %} ##### Create an intake mapping{% #create-an-intake-mapping %} **Example**: An API call that authorizes Agents running with a specific IAM role to authenticate. ```bash curl -X POST "/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{% #using-wildcards-in-arn-patterns-1 %} 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 "/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{% #list-existing-intake-mappings %} ```bash curl -X GET "/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{% #delete-an-intake-mapping %} ```bash curl -X DELETE "/api/v2/cloud_auth/aws/intake_mapping/" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" ``` ### Update your Agent configuration{% #update-your-agent-configuration %} After you configure the intake mapping, update your Agent configuration to use Workload Identity Federation. #### Global configuration{% #global-configuration %} Add the `delegated_auth` section to your `datadog.yaml` file to enable Workload Identity Federation for all Agent data: ```yaml delegated_auth: org_uuid: ``` To get your `org_uuid`, find it directly on the [**Organization Settings** > **Workload Identity Federation**](https://app.datadoghq.com/organization-settings/workload-identity-federation) page, or call this endpoint (requires an active session in the target org): [{% placeholder "user-datadog-api-url" /%}/api/v2/current_user](https://app.datadoghq.com/api/v2/current_user) The Agent auto-detects if it runs in an AWS environment and uses the available AWS credentials. #### Provider-specific options{% #provider-specific-options %} To explicitly configure AWS as your authentication provider and specify provider-specific options, use the `provider` and `aws` subsections: ```yaml delegated_auth: org_uuid: provider: aws # Optional: auto-detects if omitted aws: region: # Optional: auto-detects from IMDS if omitted or uses global STS ``` Replace `` with the AWS region to use for STS authentication (for example, `us-east-1`). #### Per-product configuration{% #per-product-configuration %} You can enable delegated authentication for specific Agent products independently. This is useful when you want to send different data types to different Datadog organizations, or when you only want to use Workload Identity Federation for specific products. To enable delegated authentication for logs only: ```yaml logs_config: delegated_auth: org_uuid: ``` To use different organizations for different products: ```yaml delegated_auth: org_uuid: provider: aws aws: region: logs_config: delegated_auth: org_uuid: ``` {% alert level="info" %} Provider-specific settings (such as `provider` and `aws`) are only configured in the global `delegated_auth` section. Per-product sections only support `org_uuid`. {% /alert %} #### Fallback behavior{% #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: delegated_auth: org_uuid: ``` ## Further reading{% #further-reading %} - [Managing Datadog with Terraform](https://docs.datadoghq.com/getting_started/integrations/terraform.md) - [Agent Configuration](https://docs.datadoghq.com/agent/configuration.md) - [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys.md) - [AWS Integration](https://docs.datadoghq.com/integrations/amazon_web_services.md)