Autenticación con bibliotecas cliente

En esta página, se describe cómo puedes usar las bibliotecas cliente para acceder a las APIs de Google.

Las bibliotecas cliente facilitan el acceso a Google Cloud APIs mediante un lenguaje compatible. Puedes usar las APIs directamente con solicitudes sin procesar al servidor, pero las bibliotecas cliente proporcionan simplificaciones que reducen de manera significativa la cantidad de código que debes escribir. Google Cloud Esto se aplica en particular a la autenticación, ya que las bibliotecas cliente son compatibles con las credenciales predeterminadas de la aplicación (ADC).

Si aceptas configuraciones de credenciales (JSON, archivos o transmisiones) de una fuente externa (por ejemplo, un cliente), revisa los requisitos de seguridad cuando uses configuraciones de credenciales de una fuente externa.

Usa las credenciales predeterminadas de la aplicación con bibliotecas cliente

Para usar las credenciales predeterminadas de la aplicación a fin de autenticar tu aplicación, primero debes configurar las ADC para el entorno en el que se ejecuta tu aplicación. Cuando usas la biblioteca cliente para crear un cliente, esta busca y usa de forma automática las credenciales que proporcionaste a ADC para autenticarte en las APIs que usa tu código. Tu aplicación no necesita autenticar ni administrar tokens de forma explícita. Las bibliotecas de autenticación administran estos requisitos de forma automática.

Para un entorno de desarrollo local, puedes configurar ADC con tus credenciales de usuario o con identidad temporal como cuenta de servicio mediante gcloud CLI. Para los entornos de producción, debes configurar las ADC mediante la conexión de una cuenta de servicio.

Ejemplo de creación de cliente

Las siguientes muestras de código crean un cliente para el servicio de Cloud Storage. Es probable que tu código necesite diferentes clientes. El propósito de estos ejemplos es solo mostrar cómo puedes crear un cliente y usarlo sin ningún código para autenticarte de forma explícita.

Antes de ejecutar las siguientes muestras, debes completar los siguientes pasos:

Go 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// authenticateImplicitWithAdc uses Application Default Credentials
// to automatically find credentials and authenticate.
func authenticateImplicitWithAdc(w io.Writer, projectId string) error {
	// projectId := "your_project_id"

	ctx := context.Background()

	// NOTE: Replace the client created below with the client required for your application.
	// Note that the credentials are not specified when constructing the client.
	// The client library finds your credentials using ADC.
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	it := client.Buckets(ctx, projectId)
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Bucket: %v\n", bucketAttrs.Name)
	}

	fmt.Fprintf(w, "Listed all storage buckets.\n")

	return nil
}

Java 


import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;

public class AuthenticateImplicitWithAdc {

  public static void main(String[] args) throws IOException {
    // TODO(Developer):
    //  1. Before running this sample,
    //  set up Application Default Credentials as described in
    //  https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable below.
    //  3. Make sure you have the necessary permission to list storage buckets
    //  "storage.buckets.list"
    String projectId = "your-google-cloud-project-id";
    authenticateImplicitWithAdc(projectId);
  }

  // When interacting with Google Cloud Client libraries, the library can auto-detect the
  // credentials to use.
  public static void authenticateImplicitWithAdc(String project) throws IOException {

    // *NOTE*: Replace the client created below with the client required for your application.
    // Note that the credentials are not specified when constructing the client.
    // Hence, the client library will look for credentials using ADC.
    //
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    Storage storage = StorageOptions.newBuilder().setProjectId(project).build().getService();

    System.out.println("Buckets:");
    Page<Bucket> buckets = storage.list();
    for (Bucket bucket : buckets.iterateAll()) {
      System.out.println(bucket.toString());
    }
    System.out.println("Listed all storage buckets.");
  }
}

Node.js 

/**
 * TODO(developer):
 *  1. Uncomment and replace these variables before running the sample.
 *  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
 *  3. Make sure you have the necessary permission to list storage buckets "storage.buckets.list"
 *    (https://cloud.google.com/storage/docs/access-control/iam-permissions#bucket_permissions)
 */
// const projectId = 'YOUR_PROJECT_ID';

const {Storage} = require('@google-cloud/storage');

async function authenticateImplicitWithAdc() {
  // This snippet demonstrates how to list buckets.
  // NOTE: Replace the client created below with the client required for your application.
  // Note that the credentials are not specified when constructing the client.
  // The client library finds your credentials using ADC.
  const storage = new Storage({
    projectId,
  });
  const [buckets] = await storage.getBuckets();
  console.log('Buckets:');

  for (const bucket of buckets) {
    console.log(`- ${bucket.name}`);
  }

  console.log('Listed all storage buckets.');
}

authenticateImplicitWithAdc();

PHP 

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

