Erste Schritte mit der Google-Authentifizierungsbibliothek

Übersicht

Die Google Auth-Bibliothek ist eine Open-Source-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 die erforderlichen Auth-Bibliotheksabhängigkeiten mit Maven, Gradle oder Simple Build Tool (SBT) hinzu.
• Authentifizierung mit verschiedenen Methoden, wobei der Schwerpunkt auf Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) liegt.
• Konfigurieren Sie erweiterte Authentifizierungsszenarien, einschließlich Workload Identity-Föderation, Workforce Identity-Föderation und Identitätsübernahme des Dienstkontos.
• Generieren und verwenden Sie eingeschränkte Tokens, um Berechtigungen einzuschränken.
• Anmeldedaten in Google HTTP-Clientbibliotheken einbinden.

Diese Dokumentation richtet sich an Java-Entwickler. Ausführliche API-Details finden Sie in der Dokumentation zur Google Auth Library API.

Die Google Auth-Bibliothek 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 Standardanmeldedaten für Anwendungen. Außerdem wird der serverseitige Ansatz zum Generieren von Tokens mit eingeschränktem Bereich 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 zur Authentifizierung beiGoogle Cloud nicht validierte Anmeldedaten zur Verfügung stellen, kann dies die Sicherheit Ihrer Systeme und Daten beeinträchtigen.

Weitere Informationen finden Sie unter Anmeldedaten aus externen Quellen. Standardanmeldedaten.

Authentifizierungsbibliothek importieren

Verwenden Sie zum Importieren der Auth-Bibliothek com.google.cloud:libraries-bom oder die Google Auth Library Materialliste mit Maven oder Gradle.

Java SDK libraries-bom

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

So importieren Sie beispielsweise die Auth-Bibliothek mit Maven mithilfe einer 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 Materialliste.

Google Auth Library – Materialliste

Mit der Google Auth Library Bill of Materials können Sie dafür sorgen, 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 einbinden 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 je nach den Anforderungen Ihrer Anwendung durch google-auth-library-credentials oder google-auth-library-appengine.

Gradle

Ähnlich wie Maven-Nutzer können Gradle-Nutzer die google-auth-library-bom verwenden, um Abhängigkeitsversionen zu verwalten und die Kompatibilität zwischen den verschiedenen google-auth-library-Modulen sicherzustellen.

Wenn Sie die BOM mit Gradle verwenden möchten, fügen Sie die BOM als platform-Abhängigkeit hinzu. Fügen Sie dann die benötigten google-auth-library-Module hinzu. Die BOM sorgt dafür, dass die Versionen aller von Ihnen verwendeten Module kompatibel sind. Fügen Sie der Datei build.gradle 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

Im Gegensatz zu Maven und Gradle unterstützt SBT (Scala Build Tool) keine Maven-Stücklisten (BOMs). Daher können Sie bei der Verwendung von Scala die google-auth-library-bom nicht importieren, um kompatible Versionen der Auth-Bibliotheksmodule und ihrer transitiven Abhängigkeiten automatisch zu verarbeiten.

Stattdessen müssen Sie jedes erforderliche Submodul 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 sind, kann es zu Versionskonflikten zwischen transitiven Abhängigkeiten kommen, was zu unerwartetem Verhalten oder Laufzeitfehlern in Ihrer Anwendung führen kann.

Wenn Sie SBT verwenden, fügen Sie Ihren Abhängigkeiten Folgendes hinzu:

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

Logging der Auth-Bibliothek

Die Java Auth-Bibliothek empfiehlt das Logging mit dem Debugging-Logging der Clientbibliothek. Beim Debugging-Logging werden sensible Tokens (z. B. access_token, refresh_token usw.) gehasht und die Werte maskiert. Das Logging mit java.util.logging ist in der Auth-Bibliothek deaktiviert, um das Offenlegen sensibler Tokens zu verhindern.

