From 700dcfc224d0aac13d7f88f6d3257843ecf98486 Mon Sep 17 00:00:00 2001
From: Stephen Rosenthal <stephen.rosenthal@datadoghq.com>
Date: Wed, 12 Aug 2026 18:55:24 -0700
Subject: [PATCH] cloud-auth: document opt-in OAuth scopes for persona-mappings
 | DAL-981

pup's cloud-auth persona-mappings commands already send the OAuth bearer
token automatically. The routes now accept it server-side, but require
workload_identity_federation_read/write -- permissions only ever granted
to admins, so they're opt-in via --extra-scopes rather than added to
default_scopes(), matching the existing precedent for other admin-only
scopes (api_keys_*, app_keys_*, service_account_write).
---
 src/auth/types.rs | 17 +++++++++++++++++
 src/main.rs       |  8 +++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/auth/types.rs b/src/auth/types.rs
index 19bd5f74..ad3184d7 100644
--- a/src/auth/types.rs
+++ b/src/auth/types.rs
@@ -400,6 +400,23 @@ mod tests {
         assert!(!ro.contains(&"logs_write_pipelines"));
     }
 
+    #[test]
+    fn test_default_scopes_excludes_workload_identity_federation() {
+        let scopes = default_scopes();
+        // workload_identity_federation_read/write are only ever granted to
+        // admins, so they're opt-in only (see 'pup cloud-auth' AUTHENTICATION
+        // doc) rather than requested by default.
+        assert!(!scopes.contains(&"workload_identity_federation_read"));
+        assert!(!scopes.contains(&"workload_identity_federation_write"));
+    }
+
+    #[test]
+    fn test_read_only_scopes_excludes_workload_identity_federation() {
+        let ro = read_only_scopes();
+        assert!(!ro.contains(&"workload_identity_federation_read"));
+        assert!(!ro.contains(&"workload_identity_federation_write"));
+    }
+
     #[test]
     fn test_read_only_scopes_subset_of_default() {
         let default: std::collections::HashSet<&str> = default_scopes().into_iter().collect();
diff --git a/src/main.rs b/src/main.rs
index cefe69b1..9e171c3d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -7902,7 +7902,13 @@ enum IntegrationActions {
 #[derive(Subcommand)]
 enum IntegrationAwsActions {
     /// Manage AWS cloud authentication
-    #[command(name = "cloud-auth")]
+    ///
+    /// AUTHENTICATION:
+    ///   Requires OAuth2 (via 'pup auth login') or API + Application keys.
+    ///   OAuth2 requires the workload_identity_federation_read/write scopes,
+    ///   which are not requested by default -- opt in with:
+    ///     pup auth login --extra-scopes workload_identity_federation_read,workload_identity_federation_write
+    #[command(name = "cloud-auth", verbatim_doc_comment)]
     CloudAuth {
         #[command(subcommand)]
         action: CloudAuthActions,