google.auth.transport.grpc module

Authorization support for gRPC.

class AuthMetadataPlugin(credentials, request)[source]

Bases: sphinx.ext.autodoc.importer._MockObject

A gRPC AuthMetadataPlugin that inserts the credentials into each request.

secure_authorized_channel(credentials, request, target, ssl_credentials=None, client_cert_callback=None, **kwargs)[source]

Creates a secure authorized gRPC channel.

This creates a channel with SSL and AuthMetadataPlugin. This channel can be used to create a stub that can make authorized requests.


import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
from import cloud_speech_pb2

# Get credentials.
credentials, _ = google.auth.default()

# Get an HTTP request function to refresh credentials.
request = google.auth.transport.requests.Request()

# Create a channel.
channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, regular_endpoint, request,

# Use the channel to create a stub.


There are actually a couple of options to create a channel, depending on if you want to create a regular or mutual TLS channel.

First let’s list the endpoints (regular vs mutual TLS) to choose from:

regular_endpoint = ''
mtls_endpoint = ''

Option 1: create a regular (non-mutual) TLS channel by explicitly setting the ssl_credentials:

regular_ssl_credentials = grpc.ssl_channel_credentials()

channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, regular_endpoint, request,

Option 2: create a mutual TLS channel by calling a callback which returns the client side certificate and the key:

def my_client_cert_callback():
    if loaded:
        return (pem_cert_bytes, pem_key_bytes)
    raise MyClientCertFailureException()

    channel = google.auth.transport.grpc.secure_authorized_channel(
        credentials, mtls_endpoint, request,
except MyClientCertFailureException:
    # handle the exception

Option 3: use application default SSL credentials. It searches and uses the command in a context aware metadata file, which is available on devices with endpoint verification support. See

    default_ssl_credentials = SslCredentials()
    # Exception can be raised if the context aware metadata is malformed.
    # See :class:`SslCredentials` for the possible exceptions.

# Choose the endpoint based on the SSL credentials type.
if default_ssl_credentials.is_mtls:
    endpoint_to_use = mtls_endpoint
    endpoint_to_use = regular_endpoint
channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, endpoint_to_use, request,

Option 4: not setting ssl_credentials and client_cert_callback. For devices without endpoint verification support, a regular TLS channel is created; otherwise, a mutual TLS channel is created, however, the call should be wrapped in a try/except block in case of malformed context aware metadata.

The following code uses regular_endpoint, it works the same no matter the created channle is regular or mutual TLS. Regular endpoint ignores client certificate and key:

channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, regular_endpoint, request)

The following code uses mtls_endpoint, if the created channle is regular, and API mtls_endpoint is confgured to require client SSL credentials, API calls using this channel will be rejected:

channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, mtls_endpoint, request)
  • credentials (google.auth.credentials.Credentials) – The credentials to add to requests.
  • request (google.auth.transport.Request) – A HTTP transport request object used to refresh credentials as needed. Even though gRPC is a separate transport, there’s no way to refresh the credentials without using a standard http transport.
  • target (str) – The host and port of the service.
  • ssl_credentials (grpc.ChannelCredentials) – Optional SSL channel credentials. This can be used to specify different certificates. This argument is mutually exclusive with client_cert_callback; providing both will raise an exception. If ssl_credentials and client_cert_callback are None, application default SSL credentials will be used.
  • client_cert_callback (Callable [ , bytes, bytes ]) – Optional callback function to obtain client certicate and key for mutual TLS connection. This argument is mutually exclusive with ssl_credentials; providing both will raise an exception. If ssl_credentials and client_cert_callback are None, application default SSL credentials will be used.
  • kwargs – Additional arguments to pass to grpc.secure_channel().

The created gRPC channel.

Return type:



google.auth.exceptions.MutualTLSChannelError – If mutual TLS channel creation failed for any reason.

class SslCredentials[source]

Bases: object

Class for application default SSL credentials.

For devices with endpoint verification support, a device certificate will be automatically loaded and mutual TLS will be established. See


Get the created SSL channel credentials.

For devices with endpoint verification support, if the device certificate loading has any problems, corresponding exceptions will be raised. For a device without endpoint verification support, no exceptions will be raised.

Returns:The created grpc channel credentials.
Return type:grpc.ChannelCredentials
Raises:google.auth.exceptions.MutualTLSChannelError – If mutual TLS channel creation failed for any reason.

Indicates if the created SSL channel credentials is mutual TLS.