Die Client-Debugging-Logging-Funktion ist optional und erfordert eine Einrichtung.

Beim Debugging-Logging kann je nach Logebene Folgendes protokolliert werden:

• Anfrageinformationen: Header, URL, Methode (INFO-Ebene)
• Antwortinformationen: Header, Status, Nachricht (INFO-Ebene)
• Antwortnutzlast (DEBUG-Ebene)

Von GoogleCredential zu GoogleCredentials migrieren

GoogleCredential von google-api-java-client wird nicht mehr unterstützt und GoogleCredentials ist der empfohlene Ersatz.

Instanziieren Sie GoogleCredentials mit Standardanmeldedaten für Anwendungen. Dies ist der empfohlene Ansatz:

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). Sie müssen also keine Anmeldedaten in Ihrem Code angeben.

• Google API-Clientbibliotheken: Sie müssen GoogleCredentials instanziieren und an den Client übergeben. Ein Beispiel finden Sie im Leitfaden zum Google API-Java-Client.

Standardanmeldedaten für Anwendungen

Die Google Auth-Bibliothek bietet eine Implementierung von Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für Java. Standardanmeldedaten für Anwendungen bieten eine Möglichkeit, Autorisierungsdaten für den Aufruf von Google APIs abzurufen.

Verwenden Sie Standardanmeldedaten für Anwendungen, wenn Ihre Anwendung eine konsistente Identität und Autorisierungsstufe erfordert, die unabhängig vom Nutzer ist. Wir empfehlen, Standardanmeldedaten für Anwendungen zu verwenden, um Aufrufe an Cloud APIs zu autorisieren, insbesondere beim Erstellen von Anwendungen in Google Cloud.

ADC unterstützt auch die Identitätsföderation von Arbeitslasten, sodass Anwendungen auf Google Cloud -Ressourcen von externen Plattformen wie Amazon Web Services (AWS), Microsoft Azure oder einem beliebigen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, zugreifen können. Wir empfehlen die Workload Identity-Föderation für Nicht-Google Cloud -Umgebungen, da Sie dann keine privaten Schlüssel für Dienstkonten lokal herunterladen, verwalten und speichern müssen.

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 Elemente werden in dieser Reihenfolge durchsucht, um die Standardanmeldedaten für Anwendungen zu finden:

1. Anmeldedatendatei, auf die die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verweist.
2. Anmeldedaten, die vom Google Cloud SDK-Befehl gcloud auth application-default login bereitgestellt werden.
3. Integrierte Google App Engine-Anmeldedaten.
4. Integrierte Anmeldedaten fürGoogle Cloud Shell.
5. In Google Compute Engine integrierte Anmeldedaten.
   • Überspringen Sie diese Prüfung, indem Sie die Umgebungsvariable NO_GCE_CHECK=true festlegen.
   • Passen Sie die Adresse des Metadatenservers 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();

Anmeldedaten für Identitätsübernahme

Verwenden Sie ImpersonatedCredentials, um einem Berechtigungsnachweis (dem Hauptkonto) zu erlauben, die Identität eines Dienstkontos (dem Ziel) zu übernehmen. Dadurch kann das Hauptkonto 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 Hauptkontos muss die IAMCredentials API aktiviert sein.
• Das Hauptkonto muss die IAM-Rolle (Identity and Access Management) Service Account Token Creator für das Zieldienstkonto haben.

Im folgenden Codebeispiel wird ImpersonatedCredentials erstellt. Die Anmeldedaten des Hauptkontos werden aus den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) abgerufen. Die resultierenden ImpersonatedCredentials werden dann verwendet, um als Zieldienstkonto 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.")
        .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);
}

Zertifikatsgebundene Tokens für KI-Agentenidentitäten

