Erste Schritte mit der Google-Authentifizierungsbibliothek

Die Google Auth Library ist eine Open-Source-Authentifizierungs-Clientbibliothek für Java. In diesem Dokument wird beschrieben, wie Sie diese Bibliothek verwenden, um Ihre Java-Anwendungen für den Zugriff auf Google Cloud -Dienste zu authentifizieren.

In diesem Leitfaden erfahren Sie, wie Sie:

Fügen Sie Ihrem Projekt mit Maven, Gradle oder Simple Build Tool (SBT) die erforderlichen Abhängigkeiten der Auth-Bibliothek hinzu.
Authentifizierung mit verschiedenen Methoden, wobei der Schwerpunkt auf Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) liegt.
Konfigurieren Sie erweiterte Authentifizierungsszenarien, einschließlich der Identitätsföderation von Arbeitslasten, der Mitarbeiteridentitätsföderation und der Identitätsübernahme von Dienstkonten.
Eingeschränkte Tokens generieren und verwenden, um Berechtigungen einzuschränken
Anmeldedaten in Google HTTP-Clientbibliotheken einbinden

Diese Dokumentation richtet sich an Java-Entwickler. Vollständige API-Details finden Sie in der Google Auth Library API-Dokumentation.

Die Google-Authentifizierungsbibliothek für Java besteht aus vier Artefakten:

google-auth-library-credentials enthält Basisklassen und ‑schnittstellen für Google-Anmeldedaten.
google-auth-library-appengine enthält App Engine-Anmeldedaten und ist vom App Engine SDK abhängig.
google-auth-library-oauth2-http enthält eine Vielzahl von Anmeldedaten und Dienstprogrammmethoden, einschließlich Funktionen zum Abrufen von Application Default Credentials. Außerdem wird der serverseitige Ansatz zum Generieren von Tokens mit eingeschränkten Berechtigungen beschrieben.
google-auth-library-cab-token-generator bietet den clientseitigen Ansatz zum Generieren von herabgestuften Tokens.

Anmeldedatenkonfigurationen validieren

Wenn Sie Anmeldedatenkonfigurationen wie JSON, Dateipfade oder Streams aus einer externen Quelle verwenden, müssen Sie sie validieren. Wenn Sie Google-APIs oder Clientbibliotheken nicht validierte Anmeldedaten für die Authentifizierung beiGoogle Cloud zur Verfügung stellen, kann dies die Sicherheit Ihrer Systeme und Daten beeinträchtigen.

Weitere Informationen finden Sie unter Extern bezogene Anmeldedaten. Standardanmeldedaten.

Auth-Bibliothek importieren

Wenn Sie die Auth Library importieren möchten, verwenden Sie com.google.cloud:libraries-bom oder die Google Auth Library Bill of Materials mit Maven oder Gradle.

Java SDK-Bibliotheken-BOM

Wenn Sie sich mit der Auth Library in einer Clientbibliothek im Java SDK (z. B. google-cloud-datastore) authentifizieren möchten, verwenden Sie libraries-bom. Dadurch werden die mit dieser Clientbibliothek kompatiblen Versionen der Auth Library abgerufen.

So importieren Sie beispielsweise die Auth Library mit Maven über eine pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Wenn Sie libraries-bom oder andere Clientbibliotheken nicht verwenden, importieren Sie die Auth-Module direkt mit der Google Auth Library Bill of Materials.

Google Auth Library-Stückliste

Sie können die Stückliste der Google-Authentifizierungsbibliothek verwenden, um sicherzustellen, dass die Auth-Module und die relevanten transitiven Abhängigkeiten kompatibel sind.

Maven

Fügen Sie der Datei pom.xml Folgendes hinzu:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Im Abschnitt <dependencies> können Sie alle erforderlichen Auth-Module angeben. Wenn Sie beispielsweise das Modul google-auth-library-oauth2-http einfügen möchten, fügen Sie das folgende <dependency>-Element hinzu:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

Ersetzen Sie google-auth-library-oauth2-http im Beispiel durch google-auth-library-credentials oder google-auth-library-appengine, je nach den Anforderungen Ihrer Anwendung.

Gradle

Ähnlich wie bei Maven können Gradle-Nutzer mit google-auth-library-bom Abhängigkeitsversionen verwalten und die Kompatibilität zwischen den verschiedenen google-auth-library-Modulen sicherstellen.

Wenn Sie die BOM mit Gradle verwenden möchten, fügen Sie sie als platform-Abhängigkeit hinzu. Fügen Sie dann die google-auth-library-Module hinzu, die Sie benötigen. Die Stückliste sorgt dafür, dass die Versionen aller verwendeten Module kompatibel sind. Fügen Sie Ihrer build.gradle-Datei beispielsweise Folgendes hinzu:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

Anders als Maven und Gradle unterstützt SBT (Scala Build Tool) keine Maven Bills of Materials (BOMs). Wenn Sie Scala verwenden, können Sie google-auth-library-bom daher nicht importieren, um kompatible Versionen der Auth Library-Module und ihrer transitiven Abhängigkeiten automatisch zu verarbeiten.

Stattdessen müssen Sie jedes erforderliche Untermodul direkt in die Datei build.sbt einfügen. Es ist wichtig, die Versionen aller verwendeten google-auth-library-Module explizit anzugeben und aufeinander abzustimmen. Wenn die Versionen nicht konsistent gehalten werden, kann es zu Versionskonflikten zwischen transitiven Abhängigkeiten kommen, was möglicherweise zu unerwartetem Verhalten oder Laufzeitfehlern in Ihrer Anwendung führt.

