L126: C-core: Support ALTS Credentials in Google Default Credentials

L126-core-add-alts-google-call-credentials.md

@@ -0,0 +1,122 @@
+# L126: C-core: Support ALTS Hard Bound Call Credentials in Google Default Credentials
+
+*   Author(s): anniefrchz
+*   Approver: markdroth
+*   Status: In Review
+*   Implemented in: C++
+*   Last updated: 2025-08-22
+*   Discussion at:
+    https://groups.google.com/g/grpc-io/c/7rRWghiS95E/m/nENwU3BtCgAJ
+
+## Abstract
+
+This proposal outlines a change to the gRPC Core C-API to support
+alts-credentials configurations within `grpc_google_default_credentials`. This
+enhancement specifically allows a secondary set of call credentials for ALTS to
+be provided alongside the default credentials.
+
+## Background
+
+The existing `grpc_google_default_credentials_create` function allows the
+configuration of a single set of call credentials. In some scenarios, a client
+would want to communicate with services that support hard bound credentials over
+ALTS. This proposal addresses the possibility to support this use case on a
+channel initialized with Google's default credentials.
+
+## Proposal
+
+### C-Core changes
+
+This proposal modifies the function `grpc_google_default_credentials_create` to
+add a second set of call credentials.
+
+```c
+GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(
+    grpc_call_credentials* tls_credentials,
+    grpc_call_credentials* alts_credentials);
+```
+
+This new function accepts two arguments:
+
+1.  `tls_credentials`: The primary call credentials, consistent with the
+    existing API. This is usually used for TLS connections.
+2.  `alts_credentials`: A secondary set of call credentials to be used
+    specifically for ALTS connections.
+
+After a secure connection is established, the gRPC runtime identifies the
+connection's transport security type, which indicates whether the underlying
+connection is using a protocol like ALTS or TLS. The runtime then selects the
+appropriate call credentials for that connection. If the determined transport
+security type is ALTS, the provided alts_credentials will be used. For all other
+transport types, the primary call_credentials are used, maintaining the default
+behavior.
+
+The hard-bound call credentials will be created through
+`grpc_google_compute_engine_credentials_create`. This function will have a
+`grpc_google_compute_engine_credentials_options` parameter. The caller will be
+able to obtain ALTS hard-bound credentials instead of the standard default call
+credentials by toggling the corresponding flag use_alts_call_credentials in the
+structure.
+
+```c
+typedef struct {
+  bool use_alts_call_credentials = false;
+} grpc_google_compute_engine_credentials_options;
+
+GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create(
+    grpc_google_compute_engine_credentials_options* options);
+```
+
+### C++ Changes
+
+Additionally, external customers for the public C++ library will de able to
+create GoogleDefaultCredentials by setting a GoogleDefaultCredentialsOptions
+value into their standard call. For this addition, the proposed struct
+`GoogleDefaultCredentialsOptions` will hold a boolean that will be default to
+false. Callers of the GoogleDefaultCredentials() API will be able to set
+use_alts_call_credentials to false value, if required to indicate the request
+for the underlying bound token call credentials.
+
+```c++
+struct GoogleDefaultCredentialsOptions {
+  bool use_alts_call_credentials = false;
+};
+
+std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials(
+    const GoogleDefaultCredentialsOptions& options =
+        GoogleDefaultCredentialsOptions());
+```
+
+### Other C-Core languages
+
+Other wrapped languages are not in scope for changes to their public API, and
+further discussion is needed if an implementation is scoped.
+
+## Rationale
+
+The primary motivation for this change is to enable seamless support for hybrid
+security environments on a single gRPC channel.
+
+The advantages of this approach are:
+
+*   Consolidated API: It avoids introducing a new function for a closely related
+    feature, keeping the API surface clean and concise. An initial review of the
+    pull request favored this path to avoid an unnecessary new API.
+*   Improved Discoverability: Developers only need to be aware of a single
+    function for creating Google default credentials. The optional nature of the
+    second parameter would make the basic use case simple while allowing for the
+    more advanced dual-credential scenario when needed.
+*   Logical Cohesion: Since the new functionality is an extension of the
+    existing credential creation process, incorporating it into the original
+    function maintains logical cohesion. The function's responsibility is
+    expanded rather than duplicated across multiple functions.
+*   Cross-language support: Since wrapper languages like Python use this API,
+    supporting ALTS bound credentials will be straightforward by passing them as
+    an argument to the existing API.
+
+## Implementation
+
+The implementation for this proposal has been completed and merged into the main
+gRPC repository.
+
+*   Pull Request: grpc/grpc#39770