Wenn Ihre Anwendung mit einer Agent-Identität ausgeführt wird (z. B. ein Cloud Run-Dienst oder -Job, der mit --identity-type=agent-identity bereitgestellt wurde), fordert ComputeEngineCredentials standardmäßig zertifikatsgebundene Zugriffstokens und ID-Tokens vom Metadatenserver an. Ein gebundenes Token ist an das X.509-Zertifikat der Arbeitslast gebunden und erfordert den Nachweis des Besitzes des entsprechenden privaten Schlüssels über gegenseitiges TLS (mTLS). Da dieser private Schlüssel nur für die Arbeitslast verfügbar ist, kann ein geleaktes Token nicht von einer anderen Stelle verwendet werden.

Ein gebundenes Token wird nur akzeptiert, wenn die Anfrage, die es enthält, über mTLS mit demselben Zertifikat gesendet wird. Cloud-Clientbibliotheken für Java konfigurieren mTLS und laden rotierte Arbeitslastzertifikate automatisch neu, wenn die Agent-Identität aktiviert ist. Wenn Sie Google APIs mit Ihrem eigenen HTTP-Client aufrufen, müssen Sie mTLS mit dem Arbeitslastzertifikat konfigurieren und es neu laden, wenn die Laufzeit das Zertifikat auf dem Laufwerk rotiert. Nach der Rotation werden neu aktualisierte Aktualisierungstoken an das neue Zertifikat gebunden. Wenn ein neues Token über eine mTLS-Verbindung gesendet wird, die mit dem vorherigen Zertifikat hergestellt wurde, lehnt die API die Anfrage mit 401 UNAUTHENTICATED ab.

Die Bibliothek fordert ein gebundenes Token nur an, wenn alle der folgenden Bedingungen erfüllt sind:

• Ein Arbeitslastzertifikat wird entweder über die Datei gefunden, die durch die Umgebungsvariable GOOGLE_API_CERTIFICATE_CONFIG benannt ist, oder am Standardspeicherort (/var/run/secrets/workload-spiffe-credentials/).
• Die SPIFFE-ID des Zertifikats gehört zu einer Trust-Domain für KI-Agentenidentitäten.
• Tokenbindung und mTLS wurden nicht deaktiviert (siehe Tokenbindung deaktivieren).

In allen anderen Umgebungen verhält sich ComputeEngineCredentials wie zuvor und gibt ungebundene Tokens zurück.

Tokenbindung deaktivieren

Achtung: Wir empfehlen, gebundene Tokens aktiviert zu lassen, da sie Ihren Agenten vor dem Diebstahl von Anmeldedaten schützen.

Wenn Sie die Tokenbindung deaktivieren müssen (siehe Bekannte Einschränkungen), legen Sie die folgende Umgebungsvariable fest:

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false

Umgebungsvariable	Effekt
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN	Legen Sie false fest, um ungebundene Tokens anzufordern.
GOOGLE_API_USE_CLIENT_CERTIFICATE	Wenn Sie hier false festlegen, wird mTLS vollständig deaktiviert, wodurch auch die Tokenbindung deaktiviert wird. Verwenden Sie GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false, wenn Sie nur ungebundene Tokens benötigen.

Bei den Werten wird die Groß-/Kleinschreibung nicht berücksichtigt und umgebende Leerzeichen werden ignoriert. Nur false deaktiviert eine Funktion. Bei jedem anderen Wert bleibt die Standardeinstellung erhalten.

Umgebungsvariablen gelten für den gesamten Prozess. Wenn Sie die Tokenbindung deaktivieren, wirkt sich das auf jede Bibliothek in Ihrer Anwendung aus, die Standardanmeldedaten für Anwendungen verwendet, nicht nur auf die, die sie benötigt. Wenn Sie nur für einige Ziele ungebundene ID-Tokens benötigen, verwenden Sie stattdessen die zielspezifische Option, die unter Ungebundene ID-Tokens für bestimmte Ziele anfordern beschrieben wird.

Ungebundene ID-Tokens für bestimmte Ziele anfordern