Fügen Sie dies Ihren Abhängigkeiten hinzu, wenn Sie SBT verwenden:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Von `GoogleCredential` zu `GoogleCredentials` migrieren

GoogleCredential aus google-api-java-client wird nicht mehr unterstützt und GoogleCredentials ist die empfohlene Alternative.

Instanziieren Sie GoogleCredentials mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). So gehen Sie am besten vor:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

Wie Sie GoogleCredentials verwenden, hängt von der Clientbibliothek ab:

Cloud-Clientbibliotheken:Diese Bibliotheken verwenden automatisch Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), sodass Sie in Ihrem Code keine Anmeldedaten angeben müssen.
Google API-Clientbibliotheken:Sie müssen GoogleCredentials instanziieren und an den Client übergeben. Ein Beispiel finden Sie im Google API Java Client Guide.

Standardanmeldedaten für Anwendungen

Die Google Auth-Bibliothek bietet eine Implementierung von Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für Java. Mit ADC können Autorisierungsanmeldedaten für den Aufruf von Google APIs abgerufen werden.

Verwenden Sie ADC, wenn Ihre Anwendung unabhängig vom Nutzer eine konsistente Identität und Autorisierungsstufe erfordert. Wir empfehlen die Verwendung von ADC zum Autorisieren von Aufrufen von Cloud APIs, insbesondere beim Entwickeln von Anwendungen auf Google Cloud.

ADC unterstützt auch die Identitätsföderation von Arbeitslasten, sodass Anwendungen über externe Plattformen wie Amazon Web Services (AWS), Microsoft Azure oder einen beliebigen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud Ressourcen zugreifen können. Wir empfehlen die Workload Identity-Föderation für Nicht-Google Cloud -Umgebungen, da sie das Herunterladen, Verwalten und lokale Speichern privater Dienstkontoschlüssel überflüssig macht.

Standardanmeldedaten für Anwendungen abrufen

Verwenden Sie GoogleCredentials.getApplicationDefault() oder GoogleCredentials.getApplicationDefault(HttpTransportFactory), um Standardanmeldedaten für Anwendungen abzurufen. Diese Methoden geben Standardanmeldedaten für Anwendungen zurück, um die gesamte Anwendung zu identifizieren und zu autorisieren.

Die folgenden Quellen werden in dieser Reihenfolge durchsucht, um die Standardanmeldedaten für Anwendungen zu finden:

Datei mit Anmeldedaten, auf die von der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verwiesen wird.
Anmeldedaten, die vom Google Cloud SDK-Befehl gcloud auth application-default login bereitgestellt werden.
Integrierte Anmeldedaten für Google App Engine.
Google Cloud In die Shell integrierte Anmeldedaten.
Integrierte Google Compute Engine-Anmeldedaten.
- Sie können diese Prüfung überspringen, indem Sie die Umgebungsvariable NO_GCE_CHECK=true festlegen.
- Passen Sie die Metadatenserveradresse an, indem Sie die Umgebungsvariable GCE_METADATA_HOST=<hostname> festlegen.

Explizites Laden von Anmeldedaten

Wenn Sie Anmeldedaten aus einem JSON-Schlüssel für ein Dienstkonto abrufen möchten, verwenden Sie GoogleCredentials.fromStream(InputStream) oder GoogleCredentials.fromStream(InputStream, HttpTransportFactory), wie im folgenden Beispielcode gezeigt.

Die Anmeldedaten müssen aktualisiert werden, bevor das Zugriffstoken verfügbar ist.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

Gefälschte Anmeldedaten

Mit ImpersonatedCredentials können Sie einem Anmeldedatum (dem Hauptkonto) erlauben, die Identität eines Dienstkontos (dem Ziel) zu übernehmen. So kann der Prinzipal als Ziel auf Ressourcen zugreifen, ohne den privaten Schlüssel des Ziels zu benötigen.

Damit Sie ImpersonatedCredentials verwenden können, müssen die folgenden Anforderungen erfüllt sein:

Für das Projekt des Principals muss die IAMCredentials API aktiviert sein.
Das Hauptkonto muss die Rolle Service Account Token Creator (Identity and Access Management) für das Zieldienstkonto haben.

Im folgenden Codebeispiel wird ImpersonatedCredentials erstellt. Die Anmeldedaten des Principals werden über die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) abgerufen. Die resultierenden ImpersonatedCredentials werden dann verwendet, um als Ziel-Dienstkonto auf Google Cloud Storage zuzugreifen.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.iam.gserviceaccount.com")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

Workload Identity-Föderation

Mit der Workload Identity-Föderation kann Ihre Anwendung auf Google Cloud-Ressourcen von Amazon Web Services (AWS), Microsoft Azure oder einem beliebigen Identitätsanbieter zugreifen, der OpenID Connect (OIDC) unterstützt.

Normalerweise haben Anwendungen, die außerhalb von Google Cloud ausgeführt werden, Dienstkontoschlüssel für den Zugriff auf Google Cloud Ressourcen verwendet. Mithilfe der Identitätsföderation kann Ihre Arbeitslast die Identität eines Dienstkontos übernehmen. Dadurch kann die externe Arbeitslast direkt auf Google Cloud -Ressourcen zugreifen und der mit Dienstkontoschlüsseln verbundene Wartungs- und Sicherheitsaufwand entfällt.

Über AWS auf Ressourcen zugreifen

Wenn Sie von Amazon Web Services (AWS) aus auf Google Cloud Ressourcen zugreifen möchten, müssen Sie zuerst die Workload Identity-Föderation konfigurieren. Der Einrichtungsprozess wird unter Über AWS auf Ressourcen zugreifen beschrieben.