/**
 * Authenticate to a cloud client library using a service account implicitly.
 *
 * @param string $projectId The Google project ID.
 */
function auth_cloud_implicit($projectId)
{
    $config = [
        'projectId' => $projectId,
    ];

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python 


from google.cloud import storage


def authenticate_implicit_with_adc(project_id: str = "your-google-cloud-project-id") -> None:
    """
    When interacting with Google Cloud Client libraries, the library can auto-detect the
    credentials to use.

    // TODO(Developer):
    //  1. Before running this sample,
    //  set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable.
    //  3. Make sure that the user account or service account that you are using
    //  has the required permissions. For this sample, you must have "storage.buckets.list".
    Args:
        project_id: The project id of your Google Cloud project.
    """

    # This snippet demonstrates how to list buckets.
    # *NOTE*: Replace the client created below with the client required for your application.
    # Note that the credentials are not specified when constructing the client.
    # Hence, the client library will look for credentials using ADC.
    storage_client = storage.Client(project=project_id)
    buckets = storage_client.list_buckets()
    print("Buckets:")
    for bucket in buckets:
        print(bucket.name)
    print("Listed all storage buckets.")

Rita 

def authenticate_implicit_with_adc project_id:
  # The ID of your Google Cloud project
  # project_id = "your-google-cloud-project-id"

  ###
  # When interacting with Google Cloud Client libraries, the library can auto-detect the
  # credentials to use.
  # TODO(Developer):
  #   1. Before running this sample,
  #      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
  #   2. Replace the project variable.
  #   3. Make sure that the user account or service account that you are using
  #      has the required permissions. For this sample, you must have "storage.buckets.list".
  ###

  require "google/cloud/storage"

  # This sample demonstrates how to list buckets.
  # *NOTE*: Replace the client created below with the client required for your application.
  # Note that the credentials are not specified when constructing the client.
  # Hence, the client library will look for credentials using ADC.
  storage = Google::Cloud::Storage.new project_id: project_id
  buckets = storage.buckets
  puts "Buckets: "
  buckets.each do |bucket|
    puts bucket.name
  end
  puts "Plaintext: Listed all storage buckets."
end

Usa claves de API con bibliotecas cliente

Solo puedes usar claves de API con bibliotecas cliente para APIs que acepten claves de API. Además, la clave de API no debe tener una restricción de API que impida que se use para la API.

Para obtener más información sobre las claves de API creadas en el modo Exprés, consulta las Preguntas frecuentes sobre el modo Exprés de Google Cloud.

En este ejemplo, se usa la API de Cloud Natural Language, que acepta claves de API, para demostrar cómo se proporciona una clave de API a la biblioteca.

C#

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.


using Google.Cloud.Language.V1;
using System;

public class UseApiKeySample
{
    public void AnalyzeSentiment(string apiKey)
    {
        LanguageServiceClient client = new LanguageServiceClientBuilder
        {
            ApiKey = apiKey
        }.Build();

        string text = "Hello, world!";

        AnalyzeSentimentResponse response = client.AnalyzeSentiment(Document.FromPlainText(text));
        Console.WriteLine($"Text: {text}");
        Sentiment sentiment = response.DocumentSentiment;
        Console.WriteLine($"Sentiment: {sentiment.Score}, {sentiment.Magnitude}");
        Console.WriteLine("Successfully authenticated using the API key");
    }
}

C++

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.

#include "google/cloud/language/v1/language_client.h"
#include "google/cloud/credentials.h"
#include "google/cloud/options.h"

void AuthenticateWithApiKey(std::vector<std::string> const& argv) {
  if (argv.size() != 2) {
    throw google::cloud::testing_util::Usage{
        "authenticate-with-api-key <project-id> <api-key>"};
  }
  namespace gc = ::google::cloud;
  auto options = gc::Options{}.set<gc::UnifiedCredentialsOption>(
      gc::MakeApiKeyCredentials(argv[1]));
  auto client = gc::language_v1::LanguageServiceClient(
      gc::language_v1::MakeLanguageServiceConnection(options));

  auto constexpr kText = "Hello, world!";

  google::cloud::language::v1::Document d;
  d.set_content(kText);
  d.set_type(google::cloud::language::v1::Document::PLAIN_TEXT);

  auto response = client.AnalyzeSentiment(d, {});
  if (!response) throw std::move(response.status());
  auto const& sentiment = response->document_sentiment();
  std::cout << "Text: " << kText << "\n";
  std::cout << "Sentiment: " << sentiment.score() << ", "
            << sentiment.magnitude() << "\n";
  std::cout << "Successfully authenticated using the API key\n";
}

Go

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.

import (
	"context"
	"fmt"
	"io"

	language "cloud.google.com/go/language/apiv1"
	"cloud.google.com/go/language/apiv1/languagepb"
	"google.golang.org/api/option"
)

// authenticateWithAPIKey authenticates with an API key for Google Language
// service.
func authenticateWithAPIKey(w io.Writer, apiKey string) error {
	// apiKey := "api-key-string"

	ctx := context.Background()

	// Initialize the Language Service client and set the API key.
	client, err := language.NewClient(ctx, option.WithAPIKey(apiKey))
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	text := "Hello, world!"
	// Make a request to analyze the sentiment of the text.
	res, err := client.AnalyzeSentiment(ctx, &languagepb.AnalyzeSentimentRequest{
		Document: &languagepb.Document{
			Source: &languagepb.Document_Content{
				Content: text,
			},
			Type: languagepb.Document_PLAIN_TEXT,
		},
	})
	if err != nil {
		return fmt.Errorf("AnalyzeSentiment: %w", err)
	}

	fmt.Fprintf(w, "Text: %s\n", text)
	fmt.Fprintf(w, "Sentiment score: %v\n", res.DocumentSentiment.Score)
	fmt.Fprintln(w, "Successfully authenticated using the API key.")

	return nil
}

Node.js

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.


const {
  v1: {LanguageServiceClient},
} = require('@google-cloud/language');

/**
 * Authenticates with an API key for Google Language service.
 *
 * @param {string} apiKey An API Key to use
 */
async function authenticateWithAPIKey(apiKey) {
  const language = new LanguageServiceClient({apiKey});

  // Alternatively:
  // const {GoogleAuth} = require('google-auth-library');
  // const auth = new GoogleAuth({apiKey});
  // const language = new LanguageServiceClient({auth});

  const text = 'Hello, world!';

  const [response] = await language.analyzeSentiment({
    document: {
      content: text,
      type: 'PLAIN_TEXT',
    },
  });

  console.log(`Text: ${text}`);
  console.log(
    `Sentiment: ${response.documentSentiment.score}, ${response.documentSentiment.magnitude}`,
  );
  console.log('Successfully authenticated using the API key');
}

authenticateWithAPIKey();

Python

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.


from google.cloud import language_v1


def authenticate_with_api_key(api_key_string: str) -> None:
    """
    Authenticates with an API key for Google Language service.

    TODO(Developer): Replace this variable before running the sample.

    Args:
        api_key_string: The API key to authenticate to the service.
    """

    # Initialize the Language Service client and set the API key
    client = language_v1.LanguageServiceClient(
        client_options={"api_key": api_key_string}
    )

    text = "Hello, world!"
    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )

    # Make a request to analyze the sentiment of the text.
    sentiment = client.analyze_sentiment(
        request={"document": document}
    ).document_sentiment

    print(f"Text: {text}")
    print(f"Sentiment: {sentiment.score}, {sentiment.magnitude}")
    print("Successfully authenticated using the API key")