Ein gebundenes ID-Token enthält den Zertifikat-Fingerabdruck des Arbeitslastzertifikats in der Anforderung cnf (x5t#S256). Empfangende Dienste können diese Anforderung anhand des Clientzertifikats validieren, das während eines mTLS-Handshakes präsentiert wird, oder die Anforderung ignorieren, wenn sie keine Zertifikatsbindung erzwingen.

Cloud Run erzwingt die Zertifikatsbindung automatisch, wenn der Anspruch cnf in einem ID-Token vorhanden ist. Wenn Sie einen Cloud Run-Dienst mit einem gebundenen ID-Token aufrufen, müssen Sie die zugehörige *.mtls.run.app-URL über mTLS aufrufen. Anfragen an eine Standard-*.run.app-URL oder eine benutzerdefinierte Domain ohne mTLS werden mit 401 Unauthorized abgelehnt.

Wenn Sie einen Dienst aufrufen, der die Zertifikatsbindung über einen Nicht-mTLS-Endpunkt (z. B. eine Standard-*.run.app-URL) erzwingt, oder wenn Sie keine Zertifikatsbindung für einen Zielendpunkt benötigen, übergeben Sie IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN, um ein ungebundenes ID-Token nur für dieses Ziel anzufordern:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

Zugriffstokens und ID-Tokens für andere Ziele sind weiterhin gebunden. Diese Option wird nur von ComputeEngineCredentials unterstützt. Andere IdTokenProvider-Implementierungen fordern keine gebundenen ID-Tokens an und ignorieren diese Option. Daher funktioniert derselbe Code auch außerhalb von Agent-Identitätsumgebungen.

Bekannte Einschränkungen

• Das Agent Development Kit (ADK) für Java verwendet kein mTLS, wenn es Google APIs wie Gemini in Vertex AI aufruft. Bei gebundenen Tokens (Standard) schlagen diese Aufrufe mit com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials fehl. Zur Umgehung dieses Problems legen Sie GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false für Agenten fest, die das ADK für Java verwenden. Weitere Informationen finden Sie unter Agenten in Cloud Run authentifizieren.

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.

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

Über AWS auf Ressourcen zugreifen

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

Im Rahmen dieses Vorgangs 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 Zugriffstokens für Dienstkonten ausgetauscht 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 Projektnummer von Google Cloud .
• 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 übernommen werden soll.

In diesem 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 auf Ressourcen von Google Cloud zugreifen möchten, müssen Sie zuerst die Workload Identity-Föderation konfigurieren. Der Einrichtungsprozess wird unter Auf Ressourcen von Azure zugreifen beschrieben.

Im Rahmen dieses Vorgangs 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 Zugriffstokens für Dienstkonten ausgetauscht werden. Sie können die Datei mit der Google Cloud CLI generieren:

# 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 Projektnummer von Google Cloud .
• 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 übernommen 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 von Azure aufzurufen.

Über einen OIDC-Identitätsanbieter auf Ressourcen zugreifen

Wenn Sie auf Google Cloud -Ressourcen von einem Identitätsanbieter zugreifen möchten, der OpenID Connect (OIDC) unterstützt, müssen Sie zuerst die Workload Identity-Föderation konfigurieren, wie unter Workload Identity-Föderation von einem OIDC-Identitätsanbieter konfigurieren beschrieben.

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

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

Dateibasierte Anmeldedaten

Bei dateibasierten Anmeldedaten muss ein Hintergrundprozess den Dateispeicherort kontinuierlich mit einem neuen OIDC-Token aktualisieren, bevor das alte Token abläuft. Bei Tokens mit einer Lebensdauer von einer Stunde müssen Sie das Token in der Datei jede Stunde 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 Projektnummer von Google Cloud .
• 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 übernommen 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

Für URL-basierte Anmeldedaten muss ein lokaler Server einen GET-Endpunkt hosten, 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 gefordert wird.

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 Projektnummer von Google Cloud .
• POOL_ID: die ID des Workload Identity-Pools.
• OIDC_PROVIDER_ID: die OIDC-Anbieter-ID.
• SERVICE_ACCOUNT_EMAIL: Die E-Mail-Adresse des Dienstkontos, das Sie verwenden möchten.
• URL_TO_GET_OIDC_TOKEN: Die URL des lokalen Server-Endpunkts, der aufgerufen werden soll, um das OIDC-Token abzurufen.
• 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.

Mit Anmeldedaten aus X.509-Zertifikaten auf Ressourcen zugreifen

Bei Anmeldedaten, die aus einem X.509-Zertifikat stammen, verwendet die Authentifizierungsbibliothek ein X.509-Zertifikat und einen privaten Schlüssel, um die Identität Ihrer Anwendung zu bestätigen. X.509-Zertifikate haben ein Ablaufdatum und müssen vor Ablauf verlängert werden, damit der Zugriff erhalten bleibt.

Weitere Informationen finden Sie in der offiziellen Dokumentation.

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

Wenn Sie X.509-Zertifikatsanmeldedaten konfigurieren möchten, 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, den die Auth-Bibliothek automatisch finden 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 Projektnummer von Google Cloud .
• 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 übernommen werden soll.
• PATH_TO_CERTIFICATE: Der Pfad, unter dem sich Ihr Blatt-X.509-Zertifikat befindet.
• PATH_TO_PRIVATE_KEY: Der Pfad, unter dem sich der entsprechende private Schlüssel für das untergeordnete Zertifikat befindet.
• PATH_TO_TRUST_CHAIN: Der Pfad der X.509-Zertifikats-Trust-Chain-Datei. Diese Datei sollte eine PEM-formatierte Datei sein, die alle Zwischenzertifikate enthält, die erforderlich sind, um die Vertrauenskette zwischen dem untergeordneten Zertifikat und dem im Workload Identity-Föderationspool konfigurierten Trust Store zu vervollständigen. Das untergeordnete Zertifikat ist in dieser Datei optional.

Dieser Befehl führt zu Folgendem:

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

Benutzerdefiniertes Standortverhalten

Wenn Sie die Zertifikatkonfigurationsdatei 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: wird im angegebenen Pfad erstellt. Diese Datei enthält ein "certificate_config_location"-Feld, das auf Ihren benutzerdefinierten Pfad verweist.
• cert_config.json: wurde um /custom/path/cert_config.json erstellt, wie im Flag angegeben.

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

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 ausführbare Workload Identity-Konfiguration 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 Projektnummer von Google Cloud .
• 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, das Sie verwenden möchten.
• 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 auf den Abschluss der ausführbaren Datei wartet. Wenn nichts angegeben ist, wird standardmäßig 30 Sekunden verwendet. Der maximal zulässige Wert beträgt zwei Minuten und der Mindestwert fünf Sekunden.

Mit dem optionalen Flag --executable-output-file wird ein Pfad zum Speichern der Antwort der ausführbaren Datei mit den Anmeldedaten des Drittanbieters im Cache angegeben. Caching trägt zur Verbesserung der Leistung bei, da die Auth-Bibliotheken zuerst diese Datei auf gültige, nicht abgelaufene Anmeldedaten prüfen, 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.

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

Zum Abrufen des Drittanbieter-Tokens führt die Bibliothek die ausführbare Datei mit dem angegebenen Befehl aus. Die Ausgabe der ausführbaren Datei muss dem in den folgenden Beispielen 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 ist 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 Konfiguration der Anmeldedaten eine Ausgabedatei mit dem Argument --executable-output-file angeben, müssen erfolgreiche Antworten der ausführbaren Datei ein expiration_time-Feld enthalten. So kann die Auth-Bibliothek die Gültigkeit der in dieser Datei gespeicherten Anmeldedaten effektiv im Cache speichern und verwalten.

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

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

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

Zusammenfassung der Felder im Antwortformat: * version: Die Version der JSON-Ausgabe. Nur Version 1 wird unterstützt. * success: Bei „true“ muss die Antwort das Token des Drittanbieters 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-Subjekt-Tokens in Sekunden (Unix-Epoche). * code: Der Fehlercodestring. * message: Die Fehlermeldung.

Alle Antworttypen müssen die Felder version und success enthalten. * Erfolgreiche Antworten müssen token_type und entweder id_token oder saml_response enthalten. Das Feld expiration_time muss ebenfalls vorhanden sein, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben wurde. * Fehlerantworten müssen die Felder code und 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

Die folgenden Sicherheitsmaßnahmen werden empfohlen:

• Verhindern Sie, dass nicht autorisierte Prozesse die ausführbare Datei ausführen, da diese über stdout vertrauliche Anmeldedaten an diese Prozesse und ihre Nutzer ausgibt.
• Verhindern Sie, dass nicht autorisierte 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 zu verwenden, um Anmeldedaten von Drittanbietern bereitzustellen, sofern sie 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

Eine benutzerdefinierte Implementierung von IdentityPoolSubjectTokenSupplier kann beim Erstellen von IdentityPoolCredentials verwendet werden, um ein Subjekttoken bereitzustellen, das gegen ein Zugriffstoken von Google Cloud ausgetauscht werden kann. Der Anbieter muss ein gültiges, nicht abgelaufenes Subjekttoken zurückgeben, wenn er von den Anmeldedaten des Google Cloudaufgerufen wird.

IdentityPoolCredentials speichert das zurückgegebene Token nicht im Cache. Implementieren Sie daher eine Caching-Logik im Token-Anbieter, um mehrere Anfragen für dasselbe Subjekttoken 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();

Dabei ist 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 Projektnummer von Google Cloud .
• WORKLOAD_POOL_ID: die ID des Workload Identity-Pools.
• PROVIDER_ID: die Anbieter-ID.

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

Benutzerdefinierten Anbieter mit AWS verwenden

Bei der Initialisierung von AwsCredentials kann eine benutzerdefinierte Implementierung von AwsSecurityCredentialsSupplier bereitgestellt werden. Falls angegeben, wird die AwsCredentials-Instanz an den Anbieter verwiesen, um AWS-Sicherheitsanmeldedaten abzurufen, die gegen einGoogle Cloud -Zugriffstoken ausgetauscht werden können. Der Anbieter muss gültige, nicht abgelaufene AWS-Sicherheitsanmeldedaten zurückgeben, wenn er von den Anmeldedaten von Google Cloud aufgerufen wird.

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

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 ist 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 Projektnummer von Google Cloud .
• WORKLOAD_POOL_ID: die ID des Workload Identity-Pools.
• PROVIDER_ID: die Anbieter-ID.

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

Konfigurierbare Token-Lebensdauer

Wenn Sie eine Konfiguration für Anmeldedaten mit der Identitätsföderation von Arbeitslasten und der Identitätsübernahme des Dienstkontos erstellen, können Sie ein optionales Argument angeben, um die Lebensdauer des Zugriffstokens für das Dienstkonto zu konfigurieren.

Führen Sie den folgenden Befehl aus, um die Konfiguration mit konfigurierbarer Tokenlebensdauer zu generieren. In diesem Beispiel wird eine AWS-Konfiguration verwendet, die Tokenlebensdauer kann jedoch für alle Anbieter von Workload Identity-Föderationen 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 Projektnummer von Google Cloud .
• 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 übernommen 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, wird das Flag standardmäßig auf eine Stunde gesetzt. Der zulässige Mindestwert beträgt 600 (10 Minuten) und der zulässige Höchstwert 43.200 (12 Stunden). Wenn Sie eine Lebensdauer von mehr als einer Stunde benötigen, müssen Sie das Dienstkonto als zulässigen Wert in einem Organisationsrichtliniendienst hinzufügen, der die Einschränkung constraints/iam.allowServiceAccountCredentialLifetimeExtension erzwingt.

Wenn Sie eine kurze Lebensdauer (z. B. 10 Minuten) konfigurieren, initiiert die Bibliothek alle 10 Minuten den gesamten Tokenaustauschablauf. Dadurch wird der Drittanbieter-Token-Anbieter auch dann aufgerufen, wenn das Drittanbieter-Token nicht abgelaufen ist.

Anmeldedaten für autorisierte Nutzer von externen Konten verwenden

Mit Anmeldedaten für autorisierte Nutzer externer Konten können Sie sich mit einem Webbrowser in einem externen Identitätsanbieterkonto über die gcloud CLI anmelden und eine Konfiguration für die Authentifizierungsbibliothek 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 Konfigurationsdatei für die Anmeldung, die mit der Google Cloud Console 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. Anschließend müssen Sie eine neue Konfiguration über die gcloud CLI generieren. Sie können die Lebensdauer ändern, indem Sie die Sitzungsdauer des Personalpools ändern. 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 den Pfad zu dieser Datei nach der Generierung in der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

Die Bibliothek kann jetzt den richtigen Clienttyp auswählen und die 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 Clients für externe Konten auch explizit mit der generierten Konfigurationsdatei initialisieren.

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

Sicherheitsaspekte

Diese Bibliothek führt keine Validierung der Felder token_url, token_info_url oder service_account_impersonation_url der Konfiguration der Anmeldedaten durch. Wir empfehlen, keine Konfiguration für Anmeldedaten zu verwenden, die Sie nicht mit der gcloud CLI generiert haben, es sei denn, Sie prüfen, ob die URL-Felder auf eine googleapis.com-Domain verweisen.

Mit Anmeldedaten-Zugriffsgrenzen herabstufen

Mit der Herabstufung mit Zugriffsgrenzen für Anmeldedaten können Sie die IAM-Berechtigungen (Identity and Access Management) einschränken, die von kurzlebigen Anmeldedaten für Cloud Storage verwendet werden können. Dazu müssen Sie eine CredentialAccessBoundary erstellen, die die Einschränkungen für das Token mit eingeschränktem Bereich definiert. Durch die Verwendung von eingeschränkten Anmeldedaten wird sichergestellt, dass Tokens während der Übertragung 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 festgelegt, die für jede Ressource verfügbar sind. Sie enthält ein oder mehrere AccessBoundaryRule-Objekte.

Das folgende Snippet zeigt, wie ein CredentialAccessBoundary mit einem AccessBoundaryRule initialisiert wird. Diese Regel legt fest, dass das Token mit eingeschränktem Bereich 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();

Gängiges Nutzungsmuster

Das gängige Nutzungsmuster umfasst einen Token-Broker mit erweitertem Zugriff. Dieser Broker generiert eingeschränkte Anmeldedaten aus Quellanmeldedaten mit höherem Zugriff. Anschließend werden die eingeschränkten kurzlebigen Zugriffstokens über einen sicheren authentifizierten Kanal an einen Token-Nutzer übergeben, um eingeschränkten Zugriff auf Google CloudStorage-Ressourcen zu gewähren.

Eingeschränkte Tokens generieren

Es gibt zwei Möglichkeiten, herabgestufte Tokens mit einem CredentialAccessBoundary zu generieren:

• Serverseitig (mit DownscopedCredentials): Der Client ruft den Security Token Service (STS) jedes Mal auf, wenn ein Token mit eingeschränktem Bereich benötigt wird. Dies eignet sich für Anwendungen, bei denen sich die Regeln für die Zugriffsgrenze für Anmeldedaten selten ändern oder bei denen Sie dieselben herabgestuften Anmeldedaten mehrmals wiederverwenden. Ein wichtiger Aspekt ist, dass jede Regeländerung einen neuen Aufruf des STS erfordert. Dieser Ansatz ist in der google-auth-library-oauth2-http-Bibliothek verfügbar und erfordert keine zusätzlichen Abhängigkeiten. Das vereinfacht die Integration. Sie ist eine gute Wahl, wenn Ihr Anwendungsfall nicht die spezifischen Vorteile des clientseitigen Ansatzes erfordert.

• Clientseitig (mit ClientSideCredentialAccessBoundaryFactory): Der Client ruft einmal kryptografisches Material ab und generiert dann lokal mehrere Tokens mit eingeschränktem Bereich. Dadurch werden Aufrufe an den STS minimiert und es ist effizienter, wenn sich die Regeln für die Zugriffsbegrenzung für Anmeldedaten häufig ändern, da der Client nicht bei jeder Regeländerung den STS kontaktieren muss. Dies ist auch effizienter für Anwendungen, die viele eindeutige Tokens mit eingeschränktem Bereich 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. Ziehen Sie diesen Ansatz in Betracht, wenn die Minimierung von STS-Aufrufen und die Generierung zahlreicher eindeutiger Tokens im Vordergrund stehen. Außerdem müssen Sie die zusätzlichen Abhängigkeiten verwalten.

Serverseitiges CAB

Mit der Klasse DownscopedCredentials kann ein eingeschränktes Zugriffstoken aus einem Quellanmeldedaten 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();

Clientseitiges CAB

Für clientseitiges CAB wird ClientSideCredentialAccessBoundaryFactory mit einem Quellanmeldedaten verwendet. Nach der Initialisierung der Factory kann die Methode generateToken() wiederholt mit verschiedenen CredentialAccessBoundary-Objekten aufgerufen werden, um mehrere Tokens mit eingeschränktem Bereich 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 Token-Broker auf einem Server in einem privaten Netzwerk einrichten. Verschiedene Arbeitslasten (Token-Nutzer) im selben Netzwerk senden authentifizierte Anfragen für herabgestufte Tokens an diesen Broker. Mit diesen Tokens können sie auf bestimmte Google Cloud Storage-Buckets zugreifen oder diese ändern.

Der Broker instanziiert Instanzen mit eingeschränkten Anmeldedaten, die kurzlebige Zugriffstokens mit eingeschränktem Zugriff generieren können. Anschließend werden diese Tokens an den Token-Nutzer ü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 CloudStorage-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(...)

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

Anmeldedaten mit google-http-client verwenden

Von com.google.auth:google-auth-library-oauth2-http bereitgestellte Anmeldedaten können mit den HTTP-basierten Clients von Google verwendet werden. Die HTTP-basierten Clients von Google stellen einen HttpCredentialsAdapter bereit, der 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 prüfen.

Signatur überprüfen

Verwenden Sie zum Prüfen einer Signatur den Standard-TokenVerifier:

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 eine TokenVerifier anpassen möchten, instanziieren Sie sie mit dem 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 Dienstkontosignierer. 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 mit urlfetch ausgeführt werden. 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();

Wichtig: com.google.auth.appengine.AppEngineCredentials ist eine separate Klasse von com.google.auth.oauth2.AppEngineCredentials.

google-auth-library-cab-token-generator

Dieses Modul stellt die Klasse ClientSideCredentialAccessBoundaryFactory bereit, mit der clientseitig eingeschränkte Tokens für Cloud Storage mithilfe von Zugriffsbeschränkungen für Anmeldedaten generiert werden können. Dieser Ansatz ist besonders nützlich für Anwendungen, die häufige Änderungen an den Regeln für Credential Access Boundarys oder die Generierung vieler eindeutiger herabgestufter Tokens erfordern, da er die Aufrufe des Security Token Service (STS) minimiert. Anwendungsbeispiele finden Sie im Abschnitt Clientseitige CAB. Dieses Modul hat eigene Abhängigkeiten. Prüfen Sie, ob die Vorteile des clientseitigen Downscopings die zusätzliche Komplexität für Ihren spezifischen Anwendungsfall rechtfertigen.