Im Rahmen dieses Prozesses generieren Sie eine Konfigurationsdatei für Anmeldedaten. Diese Datei enthält nicht vertrauliche Metadaten, die der Bibliothek mitteilen, wie externe Subjekt-Tokens abgerufen und gegen Dienstkonto-Zugriffstokens eingetauscht werden. Sie können die Datei mit der Google Cloud CLI generieren:

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
AWS_PROVIDER_ID:die AWS-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.

Im Beispiel wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

Wenn Sie AWS IMDSv2 verwenden, müssen Sie dem Befehl gcloud iam workload-identity-pools create-cred-config ein zusätzliches Flag --enable-imdsv2 hinzufügen:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

Sie können jetzt die Auth-Bibliothek verwenden, umGoogle Cloud -Ressourcen von AWS aufzurufen.

Über Microsoft Azure auf Ressourcen zugreifen

Wenn Sie von Microsoft Azure aus auf Google Cloud -Ressourcen zugreifen möchten, müssen Sie zuerst die Workload Identity-Föderation konfigurieren. Die Einrichtung wird unter Über Microsoft Azure auf Ressourcen zugreifen beschrieben.

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
AZURE_PROVIDER_ID:die Azure-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.

Mit diesem Befehl wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

Sie können jetzt die Auth-Bibliothek verwenden, um Google Cloud-Ressourcen aus Azure aufzurufen.

Über einen OIDC-Identitätsanbieter auf Ressourcen zugreifen

Wenn Sie über einen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud Ressourcen zugreifen möchten, müssen Sie zuerst die Workload Identity-Föderation konfigurieren. Eine Anleitung dazu finden Sie unter Workload Identity-Föderation über einen OIDC-Identitätsanbieter konfigurieren.

Im Rahmen dieses Prozesses generieren Sie mit der Google Cloud CLI eine Konfigurationsdatei für Anmeldedaten. Diese Datei enthält nicht vertrauliche Metadaten, die der Bibliothek mitteilen, wie externe Subjekt-Tokens abgerufen und gegen Dienstkonto-Zugriffstokens eingetauscht werden.

Bei OIDC-Anbietern kann die Auth-Bibliothek OIDC-Tokens aus einer lokalen Datei (dateibasierte Anmeldedaten), einem lokalen Server (URL-basierte Anmeldedaten) oder einer Kombination aus X.509-Zertifikat und privatem Schlüssel (X.509-Zertifikat-basierte Anmeldedaten) abrufen.

Dateibasierte Anmeldedaten

Bei dateibasierten Anmeldedaten muss ein Hintergrundprozess den Dateispeicherort vor dem Ablauf kontinuierlich mit einem neuen OIDC-Token aktualisieren. Bei Tokens mit einer Lebensdauer von einer Stunde müssen Sie das Token in der Datei stündlich aktualisieren. Sie können das Token direkt als Nur-Text oder im JSON-Format speichern.

Führen Sie den folgenden Befehl aus, um eine dateibasierte OIDC-Konfiguration zu generieren:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
OIDC_PROVIDER_ID:die OIDC-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
PATH_TO_OIDC_ID_TOKEN:Der Pfad, der zum Abrufen des OIDC-Tokens verwendet wird.

Mit diesem Befehl wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

URL-basierte Anmeldedaten

Bei URL-basierten Anmeldedaten muss auf einem lokalen Server ein GET-Endpunkt gehostet werden, der ein OIDC-Token im Nur-Text- oder JSON-Format bereitstellt. Sie können zusätzliche HTTP-Header angeben, die in der Tokenanfrage gesendet werden sollen, wenn dies vom Endpunkt erforderlich ist.

Führen Sie den folgenden Befehl aus, um eine URL-basierte OIDC-Workload Identity-Konfiguration zu generieren:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
OIDC_PROVIDER_ID:die OIDC-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
URL_TO_GET_OIDC_TOKEN:Die URL des lokalen Server-Endpunkts, der zum Abrufen des OIDC-Tokens aufgerufen werden soll.
HEADER_KEY und HEADER_VALUE: Die zusätzlichen Header-Schlüssel/Wert-Paare, die mit der GET-Anfrage an URL_TO_GET_OIDC_TOKEN übergeben werden sollen, z. B. Metadata-Flavor=Google.

Sie können jetzt die Auth-Bibliothek verwenden, umGoogle Cloud -Ressourcen von einem OIDC-Anbieter aufzurufen.

Auf Ressourcen mit Anmeldedaten zugreifen, die aus X.509-Zertifikaten stammen

Bei Anmeldedaten, die aus X.509-Zertifikaten stammen, verwendet die Authentifizierungsbibliothek ein X.509-Zertifikat und einen privaten Schlüssel, um die Identität Ihrer Anwendung nachzuweisen. X.509-Zertifikate haben ein Ablaufdatum und müssen vor dem Ablaufdatum erneuert werden, um den Zugriff aufrechtzuerhalten.

Weitere Informationen finden Sie in der offiziellen Dokumentation.

Konfigurationsdateien für die X.509-Föderation generieren

Wenn Sie Anmeldedaten konfigurieren möchten, die aus einem X.509-Zertifikat stammen, generieren Sie zwei separate Dateien: eine primäre Konfigurationsdatei für Anmeldedaten und eine Zertifikatskonfigurationsdatei.

Die primäre Konfigurationsdatei für Anmeldedaten enthält die erforderlichen Metadaten für die Authentifizierung. In dieser Datei wird auch auf die Zertifikatskonfigurationsdatei verwiesen.
In der Zertifikatskonfigurationsdatei werden die Dateipfade für das X.509-Zertifikat, den privaten Schlüssel und die Vertrauenskette angegeben.

