google.auth.transport.grpc module

Authorization support for gRPC.

class AuthMetadataPlugin(credentials, request)

Bases: grpc.AuthMetadataPlugin

A gRPC AuthMetadataPlugin that inserts the credentials into each request.

Parameters

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

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

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.

Example:

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
from google.cloud.speech.v1 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,
    ssl_credentials=grpc.ssl_channel_credentials())

# Use the channel to create a stub.
cloud_speech.create_Speech_stub(channel)

Usage:

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 = 'speech.googleapis.com:443'
mtls_endpoint = 'speech.mtls.googleapis.com:443'

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,
    ssl_credentials=regular_ssl_credentials)

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():
    code_to_load_client_cert_and_key()
    if loaded:
        return (pem_cert_bytes, pem_key_bytes)
    raise MyClientCertFailureException()

try:
    channel = google.auth.transport.grpc.secure_authorized_channel(
        credentials, mtls_endpoint, request,
        client_cert_callback=my_client_cert_callback)
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 https://cloud.google.com/endpoint-verification/docs/overview:

try:
    default_ssl_credentials = SslCredentials()
except:
    # 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
else:
    endpoint_to_use = regular_endpoint
channel = google.auth.transport.grpc.secure_authorized_channel(
    credentials, endpoint_to_use, request,
    ssl_credentials=default_ssl_credentials)

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)

Parameters

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

Returns

The created gRPC channel.

Return type

grpc.Channel

Raises

• OSError – If the cert provider command launch fails during the application default SSL credentials loading process on devices with endpoint verification support.

• RuntimeError – If the cert provider command has a runtime error during the application default SSL credentials loading process on devices with endpoint verification support.

• ValueError – If the context aware metadata file is malformed or if the cert provider command doesn’t produce both client certificate and key during the application default SSL credentials loading process on devices with endpoint verification support.

class SslCredentials

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 https://cloud.google.com/endpoint-verification/docs/overview.

property ssl_credentials

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

• OSError – If the cert provider command launch fails.

• RuntimeError – If the cert provider command has a runtime error.

• ValueError – If the context aware metadata file is malformed or if the cert provider command doesn’t produce both the client certificate and key.

property is_mtls

Indicates if the created SSL channel credentials is mutual TLS.