Rita

Para ejecutar esta muestra, debes instalar la biblioteca cliente de Natural Language.

require "googleauth"
require "google/cloud/language/v1"

def authenticate_with_api_key api_key_string
  # Authenticates with an API key for Google Language service.
  #
  # TODO(Developer): Uncomment the following line and set the value before running this sample.
  #
  # api_key_string = "mykey12345"
  #
  # Note: You can also set the API key via environment variable:
  #   export GOOGLE_API_KEY=your-api-key
  # and use Google::Auth::APIKeyCredentials.from_env method to load it.
  # Example:
  #   credentials = Google::Auth::APIKeyCredentials.from_env
  #   if credentials.nil?
  #     puts "No API key found in environment"
  #     exit
  #   end

  # Initialize API key credentials using the class factory method
  credentials = Google::Auth::APIKeyCredentials.make_creds api_key: api_key_string

  # Initialize the Language Service client with the API key credentials
  client = Google::Cloud::Language::V1::LanguageService::Client.new do |config|
    config.credentials = credentials
  end

  # Create a document to analyze
  text = "Hello, world!"
  document = {
    content: text,
    type: :PLAIN_TEXT
  }

  # Make a request to analyze the sentiment of the text
  sentiment = client.analyze_sentiment(document: document).document_sentiment

  puts "Text: #{text}"
  puts "Sentiment: #{sentiment.score}, #{sentiment.magnitude}"
  puts "Successfully authenticated using the API key"
end

Cuando uses claves de API en tus aplicaciones, asegúrate de que se mantengan seguras durante el almacenamiento y la transmisión. Si expones tus claves de API de forma pública, puedes generar cargos inesperados en tu cuenta. Para obtener más información, consulta Prácticas recomendadas para administrar las claves de API.

Requisitos de seguridad cuando se usan configuraciones de credenciales de una fuente externa

