Ü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 Cloud de Confiance by S3NS -Dienste zu authentifizieren.
In diesem Leitfaden erfahren Sie, wie Sie:
- Fügen Sie Ihrem Projekt die erforderlichen Abhängigkeiten der Google-Authentifizierungsbibliothek 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 API-Dokumentation zur Google Auth-Bibliothek.
Die Google Auth-Bibliothek für Java besteht aus vier Artefakten:
google-auth-library-credentialsenthält Basisklassen und Schnittstellen für Google-Anmeldedaten.google-auth-library-appengineenthält App Engine-Anmeldedaten und ist vom App Engine SDK abhängig.google-auth-library-oauth2-httpenthält eine Vielzahl von Anmeldedaten und Hilfsmethoden, 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-generatorbietet 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 beiCloud de Confiance by S3NS 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.
Google-Authentifizierungsbibliothek importieren
Verwenden Sie zum Importieren der Google-Authentifizierungsbibliothek com.google.cloud:libraries-bom oder die Google-Authentifizierungsbibliothek-Materialliste mit Maven oder Gradle.
Java SDK libraries-bom
Wenn Sie sich mit der Google 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 Google Auth-Bibliothek abgerufen, die mit dieser Clientbibliothek kompatibel sind.
So importieren Sie beispielsweise die Google Auth-Bibliothek 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 Google Auth-Bibliotheksmodule direkt mit der Google Auth-Bibliotheks-Materialliste.
Google Auth Library – Materialliste
Mit der Google Auth Library Materialliste können Sie sicherstellen, dass die Google Auth Library-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 Google Auth-Bibliotheksmodule 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 Google 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 Google Auth-Bibliothek
Die Google Auth-Bibliothek für Java 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 Google-Authentifizierungsbibliothek deaktiviert, um das Preisgeben vertraulicher 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 eingestellt 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
GoogleCredentialsinstanziieren und an den Client übergeben. Ein Beispiel finden Sie im Leitfaden für den Google API-Java-Client.
Standardanmeldedaten für Anwendungen
Die Google Auth-Bibliothek für Java bietet eine Implementierung von Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). Mit Standardanmeldedaten für Anwendungen können Sie Autorisierungsdaten für den Aufruf von Google APIs abrufen.
Verwenden Sie ADC, wenn Ihre Anwendung eine konsistente Identität und Autorisierungsstufe erfordert, unabhängig vom Nutzer. Wir empfehlen, Standardanmeldedaten für Anwendungen zu verwenden, um Aufrufe von Cloud APIs zu autorisieren, insbesondere beim Erstellen von Anwendungen in Cloud de Confiance.
ADC unterstützt auch die Identitätsföderation von Arbeitslasten, sodass Anwendungen auf Cloud de Confiance -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 Umgebungen, die nicht zuCloud de Confiance gehören, 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:
- Datei mit Anmeldedaten, auf die die Umgebungsvariable
GOOGLE_APPLICATION_CREDENTIALSverweist. - Anmeldedaten, die vom Google Cloud SDK-Befehl
gcloud auth application-default loginbereitgestellt werden. - Integrierte Google App Engine-Anmeldedaten.
- Cloud de Confiance Integrierte Shell-Anmeldedaten.
- In Google Compute Engine integrierte Anmeldedaten.
- Überspringen Sie diese Prüfung, indem Sie die Umgebungsvariable
NO_GCE_CHECK=truefestlegen. - Passen Sie die Adresse des Metadatenservers an, indem Sie die Umgebungsvariable
GCE_METADATA_HOST=<hostname>festlegen.
- Überspringen Sie diese Prüfung, indem Sie die Umgebungsvariable
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
IAMCredentialsAPI aktiviert sein. - Das Hauptkonto muss die IAM-Rolle (Identity and Access Management)
Service Account Token Creatorfü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.s3ns.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);
}
Zertifikatsgebundene Tokens für 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 Aktualisierungstoken ü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_CONFIGbenannt ist, oder am Standardspeicherort (/var/run/secrets/workload-spiffe-credentials/). - Die SPIFFE-ID des Zertifikats gehört zu einer Vertrauensdomäne für 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
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 ein Feature. Bei jedem anderen Wert bleibt die Standardeinstellung erhalten.
Umgebungsvariablen gelten für den gesamten Prozess. Wenn Sie die Tokenbindung deaktivieren, sind alle Bibliotheken in Ihrer Anwendung betroffen, die Standardanmeldedaten für Anwendungen verwenden, nicht nur die, die sie benötigen. 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 (Standardeinstellung) schlagen diese Aufrufe mit
com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentialsfehl. Zur Umgehung dieses Problems legen SieGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falsefü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 Cloud de Confiance-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 Cloud de Confiance ausgeführt werden, Dienstkontoschlüssel für den Zugriff auf Ressourcen in Cloud de Confiance verwendet. Mithilfe der Identitätsföderation kann Ihre Arbeitslast die Identität eines Dienstkontos übernehmen. Dadurch kann die externe Arbeitslast direkt auf Ressourcen in Cloud de Confiance zugreifen. Der mit Dienstkontoschlüsseln verbundene Wartungs- und Sicherheitsaufwand entfällt.
Über AWS auf Ressourcen zugreifen
Wenn Sie auf Cloud de Confiance -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 Dienstkonto-Zugriffstokens 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 Cloud de Confiance .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 Google Auth-Bibliothek für Java verwenden, umCloud de Confiance by S3NS -Ressourcen von AWS aufzurufen.
Über Microsoft Azure auf Ressourcen zugreifen
Wenn Sie von Microsoft Azure auf Ressourcen von Cloud de Confiance 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 Dienstkonto-Zugriffstokens 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 Cloud de Confiance .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 Google Auth-Bibliothek für Java verwenden, um Cloud de Confiance-Ressourcen aus Azure aufzurufen.
Über einen OIDC-Identitätsanbieter auf Ressourcen zugreifen
Wenn Sie von einem Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Cloud de Confiance -Ressourcen zugreifen möchten, 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 Anmeldedaten. Diese Datei enthält nicht vertrauliche Metadaten, die die Bibliothek anweisen, wie externe Subjekt-Tokens abgerufen und gegen Dienstkonto-Zugriffstokens ausgetauscht werden.
Bei OIDC-Anbietern kann die Google Auth-Bibliothek für Java OIDC-Tokens aus einer der folgenden Quellen abrufen:
- Eine lokale Datei (dateibasierte Anmeldedaten)
- Ein lokaler Server (URL-basierte Anmeldedaten)
- Ein X.509-Zertifikat und ein privater Schlüssel (Anmeldedaten aus X.509-Zertifikat)
- Eine lokale JSON-Datei, die sowohl ein Subjekttoken als auch ein Akteurtoken für die Akteurdelegation enthält (mit optionaler X.509-Clientzertifikatsbindung)
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 Cloud de Confiance .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 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 Projektnummer von Cloud de Confiance .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.URL_TO_GET_OIDC_TOKEN: Die URL des lokalen Serverendpunkts, der aufgerufen werden soll, um das OIDC-Token abzurufen.HEADER_KEYundHEADER_VALUE: die zusätzlichen Header-Schlüssel/Wert-Paare, die mit der GET-Anfrage anURL_TO_GET_OIDC_TOKENübergeben werden sollen, z. B.Metadata-Flavor=Google.
Sie können jetzt die Google Auth-Bibliothek für Java verwenden, umCloud de Confiance -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 nachzuweisen. 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, müssen Sie zwei separate Dateien generieren: eine primäre Konfigurationsdatei für Anmeldedaten und eine Konfigurationsdatei für Zertifikate.
- 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 standardmäßigen, bekannten Speicherort, den die Google 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 Cloud de Confiance .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.jsonoder unter Windows%APPDATA%\gcloud\certificate_config.jsonist.
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 wie im Flag angegeben um/custom/path/cert_config.jsonerstellt.
Sie können jetzt die Google Auth-Bibliothek für Java verwenden, umCloud de Confiance by S3NS -Ressourcen mit Anmeldedaten aus X.509-Zertifikaten aufzurufen.
Mit Akteurdelegation auf Ressourcen zugreifen
Bei Arbeitslasten, die die OIDC-Workload Identity-Föderation mit Akteurdelegation (wie in RFC 8693: OAuth 2.0 Token Exchange definiert) verwenden, tauscht die Google Auth-Bibliothek für Java sowohl ein Subjekttoken eines Drittanbieters als auch ein Akteurtoken eines Drittanbieters aus einer lokalen JSON-Datei aus. Das Subjekttoken stellt die Hauptkontoidentität für die Anfrage dar und das Akteurtoken die Arbeitslast oder den Dienst, die im Namen des Subjekts agieren.
Sie können die Akteurdelegation in zwei Modi verwenden:
- Standardmäßige Akteurdelegierung (ohne Zertifikatsbindung): Die Google Auth-Bibliothek tauscht das Subjekttoken und das Akteurtoken über Standard-TLS mit dem Security Token Service (
sts.googleapis.com) aus und übernimmt, falls konfiguriert, die Identität eines Dienstkontos mitiamcredentials.googleapis.com. - Zertifikatsgebundene Tokens mit Akteurdelegation (mTLS): Die Google Auth-Bibliothek präsentiert während des Tokenaustauschs mit
sts.mtls.googleapis.com(und, falls konfiguriert, der Identitätsübernahme des Dienstkontos mitiamcredentials.mtls.googleapis.com) ein X.509-Clientzertifikat über gegenseitiges TLS (mTLS).Cloud de Confiance prüft, ob der SHA-256-Zertifikat-Fingerabdruck in der Bestätigungsforderung (cnf.x5t#S256) des Tokens mit dem im mTLS-Handshake präsentierten Blatt-Clientzertifikat übereinstimmt, und stellt ein kurzlebiges Zugriffstoken aus, das kryptografisch an dieses Zertifikat gebunden ist.
Hinweis
Bevor Sie die Google Auth-Bibliothek für Java konfigurieren, benötigen Sie Folgendes:
- Einen OIDC-Workload Identity-Pool und -Anbieter, der für die Akteurdelegation konfiguriert ist (mit dem vollständigen Ressourcennamen des Akteur-Anbieters, der in der
--actor-providers-Konfiguration des Subjekt-Anbieters autorisiert ist) und optional die Erzwingung von Richtlinien für den kontextsensitiven Zugriff bei Verwendung von zertifikatsgebundenen Tokens. Ein lokaler Hintergrundprozess, der eine JSON-Datei mit dem Subjekttoken und dem Akteurtoken vor Ablauf kontinuierlich aktualisiert:
{ "subject_token": "<var>SUBJECT_JWT_TOKEN</var>", "actor_token": "<var>ACTOR_JWT_TOKEN</var>" }Die Tokens müssen die folgenden Anforderungen erfüllen:
Subject-Token (
may_act-Anspruch): Das Subject-Token muss einenmay_act-Anspruch enthalten, der densub-Anspruch (und optional deniss-Anspruch) des Akteurs autorisiert:"may_act": { "sub": "<var>ACTOR_SUBJECT</var>", "iss": "<var>ACTOR_ISSUER</var>" } ```Actor-Token (
aud-,sub- undiss-Anforderungen): Dieaud-Anforderung des Actor-Tokens muss auf den vollständigen Ressourcennamen des Actor-Anbieters (//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>ACTOR_PROVIDER_ID</var>) festgelegt sein und diesub- (undiss-)Anforderung muss mit den Werten übereinstimmen, die in dermay_act-Anforderung des Subjekt-Tokens deklariert sind.Bestätigungsanspruch (
cnf) (nur für zertifikatsgebundene Tokens): Die JWT-Nutzlast des gebundenen Tokens muss einencnf-Anspruch enthalten, der den base64url-codierten SHA-256-Zertifikatfingerabdruck (x5t#S256) des DER-codierten X.509-Blattzertifikats der Arbeitslast enthält. Wenn das Subjekttoken zertifikatsgebunden ist, muss das Akteurtoken ebenfalls zertifikatsgebunden sein. Das im mTLS-Handshake präsentierte Clientzertifikat muss mit demcnf.x5t#S256-Zertifikat-Fingerabdruck des Akteurstokens übereinstimmen:"cnf": { "x5t#S256": "<var>BASE64URL_SHA256_CERT_FINGERPRINT</var>" } ```
(Nur für zertifikatsgebundene Tokens) Eine PEM-codierte X.509-Datei mit untergeordnetem Zertifikat und eine entsprechende unverschlüsselte PKCS#8-Datei mit privatem Schlüssel auf dem Laufwerk.
Konfigurationsdateien für die Akteurdelegation generieren
Sie können die Konfigurationsdateien mit dem Befehl gcloud iam workload-identity-pools create-cred-config generieren.
Standard-Akteursdelegierung (ohne Zertifikatsbindung)
Führen Sie den folgenden Befehl aus, um eine Konfigurationsdatei für Anmeldedaten (config.json) für die Standard-Akteursdelegierung ohne Zertifikatsbindung zu generieren:
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--output-file /path/to/config.json
Zertifikatsgebundene Tokens mit Akteurdelegierung (mTLS)
Wenn Sie zertifikatsgebundene Tokens mit Akteurdelegation konfigurieren, generiert die gcloud CLI zwei separate Dateien, wenn die Flags --credential-cert-path und --credential-cert-private-key-path angegeben werden:
- Primäre Konfigurationsdatei für Anmeldedaten (
config.json): Enthält die Metadaten des Workload Identity-Pools,.mtls.googleapis.com-Endpunkte, den Pfad zur JSON-Tokendatei und Feldnamen für die Subjekt- und Akteur-Tokens sowie einen Verweis auf die Zertifikatskonfigurationsdatei. - Zertifikatskonfigurationsdatei (
certificate_config.json): Gibt die Pfade für das untergeordnete X.509-Zertifikat und den privaten Schlüssel der Arbeitslast an.
Wenn Sie das Flag --credential-cert-configuration-output-file weglassen (empfohlen), erstellt gcloud die Datei certificate_config.json im Standardkonfigurationspfad der Google Cloud CLI (~/.config/gcloud/certificate_config.json unter Linux und macOS oder %APPDATA%\gcloud\certificate_config.json unter Windows) und legt "use_default_certificate_config": true in config.json fest:
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--output-file /path/to/config.json
Wenn Sie die Zertifikatskonfigurationsdatei an einem nicht standardmäßigen Speicherort speichern müssen, geben Sie das Flag --credential-cert-configuration-output-file an:
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--credential-cert-configuration-output-file "/custom/path/certificate_config.json" \
--output-file /path/to/config.json
Ersetzen Sie Folgendes:
PROJECT_NUMBER: Die Projektnummer von Cloud de Confiance .POOL_ID: die ID des Workload Identity-Pools.OIDC_PROVIDER_ID: die OIDC-Workload Identity-Poolanbieter-ID, die das Subjekttoken authentifiziert.SERVICE_ACCOUNT_EMAIL: Optional. Die E-Mail-Adresse des Dienstkontos, dessen Identität übernommen werden soll. Lassen Sie--service-accountweg, wenn Sie den direkten Ressourcenzugriff verwenden.PATH_TO_TOKENS_JSON: Der Pfad zur lokalen JSON-Datei, die sowohl das Subjekttoken als auch das Akteurtoken enthält.SUBJECT_TOKEN_FIELD_NAME: Der JSON-Schlüssel inPATH_TO_TOKENS_JSON, der das Subjekttoken enthält (z. B.subject_token).ACTOR_TOKEN_FIELD_NAME: Der JSON-Schlüssel inPATH_TO_TOKENS_JSON, der das Akteurstoken enthält (z. B.actor_token). Dieser Schlüssel muss sich vonSUBJECT_TOKEN_FIELD_NAMEunterscheiden.PATH_TO_CERTIFICATE(nur zertifikatsgebundene Tokens): Der Pfad zu Ihrem PEM-codierten X.509-Blattzertifikat.PATH_TO_PRIVATE_KEY(nur zertifikatsgebundene Tokens): Der Pfad zum entsprechenden PEM-codierten privaten Schlüssel.
Umgebungsvariablen konfigurieren und Cloud de Confiance -APIs aufrufen
Legen Sie
GOOGLE_APPLICATION_CREDENTIALSso fest, dass es auf Ihre Konfigurationsdatei für Anmeldedaten verweist:export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.jsonWenn Sie zertifikatsgebundene Tokens verwenden, legen Sie auch
GOOGLE_API_USE_CLIENT_CERTIFICATE=truefest, um den mTLS-Transport von Clientzertifikaten in den Cloud-Clientbibliotheken zu aktivieren:export GOOGLE_API_USE_CLIENT_CERTIFICATE=trueWenn Sie
certificate_config.jsonan einem benutzerdefinierten Speicherort gespeichert haben, legen SieGOOGLE_API_CERTIFICATE_CONFIGfest:export GOOGLE_API_CERTIFICATE_CONFIG=/custom/path/certificate_config.jsonInitialisieren Sie eine Cloud de Confiance -Clientbibliothek mit Standardanmeldedaten für Anwendungen. Die Clientbibliothek verwendet automatisch
IdentityPoolCredentials, um die Subjekt- und Akteurstokens auszutauschen. Wenn die Zertifikatsbindung konfiguriert ist, wird das Workload-Clientzertifikat über mTLS präsentiert:import com.google.cloud.pubsub.v1.TopicAdminClient; import com.google.pubsub.v1.ProjectName; import com.google.pubsub.v1.Topic; public class ActorDelegationExample { public static void main(String[] args) throws Exception { String projectId = "your-project-id"; // TopicAdminClient automatically detects GOOGLE_APPLICATION_CREDENTIALS // and uses mTLS when GOOGLE_API_USE_CLIENT_CERTIFICATE=true is set. try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) { for (Topic topic : topicAdminClient.listTopics(ProjectName.of(projectId)).iterateAll()) { System.out.println(topic.getName()); } } } }
Token- und Zertifikatsrotation
Wenn Ihr Hintergrundprozess Tokens (und bei zertifikatsgebundenen Tokens das untergeordnete X.509-Zertifikat und den privaten Schlüssel der Arbeitslast) auf dem Laufwerk rotiert, beachten Sie die folgenden Verhaltensweisen und Anforderungen:
- Atomare Updates: Die Google Auth-Bibliothek liest sowohl das Subjekt-Token als auch das Akteur-Token aus der JSON-Token-Datei in einem einzigen Lesevorgang pro Aktualisierung. Aktualisieren Sie die JSON-Tokendatei atomar (z. B. durch Schreiben in eine temporäre Datei und Umbenennen), damit das Subjekttoken und das Akteurtoken synchronisiert bleiben. Wenn Sie zertifikatsgebundene Tokens verwenden, aktualisieren Sie das Zertifikat, den privaten Schlüssel und die JSON-Tokendatei atomar, damit der
cnf.x5t#S256-Fingerabdruck in der Tokendatei mit dem X.509-Zertifikat auf dem Laufwerk synchronisiert bleibt. - Zyklusweises Zertifikat-Pinning (zertifikatsgebundene Tokens): Wenn
IdentityPoolCredentialsein Zugriffstoken über mTLS aktualisiert, wird der X.509-Schlüsselspeicher zu Beginn des Aktualisierungszyklus erfasst. Es wird dasselbe Clientzertifikat sowohl für die Security Token Service-AnfrageexchangeTokenals auch (falls konfiguriert) für die Anfrage zur Identitätsübernahme der Service Account Credentials APIgenerateAccessTokenverwendet. - Automatisches Aktualisieren bei
401 Unauthorized(zertifikatsgebundene Tokens): Wenn das Zertifikat rotiert und eine mTLS-Anfrage401 Unauthorizedzurückgibt, lädt die Google Auth-Bibliothek das X.509-Zertifikat und den privaten Schlüssel automatisch vom Laufwerk neu und versucht einmal, das Token zu aktualisieren.
Fehlerbehebung bei der Akteurdelegierung
In der folgenden Tabelle sind häufige Fehler und Lösungen für die Akteurdelegation aufgeführt:
| Fehler oder Ausnahme | Ursache | Lösung |
|---|---|---|
IllegalArgumentException: Actor tokens are only supported for JSON-formatted credential sources. |
credential_source.format.type fehlt oder ist auf text gesetzt, während actor_token_field_name angegeben ist. |
Legen Sie für credential_source.format.type den Wert "json" fest und geben Sie sowohl subject_token_field_name als auch actor_token_field_name an. |
IllegalArgumentException: The actor_token_field_name must not be empty. |
actor_token_field_name in credential_source.format ist ein leerer String (""). |
Geben Sie einen nicht leeren JSON-Feldnamen für actor_token_field_name an oder entfernen Sie das Feld, wenn die Akteurdelegierung nicht verwendet wird. |
IllegalArgumentException: The actor_token_field_name must differ from the subject_token_field_name. |
actor_token_field_name und subject_token_field_name sind auf denselben JSON-Schlüssel festgelegt. |
Verwenden Sie in Ihrer Tokendatei und in config.json unterschiedliche JSON-Feldnamen für das Subjekttoken und das Akteurtoken. |
IllegalArgumentException: An actorTokenType must be specified when an actorTokenSupplier is configured. (oder umgekehrt) |
In config.json ist nur entweder actor_token_type oder actor_token_field_name vorhanden. |
Geben Sie sowohl "actor_token_type": "urn:ietf:params:oauth:token-type:jwt" als auch credential_source.format.actor_token_field_name an. |
IOException: Invalid token field name. No token was found for field: FIELD_NAME |
Die JSON-Datei unter credential_source.file enthält nicht den konfigurierten Schlüssel subject_token_field_name oder actor_token_field_name oder der Wert ist null. |
Prüfen Sie, ob bei der Tokenaktualisierung beide Schlüssel in die JSON-Datei geschrieben werden. |
IOException: Invalid token field value. Empty token was found for field: FIELD_NAME |
Der konfigurierte Schlüssel subject_token_field_name oder actor_token_field_name in der JSON-Tokendatei ist ein leerer String oder enthält nur Leerzeichen. |
Prüfen Sie, ob bei der Tokenaktualisierung beide Felder mit nicht leeren JWT-Strings gefüllt werden. |
IOException: Token field value for FIELD_NAME must be a String... |
Der Wert bei subject_token_field_name oder actor_token_field_name in der JSON-Tokendatei ist ein JSON-Objekt, ein Array, eine Zahl oder ein boolescher Wert anstelle eines Strings. |
Achten Sie darauf, dass beide Tokenfelder serialisierte JWT-Strings ("eyJ...") enthalten. |
RuntimeException: Failed to initialize mTLS transport for file credential source due to certificate configuration error. |
Das SDK konnte certificate_config.json, das X.509-Zertifikat unter cert_path oder den privaten Schlüssel unter key_path nicht laden oder parsen. |
Prüfen Sie, ob certificate_config.json im Standardpfad (oder GOOGLE_API_CERTIFICATE_CONFIG) vorhanden ist und ob cert_path und key_path auf gültige, lesbare PEM-Dateien verweisen. |
400 Bad Request/invalid_request von sts.mtls.googleapis.com |
Der cnf.x5t#S256-Fingerabdruck im Token stimmt nicht mit dem Clientzertifikat überein, das während des mTLS-Handshakes präsentiert wurde. |
Prüfen Sie, ob der Wert x5t#S256 der base64url-codierte SHA-256-Hash des DER-codierten untergeordneten Zertifikats in certificate_config.json ist. |
401 Unauthorized oder 403 Forbidden beim Aufrufen von Cloud de Confiance -APIs nach erfolgreichem Tokenaustausch |
Die Downstream-Clientbibliothek hat mTLS nicht eingerichtet oder ein anderes Zertifikat als das an das Zugriffstoken gebundene Zertifikat verwendet. | Prüfen Sie, ob export GOOGLE_API_USE_CLIENT_CERTIFICATE=true festgelegt ist und (wenn Sie einen benutzerdefinierten Zertifikatskonfigurationspfad verwenden) GOOGLE_API_CERTIFICATE_CONFIG auf dieselbe certificate_config.json-Datei verweist, auf die config.json verweist. |
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 Cloud de Confiance .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 übernommen 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 Google 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.
Das optionale Flag --executable-output-file gibt einen Pfad zum Speichern der Antwort der ausführbaren Datei mit den Anmeldedaten des Drittanbieters im Cache an. 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 an 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 mit dem Argument --executable-output-file eine Ausgabedatei angeben, müssen erfolgreiche Antworten der ausführbaren Datei ein expiration_time-Feld enthalten. So kann die Google-Authentifizierungsbibliothek 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 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
stdoutvertrauliche Anmeldedaten an diese Prozesse und ihre Nutzer ausgibt. - Verhindern, dass bösartige 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 Google Auth-Bibliothek für Java verwenden, umCloud de Confiance by S3NS -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 Cloud de Confiance Zugriffstoken ausgetauscht werden kann. Der Anbieter muss ein gültiges, nicht abgelaufenes Subjekttoken zurückgeben, wenn er vom Cloud de Confiance-Anmeldedaten aufgerufen wird.
IdentityPoolCredentials speichert das zurückgegebene Token nicht im Cache. Implementieren Sie daher eine Caching-Logik im Tokenanbieter, 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 Cloud de Confiance 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 Cloud de Confiance .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 den Anbieter auffordern, AWS-Sicherheitsanmeldedaten abzurufen, um sie gegen einCloud de Confiance -Zugriffstoken auszutauschen. Der Anbieter muss gültige, nicht abgelaufene AWS-Sicherheitsanmeldedaten zurückgeben, wenn er vom Cloud de Confiance -Anmeldedaten 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 Cloud de Confiance 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 Cloud de Confiance .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 Cloud de Confiance .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 Zugriffstokens für das Dienstkonto 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 aufgerufen, auch 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 über die gcloud CLI in einem externen Identitätsanbieterkonto anmelden und eine Konfiguration für die Google 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 Konfigurationsdatei für die Anmeldung, die mit der Cloud de Confiance 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 Google Auth-Bibliothek für Java verwendet dann das bereitgestellte Aktualisierungstoken aus der Konfiguration, um ein Zugriffstoken zum Aufrufen vonCloud de Confiance -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
Durch das Herabstufen 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 herabgestuften kurzlebigen Zugriffstokens über einen sicheren authentifizierten Kanal an einen Token-Nutzer übergeben, um eingeschränkten Zugriff auf Cloud de Confiance-Speicherressourcen zu gewähren.
Tokens mit eingeschränktem Bereich 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 verwenden. Ein wichtiger Aspekt ist, dass jede Regeländerung einen neuen Aufruf des STS erfordert. Dieser Ansatz ist in dergoogle-auth-library-oauth2-http-Bibliothek verfügbar und erfordert keine zusätzlichen Abhängigkeiten. Das vereinfacht die Integration. Er ist eine gute Wahl, wenn für Ihren Anwendungsfall die spezifischen Vorteile des clientseitigen Ansatzes nicht erforderlich sind.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 imgoogle-auth-library-cab-token-generator-Modul 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 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 Cloud de Confiance 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 Cloud de ConfianceStorage-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. AndereCloud de Confiance -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 asynchronenCredentials.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 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();
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 Zugriffsgrenzen 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 Boundaries 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.