# Source: https://docs.datadoghq.com/account_management/cloud_provider_authentication.md

---
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.
breadcrumbs: Docs > Account Management > Cloud-based Authentication
---

# Cloud-based Authentication

{% callout %}
##### Join the Preview!

Cloud-based authentication is in Preview. Complete the form to request access.

[Request Access](https://www.datadoghq.com/product-preview/cloud-provider-based-authentication/)
{% /callout %}

## Overview{% #overview %}

Cloud-based authentication lets you authenticate the Datadog Terraform provider using cloud credentials instead of static API and application keys.

During the preview period, AWS is the only supported cloud provider.

## 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:

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 %}

## Set up cloud-based authentication for AWS{% #set-up-cloud-based-authentication-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/).
- 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:

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 %}

First, map your AWS identities (ARNs) to Datadog service accounts or user accounts. During the preview, you must perform the mapping using the Datadog 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).

#### 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 configured the identity mapping, update your Datadog Terraform provider configuration to use cloud provider authentication:

#### 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 cloud authentication configuration{% #add-the-new-cloud-authentication-configuration %}

To get your `org_uuid`, call this endpoint, or click the link (requires an active session in the target org): [/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.

## Further reading{% #further-reading %}

- [Managing Datadog with Terraform](https://docs.datadoghq.com/getting_started/integrations/terraform/)
- [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/)
- [AWS Integration](https://docs.datadoghq.com/integrations/amazon_web_services/)