Por lo general, generas configuraciones de credenciales con comandos de gcloud CLI o con la Google Cloud consola. Por ejemplo, puedes usar gcloud CLI para generar un archivo ADC local o un archivo de configuración de acceso. Del mismo modo, puedes usar la Google Cloud consola para crear y descargar una clave de cuenta de servicio.

Sin embargo, para algunos casos de uso, una entidad externa te proporciona las configuraciones de credenciales. Estas configuraciones de credenciales están diseñadas para usarse para autenticarse en las APIs de Google.

Algunos tipos de configuraciones de credenciales incluyen extremos y rutas de acceso de archivos, que las bibliotecas de autenticación usan para adquirir un token. Cuando aceptas configuraciones de credenciales de una fuente externa, debes validar la configuración antes de usarla. Si no validas la configuración, un agente malicioso podría usar la credencial para poner en riesgo tus sistemas y datos.

Valida las configuraciones de credenciales de fuentes externas

La forma en que debes validar tus credenciales externas depende de los tipos de credenciales que acepta tu aplicación.

Valida las claves de cuenta de servicio

Si tu aplicación acepta solo claves de cuenta de servicio, usa un cargador de credenciales específico para las claves de cuenta de servicio, como se muestra en los siguientes ejemplos. El cargador de credenciales específico para el tipo analiza solo los campos presentes para las claves de cuenta de servicio, que no exponen ninguna vulnerabilidad.

C# 

var saCredential = CredentialFactory.FromStream<ServiceAccountCredential>(stream);

C++ 

auto cred = google::cloud::MakeServiceAccountCredentials(json)

Java 

ServiceAccountCredentials credentials =
      ServiceAccountCredentials.fromStream(credentialsStream);

Node.js 

const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);

PHP 

$cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);

Python 

cred = service_account.Credentials.from_service_account_info(json_data)

Rita 

creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)

Si no puedes usar un cargador de credenciales específico para el tipo, valida la credencial. Para ello, confirma que el valor del campo type sea service_account. Si el valor del campo type es cualquier otro valor, no uses la clave de cuenta de servicio.

Valida otras configuraciones de credenciales

Si tu aplicación acepta cualquier tipo de credencial además de una clave de cuenta de servicio, debes realizar una verificación adicional. Algunos ejemplos de otros tipos de configuraciones de credenciales incluyen archivos de credenciales de ADC, archivos de credenciales de federación de identidades para cargas de trabajo, o archivos de configuración de acceso de federación de identidades de personal.

En la siguiente tabla, se enumeran los campos que debes validar si están presentes en tus credenciales. No todos estos campos están presentes para todas las configuraciones de credenciales.

Campo Objetivo Valor esperado
service_account_impersonation_url Las bibliotecas de autenticación usan este campo para acceder a un extremo y generar un token de acceso para la cuenta de servicio que se suplanta. https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken
token_url Las bibliotecas de autenticación envían un token externo a este extremo para intercambiarlo por un token de acceso federado. https://sts.googleapis.com/v1/token
credential_source.file Las bibliotecas de autenticación leen un token externo del archivo en la ubicación especificada por este campo y lo envían al token_url extremo. Es la ruta de acceso de un archivo que contiene un token externo. Debes reconocer esta ruta de acceso.
credential_source.url Es un extremo que muestra un token externo. Las bibliotecas de autenticación envían una solicitud a esta URL y envían la respuesta al token_url extremo.

Uno de los siguientes elementos:

  • Un extremo conocido que proporciona tu proveedor de servicios en la nube
  • Un extremo que configuraste de forma explícita para proporcionar tokens
credential_source.executable.command Si la variable de entorno GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES se establece en 1, las bibliotecas de autenticación ejecutan este comando o archivo ejecutable. Un archivo ejecutable o un comando que muestra un token externo. Debes reconocer este comando y validar que sea seguro.
credential_source.aws.url Las bibliotecas de autenticación emiten una solicitud a esta URL para recuperar un token de seguridad de AWS.

Cualquiera de estos valores exactos:

  • http://169.254.169.254/latest/meta-data/iam/security-credentials
  • http://[fd00:ec2::254]/latest/meta-data/iam/security-credentials
credential_source.aws.region_url Las bibliotecas de autenticación emiten una solicitud a esta URL para recuperar la región activa de AWS.

Cualquiera de estos valores exactos:

  • http://169.254.169.254/latest/meta-data/placement/availability-zone
  • http://[fd00:ec2::254]/latest/meta-data/placement/availability-zone
credential_source.aws.imdsv2_session_token_url Las bibliotecas de autenticación emiten una solicitud a esta URL para recuperar el token de sesión de AWS.

Cualquiera de estos valores exactos:

  • http://169.254.169.254/latest/api/token
  • http://[fd00:ec2::254]/latest/api/token

¿Qué sigue?