Eseguire l'autenticazione con le librerie client

Questa pagina descrive come utilizzare le librerie client per accedere alle API di Google.

Le librerie client semplificano l'accesso alle Google Cloud API utilizzando un linguaggio supportato. Puoi utilizzare Google Cloud API direttamente effettuando delle richieste non elaborate al server, ma le librerie client forniscono semplificazioni che riducono notevolmente la quantità di codice da scrivere. Questo è particolarmente vero per l'autenticazione, perché le librerie client supportano le credenziali predefinite dell'applicazione (ADC).

Se accetti configurazioni delle credenziali (JSON, file o stream) da un origine esterna (ad esempio, un cliente), esamina i requisiti di sicurezza quando utilizzi le configurazioni delle credenziali da un'origine esterna.

Utilizzare le credenziali predefinite dell'applicazione con le librerie client

Per utilizzare le credenziali predefinite dell'applicazione per autenticare la tua applicazione, devi prima configurare ADC per l'ambiente in cui è in esecuzione l'applicazione. Quando utilizzi la libreria client per creare un client, la libreria client controlla e utilizza automaticamente le credenziali che hai fornito ad ADC per l'autenticazione alle API utilizzate dal tuo codice. La tua applicazione non deve autenticare esplicitamente o gestire i token; questi requisiti vengono gestiti automaticamente dalle librerie di autenticazione.

Per un ambiente di sviluppo locale, puoi configurare ADC con le credenziali utente o con account di servizio account utilizzando gcloud CLI. Per gli ambienti di produzione, configuri ADC collegando un service account.

Esempio di creazione di un client

I seguenti esempi di codice creano un client per il servizio Cloud Storage. È probabile che il tuo codice richieda client diversi; questi esempi hanno lo scopo di mostrare come creare un client e utilizzarlo senza alcun codice per l'autenticazione esplicita.

Prima di poter eseguire gli esempi seguenti, devi completare i seguenti passaggi:

Vai 

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.")

Ruby 

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

Utilizzare le chiavi API con le librerie client

Puoi utilizzare una chiave API solo con le librerie client per le API che accettano chiavi API. Inoltre, la chiave API non deve avere una limitazione API che ne impedisca l'utilizzo per l'API.

Per saperne di più sulle chiavi API create in modalità express, consulta le Domande frequenti sulla modalità express di Google Cloud.

Questo esempio utilizza l'API Cloud Natural Language, che accetta le chiavi API, per mostrare come fornire una chiave API alla libreria.

C#

Per eseguire questo esempio, devi installare la libreria client 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++

Per eseguire questo esempio, devi installare la libreria client 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";
}

Vai

Per eseguire questo esempio, devi installare la libreria client 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

Per eseguire questo esempio, devi installare la libreria client 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

Per eseguire questo esempio, devi installare la libreria client 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")

Ruby

Per eseguire questo esempio, devi installare la libreria client 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

Quando utilizzi le chiavi API nelle tue applicazioni, assicurati che siano protette durante l'archiviazione e la trasmissione. L'esposizione pubblica delle chiavi API può comportare addebiti imprevisti sul tuo account. Per saperne di più, consulta Best practice per la gestione delle chiavi API.

Requisiti di sicurezza quando si utilizzano configurazioni delle credenziali da un'origine esterna

In genere, le configurazioni delle credenziali vengono generate utilizzando i comandi gcloud CLI o la Google Cloud console. Ad esempio, puoi utilizzare gcloud CLI per generare un file ADC locale o un file di configurazione di accesso. Allo stesso modo, puoi utilizzare la Google Cloud console per creare e scaricare una chiave del account di servizio.

Tuttavia, per alcuni casi d'uso, le configurazioni delle credenziali vengono fornite da un'entità esterna; queste configurazioni delle credenziali sono destinate all'autenticazione alle API Google.

Alcuni tipi di configurazioni delle credenziali includono endpoint e percorsi di file, che le librerie di autenticazione utilizzano per acquisire un token. Quando accetti le configurazioni delle credenziali da un'origine esterna, devi convalidare la configurazione prima di utilizzarla. Se non convalidi la configurazione, un utente malintenzionato potrebbe utilizzare le credenziali per compromettere i tuoi sistemi e i tuoi dati.

Convalidare le configurazioni delle credenziali da origini esterne

La modalità di convalida delle credenziali esterne dipende dai tipi di credenziali accettate dalla tua applicazione.

Convalidare le chiavi dei account di servizio

Se la tua applicazione accetta solo le chiavi dei account di servizio, utilizza un caricatore di credenziali specifico per le chiavi dei account di servizio, come mostrato negli esempi seguenti. Il caricatore di credenziali specifico per il tipo analizza solo i campi presenti per le chiavi dei service account, che non espongono vulnerabilità.

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)

Ruby 

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

Se non puoi utilizzare un caricatore di credenziali specifico per il tipo, convalida le credenziali confermando che il valore del campo type sia service_account. Se il valore del campo type è un altro valore, non utilizzare la chiave del account di servizio.

Convalidare altre configurazioni delle credenziali

Se la tua applicazione accetta qualsiasi tipo di credenziale oltre a una chiave del account di servizio, devi eseguire una verifica aggiuntiva. Esempi di altri tipi di configurazioni delle credenziali includono file di credenziali ADC, file di credenziali della federazione delle identità per i carichi di lavoro, o file di configurazione di accesso della federazione delle identità per la forza lavoro.

La tabella seguente elenca i campi da convalidare, se presenti nelle credenziali. Non tutti questi campi sono presenti per tutte le configurazioni delle credenziali.

Campo Finalità Valore previsto
service_account_impersonation_url Le librerie di autenticazione utilizzano questo campo per accedere a un endpoint per generare un token di accesso per il account di servizio di cui viene simulata l'identità. https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken
token_url Le librerie di autenticazione inviano un token esterno a questo endpoint per scambiarlo con un token di accesso federato. https://sts.googleapis.com/v1/token
credential_source.file Le librerie di autenticazione leggono un token esterno dal file nella posizione specificata da questo campo e lo inviano all' token_url endpoint. Il percorso di un file contenente un token esterno. Dovresti riconoscere questo percorso.
credential_source.url Un endpoint che restituisce un token esterno. Le librerie di autenticazione inviano una richiesta a questo URL e inviano la risposta all' token_url endpoint.

Uno dei seguenti elementi:

  • Un endpoint noto fornito dal tuo cloud provider.
  • Un endpoint che hai configurato esplicitamente per fornire i token.
credential_source.executable.command Se la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES è impostata su 1, le librerie di autenticazione eseguono questo comando o file eseguibile. Un file eseguibile o un comando che restituisce un token esterno. Dovresti riconoscere questo comando e verificare che sia sicuro.
credential_source.aws.url Le librerie di autenticazione inviano una richiesta a questo URL per recuperare un token di sicurezza AWS.

Uno di questi valori esatti:

  • 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 Le librerie di autenticazione inviano una richiesta a questo URL per recuperare la regione AWS attiva.

Uno di questi valori esatti:

  • 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 Le librerie di autenticazione inviano una richiesta a questo URL per recuperare il token di sessione AWS.

Uno di questi valori esatti:

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

Passaggi successivi