Fédération d'identités de charges de travail

Présentation

La fédération d’identité de charge de travail vous permet d’authentifier le fournisseur Datadog Terraform et le Datadog Agent en utilisant des identifiants cloud au lieu de clés d’API et d’application statiques.

AWS est le seul fournisseur cloud pris en charge.

La fédération d’identité de charge de travail est disponible pour les éléments suivants :

  • Fournisseur Terraform Datadog : Authentifiez les opérations Terraform en utilisant des identifiants AWS mappés à un utilisateur ou un compte de service Datadog. Disponible pour tous les clients.
  • Datadog Agent : Authentifiez l'Agent en utilisant des identifiants AWS pour recevoir des clés d'API gérées et renouvelées automatiquement.
  • Fournisseur Terraform Datadog : Authentifiez les opérations Terraform en utilisant des identifiants AWS mappés à un utilisateur ou un compte de service Datadog. Disponible pour tous les clients.

Fonctionnement : processus d’authentification AWS

Le processus d’authentification utilise le AWS Security Token Service (STS) pour vérifier votre identité.

Flux d’authentification du fournisseur Terraform

  1. Génération de preuve : Le fournisseur Datadog Terraform crée une requête AWS STS GetCallerIdentity signée en utilisant vos identifiants AWS actuels
  2. Validation de preuve : Datadog valide la preuve en appelant AWS STS, qui renvoie votre ARN AWS, votre ID utilisateur et votre ID de compte
  3. Mappage d’identité : Votre identité AWS est mappée à un compte de service ou un compte utilisateur Datadog en fonction de la configuration de votre organisation
  4. Émission de jeton : Si la validation réussit, Datadog émet un jeton JWT temporaire pour l’accès à l’API
  5. Authentification API : Le jeton est utilisé pour les appels de Datadog API ultérieurs
Si possible, mappez les ARN à un compte de service Datadog plutôt qu'à un compte utilisateur. L'utilisation d'un compte de service évite d'associer votre processus d'authentification à une personne spécifique.

Flux d’authentification de l’Agent

  1. Détection des identifiants : L’Agent récupère les identifiants AWS depuis l’environnement dans lequel il s’exécute
  2. Génération de preuve : L’Agent crée une requête AWS STS signée pour prouver l’accès aux identifiants
  3. Validation de preuve : Datadog valide la requête signée auprès d’AWS et la vérifie par rapport à la configuration de mappage d’ingestion de votre organisation
  4. Émission de clé d’API : Si la validation réussit, Datadog émet une clé d’API gérée qui est automatiquement renouvelée
  5. Configuration de l’Agent : L’Agent utilise la clé d’API émise pour tous les appels de Datadog API ultérieurs
Si le flux d'authentification déléguée échoue, l'Agent revient à la clé d'API configurée dans votre datadog.yaml fichier. Ce comportement de secours vous permet d'effectuer l'intégration avec un risque limité pour votre configuration existante.

Configurer la fédération d’identités de charge de travail pour AWS

Prérequis :

  • Version 3.70 ou ultérieure du fournisseur Terraform Datadog.
  • Vous avez configuré l’intégration Datadog-AWS et ajouté votre compte AWS. Consultez la documentation sur l’intégration AWS.
  • Votre compte dispose des autorisations workload_identity_federation_config_read et workload_identity_federation_config_write.

La configuration de la fédération d’identité de charge de travail pour AWS comprend deux parties :

  1. Configuration de votre mappage d’identité AWS dans Datadog
  2. Mise à jour de la configuration de votre fournisseur Terraform

Configurer le mappage d’identité AWS dans Datadog

Pour que le mappage d'identité fonctionne, votre compte AWS doit être intégré à Datadog via l'intégration Datadog-AWS. Si un compte AWS n'est pas intégré, le flux d'authentification ne peut pas vérifier l'appelant et le mappage échoue.

Mappez vos identités AWS (ARN) vers des comptes de service ou des comptes utilisateur Datadog. Vous pouvez configurer les mappages d’identité depuis l’interface utilisateur ou en utilisant l’API.

Si vous devez créer des rôles IAM dans AWS, consultez la documentation sur la création de rôles IAM AWS.

Utilisation de l’interface utilisateur

Accédez à Paramètres de l’organisation > Fédération d’identité de charge de travail et cliquez sur l’onglet Mappages d’identité. Chaque mappage accorde à un rôle cloud les autorisations d’un utilisateur Datadog ou d’un compte de service spécifique.

Onglet Mappages d'identité dans la page Fédération d'identité de charge de travail, affichant le champ UUID de l'organisation et une liste de modèles ARN AWS mappés aux utilisateurs et comptes de service Datadog
Datadog nécessite l'ARN de rôle assumé dans le champ Modèle source, et non l'ARN de rôle IAM. Ces deux formats sont différents :
  • ARN de rôle IAM (affiché dans la console AWS) : arn:aws:iam::123456789012:role/my-role
  • ARN de rôle assumé (requis par Datadog) : arn:aws:sts::123456789012:assumed-role/my-role/session-name
