Authentifizierung mit Clientbibliotheken

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 Roh-Anfragen 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 für die Verwendung von Anmeldedatenkonfigurationen aus externen Quellen.

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 Beispiele 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: 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

API-Schlüssel mit Clientbibliotheken verwenden

Sie können API-Schlüssel nur mit Clientbibliotheken für APIs verwenden, die API-Schlüssel akzeptieren. Außerdem darf der API-Schlüssel keine API-Einschränkung haben, die seine Verwendung für die API verhindert.

Weitere Informationen zu API-Schlüsseln, die im Expressmodus erstellt wurden, finden Sie in den FAQs 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")

Ruby

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

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

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 für die Verwendung von Anmeldedatenkonfigurationen aus externen Quellen

In der Regel generieren Sie Anmeldedatenkonfigurationen mit gcloud CLI Befehlen oder über die Google Cloud Console. Mit der gcloud CLI können Sie beispielsweise eine lokale ADC-Datei oder eine Anmeldekonfigurationsdatei generieren. Ebenso können Sie über die Google Cloud Console einen Dienstkontoschlüssel erstellen und herunterladen.

In einigen Anwendungsfällen werden Ihnen jedoch Anmeldedatenkonfigurationen von einer externen Entität zur Verfügung gestellt. Diese Anmeldedatenkonfigurationen sollen zur Authentifizierung bei Google APIs verwendet werden.

Einige Arten von Anmeldedatenkonfigurationen enthalten 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 validieren, bevor Sie sie verwenden. Wenn Sie die Konfiguration nicht validieren, kann ein böswilliger Akteur die Anmeldedaten verwenden, um Ihre Systeme und Daten zu kompromittieren.

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-Loader, der speziell für Dienstkontoschlüssel entwickelt wurde, wie in den folgenden Beispielen gezeigt. Der typspezifische Anmeldedaten-Loader parst nur die Felder, die für Dienstkontoschlüssel vorhanden sind, und deckt keine Sicherheitslücken auf.

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)

Wenn Sie keinen typspezifischen Anmeldedaten-Loader verwenden können, validieren 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 jede Art von Anmeldedaten außer einem Dienstkontoschlüssel 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 Mitarbeiteridentitätsföderation.

In der folgenden Tabelle sind die Felder aufgeführt, die Sie validieren müssen, wenn 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, um ein Zugriffstoken für das Dienstkonto zu generieren, dessen Identität übernommen wird. https://iamcredentials.googleapis.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/v1/token
credential_source.file Die Authentifizierungsbibliotheken lesen ein externes Token aus der Datei am Speicherort, der durch dieses Feld angegeben wird, und senden es an den token_url Endpunkt. Der Pfad zu einer Datei, die ein externes Token enthält. Sie sollten diesen Pfad kennen.
credential_source.url Ein Endpunkt, der ein externes Token zurückgibt. Die Authentifizierungsbibliotheken senden eine Anfrage an diese URL und senden die Antwort an den token_url Endpunkt.

Einer der folgenden Werte:

  • Ein bekannter Endpunkt, der von Ihrem Cloud-Anbieter bereitgestellt wird.
  • Ein Endpunkt, den Sie explizit für die Bereitstellung von Tokens eingerichtet haben.
credential_source.executable.command Wenn die GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES Umgebungsvariable auf 1 gesetzt ist, führen die Authentifizierungs Bibliotheken 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