Zur Verwendung von Clientbibliotheken authentifizieren

Auf dieser Seite wird beschrieben, wie Sie mit Clientbibliotheken auf Google APIs zugreifen können.

Clientbibliotheken erleichtern den Zugriff auf Google Cloud APIs mit einer unterstützten Sprache. Sie können Google Cloud APIs direkt verwenden, indem Sie Rohanfragen an den Server senden. Clientbibliotheken bieten jedoch Vereinfachungen, die den zu schreibenden Code erheblich reduzieren. Dies gilt insbesondere für die Authentifizierung, da die Clientbibliotheken Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) unterstützen.

Wenn Sie Anmeldedatenkonfigurationen (JSON, Dateien oder Streams) von einer externen Quelle (z. B. einem Kunden) akzeptieren, lesen Sie die Sicherheitsanforderungen bei der Verwendung von Anmeldedatenkonfigurationen aus einer externen Quelle.

Standardanmeldedaten für Anwendungen mit Clientbibliotheken verwenden

Wenn Sie Ihre Anwendung mit den Standardanmeldedaten für Anwendungen authentifizieren möchten, müssen Sie zuerst Standardanmeldedaten für Anwendungen für die Umgebung einrichten, in der Ihre Anwendung ausgeführt wird. Wenn Sie die Clientbibliothek zum Erstellen eines Clients verwenden, prüft die Clientbibliothek automatisch die Anmeldedaten, die Sie für ADC bereitgestellt haben, und verwendet sie, um die von Ihrem Code verwendeten APIs zu authentifizieren. Ihre Anwendung muss Tokens nicht explizit authentifizieren oder verwalten. Diese Anforderungen werden automatisch von den Authentifizierungsbibliotheken verwaltet.

Für eine lokale Entwicklungsumgebung können Sie ADC mit Ihren Nutzeranmeldedaten oder mit der Identitätsübernahme des Dienstkontos einrichten. Verwenden Sie dazu die gcloud CLI. In Produktionsumgebungen richten Sie ADC ein, indem Sie ein Dienstkonto anhängen.

Beispiel für die Clienterstellung

In den folgenden Codebeispielen wird ein Client für den Cloud Storage-Dienst erstellt. Ihr Code benötigt wahrscheinlich andere Clients. Diese Beispiele sollen nur zeigen, wie Sie einen Client erstellen und ihn ohne Code zur expliziten Authentifizierung verwenden können.

Bevor Sie die folgenden Samples ausführen können, müssen Sie die folgenden Schritte ausführen:

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

API-Schlüssel mit Clientbibliotheken verwenden

API-Schlüssel können nur mit Clientbibliotheken für APIs verwendet werden, die API-Schlüssel akzeptieren. Außerdem darf für den API-Schlüssel keine API-Einschränkung gelten, die seine Verwendung für die API verhindert.

Weitere Informationen zu API-Schlüsseln, die im Expressmodus erstellt wurden, finden Sie in den häufig gestellten Fragen zum Google Cloud Expressmodus.

In diesem Beispiel wird die Cloud Natural Language API verwendet, die API-Schlüssel akzeptiert, um zu zeigen, wie Sie einen API-Schlüssel für die Bibliothek bereitstellen.

C#

Sie müssen die Natural Language-Clientbibliothek installieren, um dieses Beispiel auszuführen.


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++

Sie müssen die Natural Language-Clientbibliothek installieren, um dieses Beispiel auszuführen.

#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

Sie müssen die Natural Language-Clientbibliothek installieren, um dieses Beispiel auszuführen.

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

Sie müssen die Natural Language-Clientbibliothek installieren, um dieses Beispiel auszuführen.


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

Sie müssen die Natural Language-Clientbibliothek installieren, um dieses Beispiel auszuführen.


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

Wenn Sie API-Schlüssel in Ihren Anwendungen verwenden, achten Sie darauf, dass sie sowohl beim Speichern als auch bei der Übertragung sicher sind. Wenn Sie Ihre API-Schlüssel öffentlich freigeben, kann dies zu unerwarteten Kosten in Ihrem Konto führen. Weitere Informationen finden Sie unter Best Practices für die Verwaltung von API-Schlüsseln.

Sicherheitsanforderungen bei der Verwendung von Anmeldedatenkonfigurationen aus einer externen Quelle

Normalerweise generieren Sie Anmeldedatenkonfigurationen mithilfe von gcloud-Befehlen oder der Google Cloud Console. Sie können beispielsweise die gcloud CLI verwenden, um eine lokale ADC-Datei oder eine Anmeldekonfigurationsdatei zu generieren. Ebenso können Sie über die Google Cloud Console einen Dienstkontoschlüssel erstellen und herunterladen.