Mit dem Befehl gcloud iam workload-identity-pools create-cred-config können Sie beide erstellen.

Der Speicherort, an dem gcloud die Zertifikatskonfigurationsdatei erstellt, hängt davon ab, ob Sie das Flag --credential-cert-configuration-output-file verwenden.

Standardverhalten (empfohlen)

Wenn Sie das Flag --credential-cert-configuration-output-file weglassen, erstellt gcloud die Zertifikatskonfigurationsdatei an einem bekannten Standardspeicherort, der von der Auth-Bibliothek automatisch erkannt werden kann. Dieser Ansatz ist für die meisten Anwendungsfälle geeignet. Die Standardkonfigurationsdatei für Anmeldedaten heißt config.json und die Standardkonfigurationsdatei für Zertifikate heißt certificate_config.json.

Führen Sie beispielsweise den folgenden Befehl aus, um die Konfigurationsdateien mit dem Standardverhalten zu erstellen:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
PROVIDER_ID:die Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
PATH_TO_CERTIFICATE:Der Pfad, in dem sich Ihr X.509-Blattzertifikat befindet.
PATH_TO_PRIVATE_KEY:Der Pfad, in dem sich der entsprechende private Schlüssel für das Endzertifikat befindet.
PATH_TO_TRUST_CHAIN:Der Pfad der Datei mit der Vertrauenskette des X.509-Zertifikats. Diese Datei sollte eine PEM-formatierte Datei mit allen Zwischenzertifikaten sein, die zum Vervollständigen der Vertrauenskette zwischen dem Endzertifikat und dem im Pool für die Mitarbeiteridentitätsföderation konfigurierten Trust Store erforderlich sind. Das Endzertifikat ist in dieser Datei optional.

Dieser Befehl führt zu Folgendem:

/path/to/config.json:Die Datei wurde am angegebenen Pfad erstellt. Diese Datei enthält "use_default_certificate_config": true, um Clients anzuweisen, die Zertifikatskonfiguration im Standardpfad zu suchen.
certificate_config.json:Erstellt am Standardkonfigurationspfad der Google Cloud CLI, der unter Linux und macOS normalerweise ~/.config/gcloud/certificate_config.json und unter Windows %APPDATA%\gcloud\certificate_config.json ist.

Benutzerdefinierte Standortfunktionen

Wenn Sie die Zertifikatskonfigurationsdatei an einem nicht standardmäßigen Speicherort speichern müssen, verwenden Sie das Flag --credential-cert-configuration-output-file.

Beispielbefehl (benutzerdefinierter Speicherort):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

Dieser Befehl führt zu Folgendem:

/path/to/config.json:wurde am angegebenen Pfad erstellt. Diese Datei enthält das Feld "certificate_config_location", das auf Ihren benutzerdefinierten Pfad verweist.
cert_config.json:erstellt am /custom/path/cert_config.json, wie durch das Flag angegeben.

Sie können jetzt die Auth-Bibliothek verwenden, umGoogle Cloud -Ressourcen mit Anmeldedaten aufzurufen, die aus X.509-Zertifikaten stammen.

Ausführbare Datei-basierte Anmeldedaten mit OIDC und SAML verwenden

Bei ausführbaren Anmeldedaten wird eine lokale ausführbare Datei verwendet, um das Drittanbieter-Token abzurufen. Die ausführbare Datei muss ein gültiges, nicht abgelaufenes OIDC-ID-Token oder eine SAML-Assertion im JSON-Format für stdout bereitstellen.

Wenn Sie ausführbare Datei-basierte Anmeldedaten verwenden möchten, muss die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1 gesetzt sein.

Führen Sie den folgenden Befehl aus, um eine Arbeitslastidentitätskonfiguration mit ausführbaren Anmeldedaten zu generieren:

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
PROVIDER_ID:Die OIDC- oder SAML-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
SUBJECT_TOKEN_TYPE:Der Tokentyp des Subjekts.
EXECUTABLE_COMMAND:Der vollständige Befehl, der ausgeführt werden soll, einschließlich Argumenten. Muss ein absoluter Pfad zum Programm sein.

Das Flag --executable-timeout-millis ist optional. Es gibt die Dauer in Millisekunden an, die die Auth-Bibliothek wartet, bis die ausführbare Datei beendet ist. Wenn keine Angabe erfolgt, beträgt der Standardwert 30 Sekunden. Der zulässige Höchstwert beträgt zwei Minuten und der Mindestwert fünf Sekunden.

Mit dem optionalen Flag --executable-output-file wird ein Pfad angegeben, in dem die Antwort der ausführbaren Datei mit den Anmeldedaten des Drittanbieters zwischengespeichert werden soll. Caching trägt zur Verbesserung der Leistung bei, da die Auth-Bibliotheken zuerst in dieser Datei nach gültigen, nicht abgelaufenen Anmeldedaten suchen, bevor die ausführbare Datei ausgeführt wird. Wenn gültige, im Cache gespeicherte Anmeldedaten vorhanden sind, werden sie von den Bibliotheken verwendet, um unnötige Ausführungen zu vermeiden.

Ihre ausführbare Datei muss die Antwort mit den Anmeldedaten in diese Datei schreiben. Die Auth-Bibliotheken lesen nur aus diesem Speicherort. Der Inhalt der Datei muss dem erwarteten JSON-Format entsprechen.

