feat: support mtls env variables (#589)

Implement the two mtls env variables mentioned in https://google.aip.dev/auth/4114

New behavior summary:
(1) GOOGLE_API_USE_CLIENT_CERTIFICATE env variable:
Values:
"true": use client cert if exists
"false" (default): never use client cert, even if it exists or it is explicitly provided by user
(2) GOOGLE_API_USE_MTLS_ENDPOINT env variable:
Values:
"never": use regular endpoint
"always": use mtls endpoint
"auto" (default): auto switch to mtls endpoint, if client cert exists and we are allowed to use it (controlled by GOOGLE_API_USE_CLIENT_CERTIFICATE)

gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2

@@ -2,6 +2,7 @@
 
 {% block content %}
 from collections import OrderedDict
+from distutils import util
 import os
 import re
 from typing import Callable, Dict, {% if service.any_server_streaming %}Iterable, {% endif %}{% if service.any_client_streaming %}Iterator, {% endif %}Sequence, Tuple, Type, Union
@@ -13,6 +14,7 @@ from google.api_core import gapic_v1                   # type: ignore
 from google.api_core import retry as retries           # type: ignore
 from google.auth import credentials                    # type: ignore
 from google.auth.transport import mtls                 # type: ignore
+from google.auth.transport.grpc import SslCredentials  # type: ignore
 from google.auth.exceptions import MutualTLSChannelError  # type: ignore
 from google.oauth2 import service_account              # type: ignore
 
@@ -151,16 +153,19 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             client_options (ClientOptions): Custom options for the client. It
                 won't take effect unless ``transport`` is None.
                 (1) The ``api_endpoint`` property can be used to override the
-                default endpoint provided by the client. GOOGLE_API_USE_MTLS
+                default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
                 environment variable can also be used to override the endpoint:
                 "always" (always use the default mTLS endpoint), "never" (always
-                use the default regular endpoint, this is the default value for
-                the environment variable) and "auto" (auto switch to the default
-                mTLS endpoint if client SSL credentials is present). However,
-                the ``api_endpoint`` property takes precedence if provided.
-                (2) The ``client_cert_source`` property is used to provide client
-                SSL credentials for mutual TLS transport. If not provided, the
-                default SSL credentials will be used if present.
+                use the default regular endpoint) and "auto" (auto switch to the
+                default mTLS endpoint if client certificate is present, this is
+                the default value). However, the ``api_endpoint`` property takes
+                precedence if provided.
+                (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+                is "true", then the ``client_cert_source`` property can be used
+                to provide client certificate for mutual TLS transport. If
+                not provided, the default SSL client certificate will be used if
+                present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+                set, no client certificate will be used.
             client_info (google.api_core.gapic_v1.client_info.ClientInfo):	
                 The client info used to send a user-agent string along with	
                 API requests. If ``None``, then default info will be used.	
@@ -175,24 +180,40 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             client_options = ClientOptions.from_dict(client_options)
         if client_options is None:
             client_options = ClientOptions.ClientOptions()
+
+        # Create SSL credentials for mutual TLS if needed.
+        use_client_cert = bool(util.strtobool(os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")))
+
+        ssl_credentials = None
+        is_mtls = False
+        if use_client_cert:
+            if client_options.client_cert_source:
+                import grpc  # type: ignore
+
+                cert, key = client_options.client_cert_source()
+                ssl_credentials = grpc.ssl_channel_credentials(
+                    certificate_chain=cert, private_key=key
+                )
+                is_mtls = True
+            else:
+                creds = SslCredentials()
+                is_mtls = creds.is_mtls
+                ssl_credentials = creds.ssl_credentials if is_mtls else None
 
-        if transport is None and client_options.api_endpoint is None:
-            use_mtls_env = os.getenv("GOOGLE_API_USE_MTLS", "never")
+        # Figure out which api endpoint to use.
+        if client_options.api_endpoint is not None:
+            api_endpoint = client_options.api_endpoint
+        else:
+            use_mtls_env = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
             if use_mtls_env == "never":
-                client_options.api_endpoint = self.DEFAULT_ENDPOINT
+                api_endpoint = self.DEFAULT_ENDPOINT
             elif use_mtls_env == "always":
-                client_options.api_endpoint = self.DEFAULT_MTLS_ENDPOINT
+                api_endpoint = self.DEFAULT_MTLS_ENDPOINT
             elif use_mtls_env == "auto":
-                has_client_cert_source = (
-                    client_options.client_cert_source is not None
-                    or mtls.has_default_client_cert_source()
-                )
-                client_options.api_endpoint = (
-                    self.DEFAULT_MTLS_ENDPOINT if has_client_cert_source else self.DEFAULT_ENDPOINT
-                )
+                api_endpoint = self.DEFAULT_MTLS_ENDPOINT if is_mtls else self.DEFAULT_ENDPOINT
             else:
                 raise MutualTLSChannelError(
-                    "Unsupported GOOGLE_API_USE_MTLS value. Accepted values: never, auto, always"
+                    "Unsupported GOOGLE_API_USE_MTLS_ENDPOINT value. Accepted values: never, auto, always"
                 )
 
         # Save or instantiate the transport.
@@ -212,9 +233,8 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
         else:
             self._transport = {{ service.name }}GrpcTransport(
                 credentials=credentials,
-                host=client_options.api_endpoint,
-                api_mtls_endpoint=client_options.api_endpoint,
-                client_cert_source=client_options.client_cert_source,
+                host=api_endpoint,
+                ssl_channel_credentials=ssl_credentials,
                 client_info=client_info,
               )
 

gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/transports/grpc.py.j2

@@ -10,7 +10,6 @@ from google.api_core import operations_v1  # type: ignore
 from google.api_core import gapic_v1       # type: ignore
 from google import auth                    # type: ignore
 from google.auth import credentials        # type: ignore
-from google.auth.transport.grpc import SslCredentials  # type: ignore
 
 
 import grpc  # type: ignore
@@ -40,8 +39,7 @@ class {{ service.name }}GrpcTransport({{ service.name }}Transport):
             host: str{% if service.host %} = '{{ service.host }}'{% endif %},
             credentials: credentials.Credentials = None,
             channel: grpc.Channel = None,
-            api_mtls_endpoint: str = None,
-            client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+            ssl_channel_credentials: grpc.ChannelCredentials = None,
             client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
             ) -> None:
         """Instantiate the transport.
@@ -57,14 +55,8 @@ class {{ service.name }}GrpcTransport({{ service.name }}Transport):
                 This argument is ignored if ``channel`` is provided.
             channel (Optional[grpc.Channel]): A ``Channel`` instance through
                 which to make calls.
-            api_mtls_endpoint (Optional[str]): The mutual TLS endpoint. If
-                provided, it overrides the ``host`` argument and tries to create
-                a mutual TLS channel with client SSL credentials from
-                ``client_cert_source`` or applicatin default SSL credentials.
-            client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]): A
-                callback to provide client SSL certificate bytes and private key
-                bytes, both in PEM format. It is ignored if ``api_mtls_endpoint``
-                is None.
+            ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+                for grpc channel. It is ignored if ``channel`` is provided.
             client_info (google.api_core.gapic_v1.client_info.ClientInfo):	
                 The client info used to send a user-agent string along with	
                 API requests. If ``None``, then default info will be used.	
@@ -82,27 +74,17 @@ class {{ service.name }}GrpcTransport({{ service.name }}Transport):
 
             # If a channel was explicitly provided, set it.
             self._grpc_channel = channel
-        elif api_mtls_endpoint:
-            host = api_mtls_endpoint if ":" in api_mtls_endpoint else api_mtls_endpoint + ":443"
+        else:
+            host = host if ":" in host else host + ":443"
 
             if credentials is None:
                 credentials, _ = auth.default(scopes=self.AUTH_SCOPES)
 
-            # Create SSL credentials with client_cert_source or application
-            # default SSL credentials.
-            if client_cert_source:
-                cert, key = client_cert_source()
-                ssl_credentials = grpc.ssl_channel_credentials(
-                    certificate_chain=cert, private_key=key
-                )
-            else:
-                ssl_credentials = SslCredentials().ssl_credentials
-
             # create a new channel. The provided one is ignored.
             self._grpc_channel = grpc_helpers.create_channel(
                 host,
                 credentials=credentials,
-                ssl_credentials=ssl_credentials,
+                ssl_credentials=ssl_channel_credentials,
                 scopes=self.AUTH_SCOPES,
             )
 

gapic/ads-templates/setup.py.j2

@@ -16,7 +16,7 @@ setuptools.setup(
     platforms='Posix; MacOS X; Windows',
     include_package_data=True,
     install_requires=(
-        'google-api-core >= 1.17.0, < 2.0.0dev',
+        'google-api-core >= 1.22.2, < 2.0.0dev',
         'googleapis-common-protos >= 1.5.8',
         'grpcio >= 1.10.0',
         'proto-plus >= 1.4.0',