impl(oauth2): add support for creating GDCH credentials for use with REST endpoints (googleapis#16129)

Author: scotthart

CHANGELOG.md

@@ -20,6 +20,13 @@ the APIs in these libraries are stable, and are ready for production use.
 
 - [Network Security API] has been updated with several additional services ([#16122](https://github.com/googleapis/google-cloud-cpp/pull/16122)) 
 
+### Auth
+
+- [Google Distributed Cloud Hosting (GDCH) Service Account credentials](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/service-identity)
+  are now supported for REST endpoints. Support for gRPC endpoints will be
+  available in a future release.
+
+
 ## v3.5.0 - 2026-05
 
 ### [Bigtable](/google/cloud/bigtable/README.md)

google/cloud/credentials.cc

@@ -74,6 +74,18 @@ std::shared_ptr<Credentials> MakeComputeEngineCredentials(Options opts) {
       std::move(opts));
 }
 
+std::shared_ptr<Credentials> MakeGDCHServiceAccountCredentials(
+    std::string json_object, std::string audience, Options opts) {
+  return std::make_shared<internal::GDCHServiceAccountConfig>(
+      std::move(json_object), std::move(audience), std::move(opts));
+}
+
+std::shared_ptr<Credentials> MakeGDCHServiceAccountCredentials(
+    std::string audience, Options opts) {
+  return std::make_shared<internal::GDCHServiceAccountConfig>(
+      std::move(audience), std::move(opts));
+}
+
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace cloud
 }  // namespace google

google/cloud/credentials.h

@@ -454,6 +454,39 @@ std::shared_ptr<Credentials> MakeApiKeyCredentials(std::string api_key,
  */
 std::shared_ptr<Credentials> MakeComputeEngineCredentials(Options opts = {});
 
+/**
+ * Creates credentials for a Google Distributed Cloud Hosting (GDCH) Service
+ * Account.
+ *
+ * @see https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag
+ *     for more information on GDCH air-gapped environments.
+ *
+ *
+ * @see https://cloud.google.com/docs/authentication for more information on
+ *     authentication in GCP.
+ *
+ * @see https://cloud.google.com/docs/authentication/client-libraries for more
+ *     information on authentication for client libraries.
+ *
+ * [aip/4115]: https://google.aip.dev/auth/4115
+ *
+ * @ingroup guac
+ *
+ * @param json_object service account configuration as a JSON string. If
+ *     omitted, the contents of the file at GOOGLE_APPLICATION_CREDENTIALS is
+ *     used.
+ *
+ * @param audience authentication endpoint for the service identity.
+ *
+ * @param opts optional configuration values.  Note that the effect of these
+ *     parameters depends on the underlying transport. For example,
+ *     `LoggingComponentsOption` is ignored by gRPC-based services.
+ */
+std::shared_ptr<Credentials> MakeGDCHServiceAccountCredentials(
+    std::string json_object, std::string audience, Options opts = {});
+std::shared_ptr<Credentials> MakeGDCHServiceAccountCredentials(
+    std::string audience, Options opts = {});
+
 /**
  * Configure the delegates for `MakeImpersonateServiceAccountCredentials()`
  *

google/cloud/internal/credentials_impl.cc

@@ -14,6 +14,7 @@
 
 #include "google/cloud/internal/credentials_impl.h"
 #include "google/cloud/common_options.h"
+#include "google/cloud/internal/getenv.h"
 #include "google/cloud/internal/populate_common_options.h"
 #include <chrono>
 
@@ -117,6 +118,19 @@ AuthorizedUserConfig::AuthorizedUserConfig(std::string json_object,
     : json_object_(std::move(json_object)),
       options_(PopulateAuthOptions(std::move(opts))) {}
 
+GDCHServiceAccountConfig::GDCHServiceAccountConfig(std::string json_object,
+                                                   std::string audience,
+                                                   Options opts)
+    : json_object_(std::move(json_object)),
+      audience_(std::move(audience)),
+      options_(PopulateAuthOptions(std::move(opts))) {}
+
+GDCHServiceAccountConfig::GDCHServiceAccountConfig(std::string audience,
+                                                   Options opts)
+    : file_path_(GetEnv("GOOGLE_APPLICATION_CREDENTIALS")),
+      audience_(std::move(audience)),
+      options_(PopulateAuthOptions(std::move(opts))) {}
+
 }  // namespace internal
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace cloud

google/cloud/internal/credentials_impl.h

@@ -20,10 +20,10 @@
 #include "google/cloud/options.h"
 #include "google/cloud/status_or.h"
 #include "google/cloud/version.h"
-#include "absl/types/optional.h"
 #include <chrono>
 #include <functional>
 #include <memory>
+#include <optional>
 #include <string>
 #include <vector>
 
@@ -42,6 +42,7 @@ class ExternalAccountConfig;
 class ApiKeyConfig;
 class ComputeEngineCredentialsConfig;
 class AuthorizedUserConfig;
+class GDCHServiceAccountConfig;
 
 std::shared_ptr<Credentials> MakeErrorCredentials(Status error_status);
 
@@ -70,6 +71,7 @@ class CredentialsVisitor {
   virtual void visit(ApiKeyConfig const&) = 0;
   virtual void visit(ComputeEngineCredentialsConfig const&) = 0;
   virtual void visit(AuthorizedUserConfig const&) = 0;
+  virtual void visit(GDCHServiceAccountConfig const&) = 0;
 
   static void dispatch(Credentials const& credentials,
                        CredentialsVisitor& visitor);
@@ -161,20 +163,18 @@ class ServiceAccountConfig : public Credentials {
   // Only one of json_object or file_path should have a value.
   // TODO(#15886): Use the C++ type system to make better constructors that
   //   enforces this comment.
-  ServiceAccountConfig(absl::optional<std::string> json_object,
-                       absl::optional<std::string> file_path, Options opts);
+  ServiceAccountConfig(std::optional<std::string> json_object,
+                       std::optional<std::string> file_path, Options opts);
 
-  absl::optional<std::string> const& json_object() const {
-    return json_object_;
-  }
-  absl::optional<std::string> const& file_path() const { return file_path_; }
+  std::optional<std::string> const& json_object() const { return json_object_; }
+  std::optional<std::string> const& file_path() const { return file_path_; }
   Options const& options() const { return options_; }
 
  private:
   void dispatch(CredentialsVisitor& v) const override { v.visit(*this); }
 
-  absl::optional<std::string> json_object_;
-  absl::optional<std::string> file_path_;
+  std::optional<std::string> json_object_;
+  std::optional<std::string> file_path_;
   Options options_;
 };
 
@@ -235,6 +235,28 @@ class AuthorizedUserConfig : public Credentials {
   Options options_;
 };
 
+class GDCHServiceAccountConfig : public Credentials {
+ public:
+  GDCHServiceAccountConfig(std::string json_object, std::string audience,
+                           Options opts);
+  GDCHServiceAccountConfig(std::string audience, Options opts);
+
+  ~GDCHServiceAccountConfig() override = default;
+
+  std::optional<std::string> const& file_path() const { return file_path_; }
+  std::string const& json_object() const { return json_object_; }
+  std::string const& audience() const { return audience_; }
+  Options const& options() const { return options_; }
+
+ private:
+  void dispatch(CredentialsVisitor& v) const override { v.visit(*this); }
+
+  std::optional<std::string> file_path_ = std::nullopt;
+  std::string json_object_;
+  std::string audience_;
+  Options options_;
+};
+
 /// A helper function to initialize Auth options.
 Options PopulateAuthOptions(Options options);
 

google/cloud/internal/credentials_impl_test.cc

@@ -135,6 +135,17 @@ TEST(Credentials, AuthorizedUserCredentials) {
               ElementsAre("scope1", "scope2"));
 }
 
+TEST(Credentials, GDCHServiceAccountCredentials) {
+  TestCredentialsVisitor visitor;
+
+  auto credentials =
+      MakeGDCHServiceAccountCredentials("test-json", "test-audience");
+  CredentialsVisitor::dispatch(*credentials, visitor);
+  EXPECT_EQ("GDCHServiceAccountConfig", visitor.name);
+  EXPECT_EQ("test-json", visitor.json_object);
+  EXPECT_EQ("test-audience", visitor.audience);
+}
+
 TEST(PopulateAuthOptions, EmptyOptions) {
   auto result_options = PopulateAuthOptions(Options{});
 

google/cloud/internal/unified_grpc_credentials.cc

@@ -161,6 +161,13 @@ std::shared_ptr<GrpcAuthenticationStrategy> CreateAuthenticationStrategy(
               "or Access Token Credentials instead.",
               GCP_ERROR_INFO())});
     }
+    void visit(GDCHServiceAccountConfig const&) override {
+      result = std::make_unique<GrpcErrorCredentialsAuthentication>(
+          ErrorCredentialsConfig{
+              UnimplementedError("GDCHServiceAccountCredentials are not yet "
+                                 "supported for gRPC endpoints",
+                                 GCP_ERROR_INFO())});
+    }
 
   } visitor(std::move(cq), std::move(options));
 

google/cloud/internal/unified_rest_credentials.cc

@@ -24,6 +24,7 @@
 #include "google/cloud/internal/oauth2_decorate_credentials.h"
 #include "google/cloud/internal/oauth2_error_credentials.h"
 #include "google/cloud/internal/oauth2_external_account_credentials.h"
+#include "google/cloud/internal/oauth2_gdch_service_account_credentials.h"
 #include "google/cloud/internal/oauth2_google_credentials.h"
 #include "google/cloud/internal/oauth2_impersonate_service_account_credentials.h"
 #include "google/cloud/internal/oauth2_service_account_credentials.h"
@@ -41,6 +42,7 @@ using ::google::cloud::internal::ComputeEngineCredentialsConfig;
 using ::google::cloud::internal::CredentialsVisitor;
 using ::google::cloud::internal::ErrorCredentialsConfig;
 using ::google::cloud::internal::ExternalAccountConfig;
+using ::google::cloud::internal::GDCHServiceAccountConfig;
 using ::google::cloud::internal::GoogleDefaultCredentialsConfig;
 using ::google::cloud::internal::ImpersonateServiceAccountConfig;
 using ::google::cloud::internal::InsecureCredentialsConfig;
@@ -154,6 +156,30 @@ std::shared_ptr<oauth2_internal::Credentials> MapCredentials(
       result =
           Decorate(std::move(creds), std::move(client_factory_), cfg.options());
     }
+    void visit(GDCHServiceAccountConfig const& cfg) override {
+      auto options = cfg.options();
+      StatusOr<std::unique_ptr<oauth2_internal::Credentials>> creds;
+      if (cfg.file_path().has_value()) {
+        creds =
+            oauth2_internal::GDCHServiceAccountCredentials::CreateFromFilePath(
+                *cfg.file_path(), cfg.audience(), options, client_factory_);
+      } else if (!cfg.json_object().empty()) {
+        creds = oauth2_internal::GDCHServiceAccountCredentials::
+            CreateFromJsonContents(cfg.json_object(), cfg.audience(), options,
+                                   client_factory_);
+      } else {
+        creds = internal::InvalidArgumentError(
+            "GDCH ServiceAccount Credentials require either a JSON object or "
+            "the "
+            "GOOGLE_APPLICATION_CREDENTIALS environment variable to be set");
+      }
+      if (!creds.ok()) {
+        result = MakeErrorCredentials(std::move(creds).status());
+      } else {
+        result = Decorate(*std::move(creds), std::move(client_factory_),
+                          std::move(options));
+      }
+    }
 
     void visit(AuthorizedUserConfig const& cfg) override {
       auto info = oauth2_internal::ParseAuthorizedUserCredentials(

google/cloud/internal/unified_rest_credentials_integration_test.cc

@@ -34,7 +34,11 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 namespace {
 
 using ::google::cloud::testing_util::IsOk;
+using ::google::cloud::testing_util::IsOkAndHolds;
 using ::google::cloud::testing_util::ScopedEnvironment;
+using ::testing::IsEmpty;
+using ::testing::Not;
+using ::testing::NotNull;
 
 auto constexpr kEndpointThatUsesRAB = "storage.googleapis.com";
 
@@ -355,6 +359,26 @@ TEST(UnifiedRestCredentialsIntegrationTest, StorageSelfSignedJWT) {
           MakeServiceAccountCredentials(contents))));
 }
 
+MATCHER(AccessTokenIsSTSBearer, "access token is STS Bearer") {
+  return absl::StartsWith(arg.token, "STS-Bearer-");
+}
+
+TEST(UnifiedRestCredentialsIntegrationTest, GDCHServiceAccountCredentials) {
+  auto key_file_env =
+      internal::GetEnv("GOOGLE_CLOUD_CPP_REST_TEST_GDCH_KEY_FILE");
+  if (!key_file_env.has_value()) GTEST_SKIP();
+  std::ifstream is(*key_file_env);
+  auto contents = std::string{std::istreambuf_iterator<char>{is}, {}};
+  ASSERT_THAT(contents, Not(IsEmpty()));
+
+  std::string const audience = "global-api";
+  auto gdch_creds = MakeGDCHServiceAccountCredentials(contents, audience);
+  ASSERT_THAT(gdch_creds, NotNull());
+  auto oauth2_creds = MapCredentials(*gdch_creds);
+  EXPECT_THAT(oauth2_creds->GetToken(std::chrono::system_clock::now()),
+              IsOkAndHolds(AccessTokenIsSTSBearer()));
+}
+
 }  // namespace
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace rest_internal