Zum Abrufen des Drittanbieter-Tokens führt die Bibliothek das ausführbare Programm mit dem angegebenen Befehl aus. Die Ausgabe der ausführbaren Datei muss dem im Folgenden angegebenen Antwortformat entsprechen und die Antwort muss in stdout ausgegeben werden.

Hier ist ein Beispiel für eine erfolgreiche ausführbare OIDC-Antwort:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Hier sehen Sie ein Beispiel für eine erfolgreiche ausführbare SAML-Antwort:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Wenn Sie in der Anmeldedatenkonfiguration eine Ausgabedatei mit dem Argument --executable-output-file angeben, müssen erfolgreiche ausführbare Antworten das Feld expiration_time enthalten. So kann die Auth Library die in dieser Datei gespeicherten Anmeldedaten effektiv im Cache speichern und ihre Gültigkeit verwalten.

Hier ist ein Beispiel für eine ausführbare Fehlerantwort:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Alle diese Felder sind für eine Fehlerantwort erforderlich. Die Bibliothek verwendet die Felder „code“ und „message“ als Teil einer ausgelösten Ausnahme.

Zusammenfassung der Felder des Antwortformats: * version:Die Version der JSON-Ausgabe. Nur Version 1 wird unterstützt. * success:Bei „true“ muss die Antwort das Drittanbieter-Token und den Tokentyp enthalten. Die Antwort muss auch das Feld expiration_time enthalten, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben wurde. Die ausführbare Datei muss auch mit dem Exit-Code 0 beendet werden. Bei „false“ muss die Antwort den Fehlercode und die Nachrichtenfelder enthalten und mit einem Wert ungleich Null beendet werden. * token_type:In diesem Feld wird der Tokentyp des Drittanbieter-Subjekts angegeben. Muss urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token oder urn:ietf:params:oauth:token-type:saml2 sein. * id_token:Das OIDC-Token des Drittanbieters. * saml_response:Die SAML-Antwort des Drittanbieters. * expiration_time:Die Ablaufzeit des Drittanbieter-Subjekttokens in Sekunden (Unixzeit). * code:Der Fehlercodestring. * message:Die Fehlermeldung.

Alle Antworttypen müssen sowohl das Feld version als auch das Feld success enthalten. * Erfolgreiche Antworten müssen token_type und entweder id_token oder saml_response enthalten. Das Feld expiration_time muss auch vorhanden sein, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben wurde. * Fehlerantworten müssen sowohl das Feld code als auch das Feld message enthalten.

Die Bibliothek füllt die folgenden Umgebungsvariablen aus, wenn sie die ausführbare Datei ausführt:

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE:Das Feld für die Zielgruppe aus der Konfiguration der Anmeldedaten. Immer vorhanden.
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE:Der erwartete Tokentyp des Subjekts. Immer vorhanden.
GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL:Die E-Mail-Adresse des Dienstkontos. Nur vorhanden, wenn die Identitätsübernahme des Dienstkontos verwendet wird.
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE:Der Speicherort der Ausgabedatei aus der Konfiguration von Anmeldedaten. Nur vorhanden, wenn in der Konfiguration der Anmeldedaten angegeben.

Diese Umgebungsvariablen können von der ausführbaren Datei verwendet werden, um eine Hartcodierung dieser Werte zu vermeiden.

Sicherheitsaspekte

Wir empfehlen die folgenden Sicherheitsmaßnahmen:

Verhindern Sie, dass schädliche Prozesse die ausführbare Datei ausführen, da dadurch sensible Anmeldedaten über stdout an diese Prozesse und ihre Nutzer ausgegeben werden.
Verhindern, dass unbefugte Prozesse die Konfiguration oder den Aufruf der ausführbaren Datei ändern.

Aufgrund der Komplexität der Verwendung von Anmeldedaten aus ausführbaren Dateien empfehlen wir dringend, andere unterstützte Mechanismen wie Datei- oder URL-Quellen zum Bereitstellen von Drittanbieteranmeldedaten zu verwenden, sofern diese nicht Ihren spezifischen Anforderungen entsprechen.

Sie können jetzt die Auth-Bibliothek verwenden, umGoogle Cloud -Ressourcen von einem OIDC- oder SAML-Anbieter aufzurufen.

Benutzerdefinierten Anbieter mit OIDC und SAML verwenden

Bei der Entwicklung von IdentityPoolCredentials kann eine benutzerdefinierte Implementierung von IdentityPoolSubjectTokenSupplier verwendet werden, um ein Subjekt-Token bereitzustellen, das gegen ein Google Cloud -Zugriffstoken eingetauscht werden kann. Der Anbieter muss ein gültiges, nicht abgelaufenes Subjekt-Token zurückgeben, wenn er über die Google Cloud-Anmeldedaten aufgerufen wird.

IdentityPoolCredentials Das zurückgegebene Token wird nicht im Cache gespeichert. Implementieren Sie daher eine Caching-Logik im Tokenanbieter, um mehrere Anfragen für dasselbe Subjekt-Token zu verhindern.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

Zielgruppe:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
WORKLOAD_POOL_ID:die ID des Workload Identity-Pools.
PROVIDER_ID:die Anbieter-ID.

Sie können die Werte für „Zielgruppe“, „URL für die Identitätsübernahme des Dienstkontos“ und alle anderen Builder-Felder auch abrufen, indem Sie mit der gcloud CLI eine Konfigurationsdatei mit Anmeldedaten generieren.

Benutzerdefinierten Anbieter mit AWS verwenden