Bei einigen Anwendungsfällen werden Anmeldedatenkonfigurationen jedoch von einer externen Entität bereitgestellt. Diese Anmeldedatenkonfigurationen sind für die Authentifizierung bei Google APIs vorgesehen.

Einige Arten von Anmeldedatenkonfigurationen umfassen Endpunkte und Dateipfade, die von den Authentifizierungsbibliotheken zum Abrufen eines Tokens verwendet werden. Wenn Sie Anmeldedatenkonfigurationen von einer externen Quelle akzeptieren, müssen Sie die Konfiguration vor der Verwendung validieren. Wenn Sie die Konfiguration nicht validieren, kann ein böswilliger Akteur die Anmeldedaten verwenden, um Ihre Systeme und Daten zu schädigen.

Anmeldedatenkonfigurationen aus externen Quellen validieren

Wie Sie Ihre externen Anmeldedaten validieren müssen, hängt davon ab, welche Arten von Anmeldedaten Ihre Anwendung akzeptiert.

Dienstkontoschlüssel validieren

Wenn Ihre Anwendung nur Dienstkontoschlüssel akzeptiert, verwenden Sie einen Anmeldedaten-Ladeprogramm, das speziell für Dienstkontoschlüssel vorgesehen ist, wie in den folgenden Beispielen gezeigt. Der typspezifische Anmeldedaten-Ladeprogramm analysiert nur die Felder für Dienstkontoschlüssel, die keine Sicherheitslücken aufweisen.

C#

var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);

C++ 

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

Java 

ServiceAccountCredentials credentials =
      ServiceAccountCredentials.fromJson(json, new HttpTransportFactory());

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)

Wenn Sie keinen typspezifischen Anmeldedaten-Ladeprogramm verwenden können, prüfen Sie die Anmeldedaten, indem Sie bestätigen, dass der Wert für das Feld type service_account ist. Wenn der Wert für das Feld type ein anderer Wert ist, verwenden Sie den Dienstkontoschlüssel nicht.

Andere Anmeldedatenkonfigurationen validieren

Wenn Ihre Anwendung neben einem Dienstkontoschlüssel jegliche Art von Anmeldedaten akzeptiert, müssen Sie eine zusätzliche Überprüfung durchführen. Beispiele für andere Arten von Anmeldedatenkonfigurationen sind ADC-Anmeldedatendateien, Anmeldedatendateien für die Workload Identity-Föderation oder Anmeldekonfigurationsdateien für die Workforce Identity-Föderation.

In der folgenden Tabelle sind die Felder aufgeführt, die Sie validieren müssen, sofern sie in Ihren Anmeldedaten vorhanden sind. Nicht alle diese Felder sind für alle Anmeldedatenkonfigurationen vorhanden.

Feld Zweck Erwarteter Wert
service_account_impersonation_url Die Authentifizierungsbibliotheken verwenden dieses Feld, um auf einen Endpunkt zuzugreifen und ein Zugriffstoken für das Dienstkonto zu generieren, dessen Identität übernommen wird. https://iamcredentials.googleapis.com.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken
token_url Die Authentifizierungsbibliotheken senden ein externes Token an diesen Endpunkt, um es gegen ein föderiertes Zugriffstoken auszutauschen. https://sts.googleapis.com.com/v1/token
credential_source.file Die Authentifizierungsbibliotheken lesen ein externes Token aus der Datei am durch dieses Feld angegebenen Speicherort und senden es an den token_url-Endpunkt. Der Pfad zu einer Datei mit einem externen Token. Dieser Pfad sollte Ihnen bekannt sein.
credential_source.url Ein Endpunkt, der ein externes Token zurückgibt. Die Authentifizierungsbibliotheken senden eine Anfrage an diese URL und die Antwort an den Endpunkt token_url.

Eine der folgenden Optionen:

  • Ein bekannter Endpunkt, der von Ihrem Cloud-Anbieter bereitgestellt wird.
  • Ein Endpunkt, den Sie explizit zum Bereitstellen von Tokens eingerichtet haben.
credential_source.executable.command Wenn die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1 festgelegt ist, führen die Authentifizierungsbibliotheken diesen Befehl oder diese ausführbare Datei aus. Eine ausführbare Datei oder ein Befehl, der ein externes Token zurückgibt. Sie sollten diesen Befehl kennen und prüfen, ob er sicher ist.
credential_source.aws.url Die Authentifizierungsbibliotheken senden eine Anfrage an diese URL, um ein AWS-Sicherheitstoken abzurufen.

Einer der folgenden genauen Werte:

  • 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 Die Authentifizierungsbibliotheken senden eine Anfrage an diese URL, um die aktive AWS-Region abzurufen.

Einer der folgenden genauen Werte:

  • 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 Die Authentifizierungsbibliotheken senden eine Anfrage an diese URL, um das AWS-Sitzungstoken abzurufen.

Einer der folgenden genauen Werte:

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

Nächste Schritte