Pour trouver l'ARN de rôle assumé pour votre charge de travail, exécutez aws sts get-caller-identity depuis votre environnement de charge de travail et utilisez la valeur dans le Arn champ de la réponse.

Pour créer un mappage d’identité :

  1. Cliquez sur + New Mapping.
  2. Sélectionnez un fournisseur cloud.
  3. Saisissez un modèle source (ARN). Utilisez le format ARN de rôle assumé et * pour les modèles génériques (par exemple, arn:aws:sts::123456789012:assumed-role/terraform-runner/*).
  4. Recherchez et sélectionnez une identité cible. Il s’agit du compte utilisateur ou du compte de service Datadog sous lequel cette identité cloud s’authentifie.
  5. Cliquez sur Create Mapping.
Boîte de dialogue Créer un mappage d'identité avec des champs pour le fournisseur cloud, le modèle d'ARN source et l'identité cible, avec un texte d'aide décrivant la prise en charge des modèles avec caractères génériques
Privilégiez les comptes de service aux comptes utilisateur pour éviter de lier l'accès à des individus.

Utilisation de l’API

Mapper un ARN AWS à un compte utilisateur Datadog

Pour account_identifier, utilisez l’e-mail indiqué dans le profil Datadog de l’utilisateur.

Exemple : Un appel API qui mappe un ARN AWS à un compte utilisateur Datadog, john.doe@myorg.com.

# 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"
    }
  }
}'
Mapper un ARN AWS à un compte de service Datadog

Pour account_identifier, vous pouvez utiliser soit :

  • Le UUID du compte de service : Allez dans Organization settings > Service accounts, cliquez sur le compte de service que vous souhaitez mapper, et copiez le service_account_id depuis l’URL. Par exemple, si l’URL se termine par /organization-settings/service-accounts?service_account_id=3fa85f64-5717-4562-b3fc-2c963f66afa6, alors utilisez 3fa85f64-5717-4562-b3fc-2c963f66afa6.
  • L’adresse e-mail du compte de service : Utilisez l’adresse e-mail indiquée dans les détails du compte de service.

Exemple : Un appel API qui mappe un ARN AWS à un compte de service Datadog en utilisant l’UUID, 3fa85f64-5717-4562-b3fc-2c963f66afa6.

# 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"
    }
  }
}'

Exemple : Un appel API qui mappe un ARN AWS à un compte de service Datadog en utilisant l’adresse e-mail, terraform-service-account@myorg.com.

# 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"
    }
  }
}'
Utilisation de caractères génériques dans les modèles d’ARN

Les modèles d’ARN prennent en charge la correspondance par caractères génériques pour gérer les parties dynamiques ou variables des ARN de ressources. Ceci est utile lorsque vous travaillez avec des rôles assumés qui incluent des identifiants de session ou d’autres composants variables.

Règles pour les caractères génériques :

  • Les caractères génériques (*) ne sont autorisés que dans la dernière partie de l’ARN de la ressource
  • Vous devez spécifier une ressource précise avant le caractère générique
  • Les caractères génériques ne peuvent pas être placés au milieu de l’ARN

Exemple : Correspond à toute session assumant le DatadogTerraformerRole :

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/*"
    }
  }
}'

Ce modèle correspond aux ARN de rôle assumé réels tels que :

  • arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/run-abcdefghijk
  • arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/session-xyz789
La correspondance par caractère générique est particulièrement utile pour les pipelines CI/CD où les sessions de rôle ont des identifiants générés dynamiquement.
Lister les mappages existants
curl -X GET "/api/v2/cloud_auth/aws/persona_mapping" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Mettez à jour votre configuration de fournisseur Terraform

Après avoir configuré le mappage d’identité, mettez à jour votre configuration de fournisseur Terraform Datadog pour utiliser Workload Identity Federation :

Supprimez votre configuration existante

# Old configuration
provider "datadog" {
  api_key = var.datadog_api_key
  app_key = var.datadog_app_key
}

Ajoutez la nouvelle configuration de Workload Identity Federation

Pour obtenir votre org_uuid, trouvez-le directement sur la page Organization Settings > Workload Identity Federation, ou appelez cet endpoint (nécessite une session active dans l’organisation cible) : /api/v2/current_user

# New configuration using AWS authentication
provider "datadog" {
  org_uuid             = var.datadog_org_uuid
  cloud_provider_type  = "aws"
}

Optionnel - Spécifiez explicitement les identifiants AWS

En alternative à l’utilisation de variables d’environnement ou de fichiers d’identifiants AWS, vous pouvez spécifier les identifiants AWS directement dans votre configuration Terraform :

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
}

Le fournisseur Terraform utilise automatiquement vos identifiants AWS configurés pour s’authentifier auprès de Datadog.

Configurez Workload Identity Federation pour le Datadog Agent

Workload Identity Federation pour le Datadog Agent n'est pas disponible pour le site Datadog sélectionné ().

Workload Identity Federation pour l’Agent vous permet d’authentifier votre Agent en utilisant des identifiants AWS au lieu de gérer des clés d’API statiques. L’Agent échange une preuve d’authentification AWS contre une clé d’API gérée que Datadog fait pivoter automatiquement.

Prérequis

  • Une version et un type d’Agent pris en charge selon la manière dont l’Agent obtient les identifiants AWS. Consultez les versions d’Agent prises en charge et les identifiants AWS.
  • Un Agent fonctionnant dans un environnement AWS avec accès aux identifiants AWS (par exemple, une instance EC2 avec un rôle IAM, une tâche ECS ou un pod EKS).
  • Une intégration Datadog-AWS configurée avec votre compte AWS ajouté.
  • Les autorisations workload_identity_federation_config_read et workload_identity_federation_config_write.

Versions d’Agent prises en charge et identifiants AWS

La prise en charge de la fédération d’identité de charge de travail dépend de la version de l’Agent, du type d’Agent et de la manière dont l’Agent obtient les identifiants AWS.

Comment l’Agent obtient les identifiants AWSAgent 7.78-7.81Agent 7.82Agent 7.83+
Variables d’environnement (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)Tous les AgentsTous les AgentsTous les Agents
Rôle du service de métadonnées d’instance EC2 (IMDS)Agents principaux uniquementAgents principaux uniquementTous les Agents
EKS IRSA (AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE)Non pris en chargeAgents principaux uniquementTous les Agents
Rôle de tâche ECS ou identité de pod EKS (AWS_CONTAINER_CREDENTIALS_*)Non pris en chargeAgents principaux uniquementTous les Agents

Agents principaux : l’Agent, l’Agent de cluster, l’Agent de processus, l’Agent de sécurité, la sonde système et le programme d’installation.

Tous les Agents : les Agents principaux ainsi que l’Agent de trace, DogStatsD autonome, le Private Action Runner, l’IoT Agent et l’Agent Heroku.

Le collecteur OpenTelemetry (otel-agent) ne prend pas en charge la fédération d’identité de charge de travail. AWS est le seul fournisseur cloud pris en charge. Azure, Google Cloud et les fournisseurs OIDC génériques ne sont pas pris en charge.

Pour un type d'Agent, un fournisseur cloud ou un mode de fourniture d'identifiants non pris en charge, ouvrez une demande de fonctionnalité auprès du support Datadog.

La configuration de la fédération d’identité de charge de travail pour l’Agent comprend deux parties :

  1. Configuration de votre mappage d’ingestion AWS dans Datadog
  2. Mise à jour de la configuration de votre Agent

Configurez le mappage d’ingestion AWS dans Datadog

Pour que le mappage d'ingestion fonctionne, votre compte AWS doit être intégré à Datadog via l'intégration Datadog-AWS. Si un compte AWS n'est pas intégré, le flux d'authentification ne peut pas vérifier l'appelant et le mappage échoue.

Configurez les mappages d’ingestion pour autoriser des modèles ARN AWS spécifiques pour l’authentification de l’Agent. Contrairement aux mappages d’identité, les mappages d’ingestion nécessitent uniquement un modèle ARN. Aucun identifiant de compte Datadog n’est nécessaire, car l’Agent s’authentifie pour envoyer des données plutôt que pour effectuer des actions utilisateur. Datadog provisionne, configure et fait pivoter automatiquement la clé d’API sous-jacente pour vous.

Si vous devez créer des rôles IAM dans AWS, consultez la documentation sur la création de rôles IAM AWS.

Utilisation de l’interface utilisateur

Accédez à Paramètres d’organisation > Fédération d’identité de charge de travail et cliquez sur l’onglet Mappages d’ingestion.

Onglet Mappages d'ingestion dans la page Fédération d'identité de charge de travail, affichant le champ UUID de l'organisation et une liste de modèles ARN AWS autorisés pour l'authentification de l'Agent
Datadog nécessite l'ARN de rôle assumé dans le champ Modèle source, et non l'ARN de rôle IAM. Ces deux formats sont différents :
  • ARN de rôle IAM (affiché dans la console AWS) : arn:aws:iam::123456789012:role/my-role
  • ARN de rôle assumé (requis par Datadog) : arn:aws:sts::123456789012:assumed-role/my-role/session-name
Pour trouver l'ARN de rôle assumé pour votre charge de travail, exécutez aws sts get-caller-identity depuis votre environnement de charge de travail et utilisez la valeur dans le Arn champ de la réponse.

Pour créer un mappage d’ingestion :

  1. Cliquez sur + New Mapping.
  2. Sélectionnez un fournisseur cloud.
  3. Saisissez un modèle source (ARN). Utilisez le format ARN de rôle assumé et * pour les modèles génériques (par exemple, arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*).
  4. Cliquez sur Create Mapping.
Boîte de dialogue Créer un mappage d'ingestion avec des champs pour le fournisseur cloud et l'ARN du modèle source, avec un texte d'aide décrivant la prise en charge des modèles avec caractères génériques

Utilisation de l’API

Créer un mappage d’ingestion

Exemple: un appel d’API qui autorise les agents s’exécutant avec un rôle IAM spécifique à s’authentifier.

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/*"
    }
  }
}'
Utilisation de caractères génériques dans les modèles d’ARN

Les modèles d’ARN prennent en charge la correspondance par caractères génériques pour gérer les parties dynamiques ou variables des ARN de ressources. Ceci est utile lorsque vous travaillez avec des rôles assumés qui incluent des identifiants de session ou lorsque vous avez plusieurs instances d’Agent.

Règles pour les caractères génériques :

  • Les caractères génériques (*) ne sont autorisés que dans la dernière partie de l’ARN de la ressource
  • Vous devez spécifier une ressource précise avant le caractère générique
  • Les caractères génériques ne peuvent pas être placés au milieu de l’ARN

Exemple : Correspond à toute session assumant le DatadogAgentRole :

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/*"
    }
  }
}'

Ce modèle correspond aux ARN de rôle assumé réels tels que :

  • arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/i-0abc123def456
  • arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/eks-datadog-agent-xyz
Lister les mappages d’ingestion existants
curl -X GET "/api/v2/cloud_auth/aws/intake_mapping" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
Supprimer un mappage d’ingestion
curl -X DELETE "/api/v2/cloud_auth/aws/intake_mapping/<MAPPING_UUID>" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Mettre à jour votre configuration d’Agent

Après avoir configuré le mappage d’ingestion, mettez à jour la configuration de l’Agent pour utiliser la fédération d’identité de charge de travail.

Configuration globale

Ajoutez la section delegated_auth à votre fichier datadog.yaml pour activer la fédération d’identité de charge de travail pour toutes les données de l’Agent :

delegated_auth:
  org_uuid: <YOUR_ORG_UUID>

Pour obtenir votre org_uuid, trouvez-le directement sur la page Organization Settings > Workload Identity Federation, ou appelez cet endpoint (nécessite une session active dans l’organisation cible) : /api/v2/current_user

L’Agent détecte automatiquement s’il s’exécute dans un environnement AWS et utilise les identifiants AWS disponibles.

Options spécifiques au fournisseur

Pour configurer explicitement AWS comme fournisseur d’authentification et spécifier des options spécifiques au fournisseur, utilisez les sous-sections provider et aws :

delegated_auth:
  org_uuid: <YOUR_ORG_UUID>
  provider: aws  # Optional: auto-detects if omitted
  aws:
    region: <AWS_REGION>  # Optional: auto-detects from IMDS if omitted or uses global STS

Remplacez <AWS_REGION> par la région AWS à utiliser pour l’authentification STS (par exemple, us-east-1).

Configuration par produit

Vous pouvez activer l’authentification déléguée pour des produits Agent spécifiques indépendamment. Ceci est utile lorsque vous souhaitez envoyer différents types de données à différentes organisations Datadog, ou lorsque vous souhaitez uniquement utiliser la Fédération d’identité de charge de travail pour des produits spécifiques.

Pour activer l’authentification déléguée pour les logs uniquement :

logs_config:
  delegated_auth:
    org_uuid: <YOUR_ORG_UUID>

Pour utiliser des organisations différentes pour des produits différents :

delegated_auth:
  org_uuid: <YOUR_GLOBAL_ORG_UUID>
  provider: aws
  aws:
    region: <AWS_REGION>

logs_config:
  delegated_auth:
    org_uuid: <YOUR_LOGS_ORG_UUID>
Paramètres spécifiques au fournisseur (tels que provider et aws) ne sont configurés que dans le global delegated_auth section. Les sections par produit ne prennent en charge que org_uuid.

Comportement de repli

Si le flux d’authentification déléguée échoue pour une raison quelconque, l’Agent revient automatiquement à l’utilisation de la clé d’API configurée dans votre fichier datadog.yaml. Ce comportement de repli fournit un filet de sécurité lors de l’intégration et protège contre les interruptions du service d’authentification.

Pour tirer parti de ce repli, conservez votre configuration api_key existante parallèlement à la nouvelle configuration delegated_auth :

api_key: <YOUR_API_KEY>

delegated_auth:
  org_uuid: <YOUR_ORG_UUID>

Pour aller plus loin