Bei der Initialisierung von AwsCredentials kann eine benutzerdefinierte Implementierung von AwsSecurityCredentialsSupplier angegeben werden. Wenn die AwsCredentials-Instanz bereitgestellt wird, wird der Lieferant aufgefordert, AWS-Sicherheitsanmeldedaten abzurufen, die gegen einGoogle Cloud -Zugriffstoken eingetauscht werden. Der Lieferant muss gültige, nicht abgelaufene AWS-Sicherheitsanmeldedaten zurückgeben, wenn er vom Google Cloud -Anmeldedatenobjekt aufgerufen wird.

AwsCredentials speichert die zurückgegebenen AWS-Sicherheitsanmeldedaten oder die Region nicht im Cache. Implementieren Sie daher eine Caching-Logik im Lieferanten, um mehrere Anfragen für dieselben Ressourcen zu verhindern.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

Dabei gilt für die Zielgruppe: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
WORKLOAD_POOL_ID:die ID des Workload Identity-Pools.
PROVIDER_ID:die Anbieter-ID.

Konfigurierbare Lebensdauer des Tokens

Wenn Sie eine Anmeldedatenkonfiguration mit Workload Identity-Föderation mithilfe der Identitätsübernahme des Dienstkontos erstellen, können Sie ein optionales Argument angeben, um die Lebensdauer des Dienstkonto-Zugriffstokens zu konfigurieren.

Führen Sie den folgenden Befehl aus, um die Konfiguration mit konfigurierbarer Token-Lebensdauer zu generieren. In diesem Beispiel wird eine AWS-Konfiguration verwendet, die Token-Lebensdauer kann jedoch für alle Anbieter für die Workload Identity-Föderation konfiguriert werden:

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

Ersetzen Sie Folgendes:

PROJECT_NUMBER:die Google Cloud Projektnummer.
POOL_ID:die ID des Workload Identity-Pools.
AWS_PROVIDER_ID:die AWS-Anbieter-ID.
SERVICE_ACCOUNT_EMAIL:die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
TOKEN_LIFETIME:Die ausgewählte Lebensdauer des Dienstkonto-Zugriffstokens in Sekunden.

Das Flag service-account-token-lifetime-seconds ist optional. Wenn nicht angegeben, beträgt der Standardwert für das Flag eine Stunde. Der zulässige Mindestwert beträgt 600 Sekunden (10 Minuten) und der zulässige Höchstwert 43.200 Sekunden (12 Stunden). Wenn Sie eine Lebensdauer von mehr als einer Stunde benötigen, müssen Sie das Dienstkonto als zulässigen Wert in einem Organizations Policy Service hinzufügen, der die Einschränkung constraints/iam.allowServiceAccountCredentialLifetimeExtension erzwingt.

Wenn Sie eine kurze Lebensdauer konfigurieren (z. B. 10 Minuten), wird der gesamte Tokenaustauschvorgang von der Bibliothek alle 10 Minuten initiiert. Dadurch wird der Drittanbieter für das Token aufgerufen, auch wenn das Drittanbieter-Token nicht abgelaufen ist.

Anmeldedaten von Mitarbeitern mit autorisierten externen Konten verwenden

Mit Anmeldedaten für autorisierte Nutzer für externe Konten können Sie sich mit einem Webbrowser in einem Konto eines externen Identitätsanbieters anmelden und eine Konfiguration für die Auth-Bibliothek erstellen.

Führen Sie den folgenden Befehl aus, um eine Workforce Identity-Konfiguration für einen autorisierten Nutzer eines externen Kontos zu generieren:

gcloud auth application-default login --login-config=LOGIN_CONFIG

Dabei muss die folgende Variable ersetzt werden:

LOGIN_CONFIG:Die Anmeldekonfigurationsdatei, die mit der Google Cloud -Konsole oder gcloud iam workforce-pools create-login-config generiert wurde.

Dadurch wird ein Browserablauf geöffnet, über den Sie sich mit dem konfigurierten Drittanbieter-Identitätsanbieter anmelden können. Anschließend wird die Konfiguration des autorisierten Nutzers des externen Kontos am bekannten ADC-Speicherort gespeichert.

Die Auth-Bibliothek verwendet dann das bereitgestellte Aktualisierungstoken aus der Konfiguration, um ein Zugriffstoken zum Aufrufen von Google Cloud -Diensten zu generieren und zu aktualisieren.

Die Standardlebensdauer des Aktualisierungstokens beträgt eine Stunde. Danach müssen Sie eine neue Konfiguration über die gcloud CLI generieren. Sie können die Lebensdauer ändern, indem Sie die Sitzungsdauer des Personalpools anpassen. Sie können sie auf bis zu 12 Stunden festlegen.

Externe Identitäten verwenden

Sie können externe Identitäten mit Application Default Credentials verwenden. Wenn Sie externe Identitäten mit Standardanmeldedaten für Anwendungen verwenden möchten, generieren Sie die JSON-Konfigurationsdatei für Anmeldedaten für Ihre externe Identität, wie im Abschnitt Workload Identity-Föderation beschrieben. Speichern Sie nach dem Generieren den Pfad zu dieser Datei in der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

Die Bibliothek kann jetzt den richtigen Clienttyp auswählen und Anmeldedaten aus dem Kontext initialisieren, den die Konfigurationsdatei bereitstellt.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

Sie können auch explizit Clients für externe Konten mit der generierten Konfigurationsdatei initialisieren.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

Sicherheitsaspekte

In dieser Bibliothek werden die Felder token_url, token_info_url oder service_account_impersonation_url der Konfiguration der Anmeldedaten nicht validiert. Wir empfehlen, keine Anmeldedatenkonfiguration zu verwenden, die nicht mit der gcloud CLI generiert wurde, es sei denn, Sie haben überprüft, dass die URL-Felder auf eine googleapis.com-Domain verweisen.

