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).

Author: srosenthal-dd

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();

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,