Mit Anmeldedaten-Zugriffsgrenzen herabstufen

Berechtigungen mit Zugriffsgrenzen für Anmeldedaten einschränken: Mit dieser Funktion können Sie die Berechtigungen für Identity and Access Management (IAM) einschränken, die von kurzlebigen Anmeldedaten für Cloud Storage verwendet werden können. Dazu müssen Sie eine CredentialAccessBoundary erstellen, in der die Einschränkungen für das eingeschränkte Token definiert werden. Durch die Verwendung von Anmeldedaten mit eingeschränkten Berechtigungen wird dafür gesorgt, dass Tokens, die übertragen werden, immer die geringsten Berechtigungen haben. Weitere Informationen finden Sie unter Prinzip der geringsten Berechtigung.

`CredentialAccessBoundary` erstellen

Die Zugriffsgrenze für Anmeldedaten gibt an, auf welche Ressourcen die neu erstellten Anmeldedaten zugreifen können. Außerdem wird eine Obergrenze für die Berechtigungen angegeben, die für jede Ressource verfügbar sind. Es enthält ein oder mehrere AccessBoundaryRule-Objekte.

Das folgende Snippet zeigt, wie ein CredentialAccessBoundary mit einem AccessBoundaryRule initialisiert wird. Diese Regel gibt an, dass das eingeschränkte Token Lesezugriff auf Objekte hat, die mit customer-a im Bucket bucket-123 beginnen.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

Häufiges Nutzungsmuster

Das gängige Nutzungsmuster umfasst einen Token-Broker mit erhöhten Berechtigungen. Dieser Broker generiert herabgestufte Anmeldedaten aus Quellanmeldedaten mit höherem Zugriff. Anschließend werden die herabgestuften kurzlebigen Zugriffstokens über einen sicheren authentifizierten Kanal an einen Token-Nutzer weitergegeben, um eingeschränkten Zugriff auf Google Cloud-Speicherressourcen zu ermöglichen.

Tokens mit eingeschränkten Berechtigungen generieren

Es gibt zwei Möglichkeiten, eingeschränkte Tokens mit einer CredentialAccessBoundary zu generieren:

Serverseitig (mit DownscopedCredentials): Der Client ruft den Security Token Service (STS) jedes Mal auf, wenn ein Token mit eingeschränktem Umfang benötigt wird. Diese Methode eignet sich für Anwendungen, in denen sich die Regeln für die Zugriffsgrenze für Anmeldedaten nur selten ändern oder in denen Sie eine einzelne herabgestufte Anmeldedaten häufig wiederverwenden. Wichtig ist, dass für jede Regeländerung ein neuer Aufruf an den STS erforderlich ist. Dieser Ansatz ist in der google-auth-library-oauth2-http-Bibliothek verfügbar und erfordert keine zusätzlichen Abhängigkeiten. Dadurch wird die Integration vereinfacht. Diese Option ist eine gute Wahl, wenn Ihr Anwendungsfall nicht die spezifischen Vorteile des clientseitigen Ansatzes erfordert.
Clientseitig (mit ClientSideCredentialAccessBoundaryFactory): Der Client ruft kryptografisches Material einmal ab und generiert dann mehrere lokal eingeschränkte Tokens. Dadurch werden weniger Aufrufe an den STS gesendet und die Effizienz wird gesteigert, wenn sich die Regeln für die Anmeldedatenzugriffsgrenze häufig ändern, da der Client nicht bei jeder Regeländerung den STS kontaktieren muss. Das ist auch effizienter für Anwendungen, die viele eindeutige Tokens mit eingeschränktem Umfang generieren müssen. Dieser Ansatz ist im Modul google-auth-library-cab-token-generator verfügbar. Dieses Modul hat jedoch eigene Abhängigkeiten. Diese Abhängigkeiten können Ihr Projekt komplexer machen. Dieser Ansatz ist sinnvoll, wenn es vor allem darum geht, STS-Aufrufe zu minimieren und zahlreiche eindeutige Tokens zu generieren. Außerdem müssen Sie die zusätzlichen Abhängigkeiten verwalten.

Serverseitige CAB

Mit der Klasse DownscopedCredentials kann ein eingeschränktes Zugriffstoken aus einem Quellanmeldedatum und der CredentialAccessBoundary erstellt werden.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

Clientseitige CAB

Bei der clientseitigen CAB wird ClientSideCredentialAccessBoundaryFactory mit einem Quell-Anmeldedatum verwendet. Nach der Initialisierung der Factory kann die Methode generateToken() wiederholt mit verschiedenen CredentialAccessBoundary-Objekten aufgerufen werden, um mehrere eingeschränkte Tokens zu erstellen.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

Eingeschränkte Zugriffstokens verwenden

Sie können einen Tokenbroker auf einem Server in einem privaten Netzwerk einrichten. Verschiedene Arbeitslasten (Token-Nutzer) im selben Netzwerk senden authentifizierte Anfragen an diesen Broker, um herabgestufte Tokens zu erhalten. Mit diesen Tokens können sie auf bestimmte Google Cloud Storage-Buckets zugreifen oder diese ändern.

Der Broker instanziiert herabgestufte Anmeldedateninstanzen, mit denen kurzlebige, herabgestufte Zugriffstokens generiert werden können. Anschließend werden diese Tokens an den Token-Consumer übergeben.

Diese herabgestuften Zugriffstokens können vom Token-Nutzer mit OAuth2Credentials oder OAuth2CredentialsWithRefresh verwendet werden. Mit diesen Anmeldedaten können Sie dann eine Storage-Clientinstanz initialisieren, um auf Google Cloud-Storage-Ressourcen mit eingeschränktem Zugriff zuzugreifen.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Zugriffsgrenzen für Anmeldedaten werden nur in Cloud Storage unterstützt. AndereGoogle Cloud -Dienste unterstützen diese Funktion nicht.

Anmeldedaten mit `google-http-client` verwenden

Anmeldedaten, die von com.google.auth:google-auth-library-oauth2-http bereitgestellt werden, können mit den HTTP-basierten Clients von Google verwendet werden. Die HTTP-basierten Clients von Google bieten eine HttpCredentialsAdapter, die als HttpRequestInitializer verwendet werden kann, das letzte Argument für ihre Builder.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

JWT-Tokens überprüfen (Betafunktion)

Verwenden Sie die Klasse TokenVerifier, um ein JWT-Token zu überprüfen.

Signatur überprüfen

Verwenden Sie die Standardeinstellung TokenVerifier, um eine Signatur zu prüfen:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

`TokenVerifier` anpassen

Wenn Sie ein TokenVerifier anpassen möchten, instanziieren Sie es mit seinem Builder:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Weitere Optionen finden Sie in der Dokumentation zu TokenVerifier.Builder.

`google-auth-library-credentials`

Dieses Artefakt enthält Basisklassen und ‑schnittstellen für Google-Anmeldedaten:

Credentials:Dies ist die Basisklasse für eine autorisierte Identität. Implementierungen dieser Klasse können Ihre Anwendung autorisieren.
RequestMetadataCallback:Dies ist die Schnittstelle für den Callback, der das Ergebnis des asynchronen Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) empfängt.
ServiceAccountSigner:Dies ist die Schnittstelle für einen Dienstkonto-Signierer. Implementierungen dieser Klasse können Byte-Arrays mit den Anmeldedaten signieren, die einem Google-Dienstkonto zugeordnet sind.

`google-auth-library-appengine`

Dieses Artefakt hängt vom App Engine SDK (appengine-api-1.0-sdk) ab. Verwenden Sie es nur für Anwendungen, die in App Engine-Umgebungen ausgeführt werden, in denen urlfetch verwendet wird. Mit der Klasse AppEngineCredentials können Sie Ihre App Engine-Anwendung mit einer Instanz von AppIdentityService autorisieren.

Verwendung:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

Dieses Modul stellt die Klasse ClientSideCredentialAccessBoundaryFactory bereit, mit der clientseitig herabgestufte Tokens für Cloud Storage mithilfe von Zugriffsgrenzen für Anmeldedaten generiert werden können. Dieser Ansatz ist besonders nützlich für Anwendungen, bei denen häufig Änderungen an den Regeln für die Credential Access Boundary erforderlich sind oder viele eindeutige herabgestufte Tokens generiert werden müssen, da er die Anzahl der Aufrufe des Security Token Service (STS) minimiert. Beispiele für die Verwendung finden Sie im Abschnitt Clientseitige CAB. Dieses Modul hat eigene Abhängigkeiten. Prüfen Sie, ob die Vorteile der clientseitigen Einschränkung des Gültigkeitsbereichs die zusätzliche Komplexität für Ihren spezifischen Anwendungsfall überwiegen.

Erste Schritte mit der Google-Authentifizierungsbibliothek Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Anmeldedatenkonfigurationen validieren

Auth-Bibliothek importieren

Java SDK-Bibliotheken-BOM

Google Auth Library-Stückliste

Maven

Gradle

Scala

Von GoogleCredential zu GoogleCredentials migrieren

Standardanmeldedaten für Anwendungen

Standardanmeldedaten für Anwendungen abrufen

Explizites Laden von Anmeldedaten

Gefälschte Anmeldedaten

Workload Identity-Föderation

Über AWS auf Ressourcen zugreifen

Über Microsoft Azure auf Ressourcen zugreifen

Über einen OIDC-Identitätsanbieter auf Ressourcen zugreifen

Dateibasierte Anmeldedaten

URL-basierte Anmeldedaten

Auf Ressourcen mit Anmeldedaten zugreifen, die aus X.509-Zertifikaten stammen

Konfigurationsdateien für die X.509-Föderation generieren

Standardverhalten (empfohlen)

Benutzerdefinierte Standortfunktionen

Ausführbare Datei-basierte Anmeldedaten mit OIDC und SAML verwenden

Sicherheitsaspekte

Benutzerdefinierten Anbieter mit OIDC und SAML verwenden

Benutzerdefinierten Anbieter mit AWS verwenden

Konfigurierbare Lebensdauer des Tokens

Anmeldedaten von Mitarbeitern mit autorisierten externen Konten verwenden

Externe Identitäten verwenden

Sicherheitsaspekte

Mit Anmeldedaten-Zugriffsgrenzen herabstufen

CredentialAccessBoundary erstellen

Häufiges Nutzungsmuster

Tokens mit eingeschränkten Berechtigungen generieren

Serverseitige CAB

Clientseitige CAB

Eingeschränkte Zugriffstokens verwenden

Anmeldedaten mit google-http-client verwenden

JWT-Tokens überprüfen (Betafunktion)

Signatur überprüfen

TokenVerifier anpassen

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

Erste Schritte mit der Google-Authentifizierungsbibliothek

Von `GoogleCredential` zu `GoogleCredentials` migrieren

`CredentialAccessBoundary` erstellen

Anmeldedaten mit `google-http-client` verwenden

`TokenVerifier` anpassen

`google-auth-library-credentials`

`google-auth-library-appengine`