google auth library java

Google Auth-Bibliothek

Open-Source-Authentifizierungs-Client-Bibliothek für Java.

• API-Dokumentation

Dieses Projekt besteht aus 3 Artefakten:

• google-auth-library-credentials : enthält Basisklassen und Schnittstellen für Google-Anmeldeinformationen
• google-auth-library-appengine : enthält App Engine-Anmeldeinformationen. Dieses Artefakt hängt vom App Engine SDK ab.
• google-auth-library-oauth2-http : enthält eine Vielzahl von Anmeldeinformationen sowie Hilfsmethoden, um diese zu erstellen und Standardanmeldeinformationen für Anwendungen abzurufen

Inhaltsverzeichnis:

• Schnellstart

• google-auth-library-oauth2-http

  • Standardanmeldeinformationen für die Anwendung
  • ImpersonatedCredentials
  • Workload Identity Federation
    • Zugriff auf Ressourcen von AWS
    • Zugriff auf Ressourcen über Azure
    • Zugriff auf Ressourcen von einem OIDC-Identitätsanbieter
    • Zugriff auf Ressourcen mit ausführbaren Anmeldeinformationen
    • Zugriff auf Ressourcen über einen benutzerdefinierten Lieferanten für OIDC oder SAML
    • Zugriff auf Ressourcen über einen benutzerdefinierten Lieferanten mit AWS
    • Konfigurierbare Token-Lebensdauer
  • Workforce Identity Federation
    • Zugriff auf Ressourcen über einen OIDC- oder SAML 2.0-Identitätsanbieter
    • Zugriff auf Ressourcen mithilfe der Anmeldeinformationen eines autorisierten Benutzers für externe Konten
    • Zugriff auf Ressourcen mit ausführbaren Anmeldeinformationen
    • Zugriff auf Ressourcen über einen benutzerdefinierten Lieferanten für OIDC oder SAML
  • Downscoping mit Zugriffsgrenzen für Anmeldeinformationen
  • Konfigurieren eines Proxys
  • Verwenden von Anmeldeinformationen mit google-http-client
  • Überprüfen von JWT-Tokens

• Anmeldeinformationen für die Google-Auth-Bibliothek

• google-auth-library-appengine

• CI-Status

• Mitwirken

• Lizenz

Schnellstart

Wenn Sie Maven verwenden, fügen Sie dies Ihrer pom.xml-Datei hinzu (beachten Sie, dass Sie google-auth-library-oauth2-http je nach Bedarf durch beliebige google-auth-library-credentials und google-auth-library-appengine ersetzen können). Ihre Bewerbungsanforderungen):

< dependency >
  < groupId >com.google.authgroupId >
  < artifactId >google-auth-library-oauth2-httpartifactId >
  < version >1.19.0version >
dependency >

Wenn Sie Gradle verwenden, fügen Sie dies zu Ihren Abhängigkeiten hinzu

implementation ' com.google.auth:google-auth-library-oauth2-http:1.19.0 '

Wenn Sie SBT verwenden, fügen Sie dies zu Ihren Abhängigkeiten hinzu

libraryDependencies + = " com.google.auth " % " google-auth-library-oauth2-http " % " 1.19.0 " 

google-auth-library-oauth2-http

Standardanmeldeinformationen für die Anwendung

Diese Bibliothek stellt eine Implementierung von Application Default Credentials für Java bereit. Standardanmeldeinformationen für Anwendungen bieten eine einfache Möglichkeit, Autorisierungsanmeldeinformationen für den Aufruf von Google APIs abzurufen.

Sie eignen sich am besten für Fälle, in denen der Anruf unabhängig vom Benutzer dieselbe Identität und Autorisierungsebene für die Anwendung haben muss. Dies ist der empfohlene Ansatz zum Autorisieren von Aufrufen von Cloud-APIs, insbesondere wenn Sie eine Anwendung erstellen, die die Google Cloud Platform verwendet.

Standardanmeldeinformationen für Anwendungen unterstützen auch die Workload-Identitätsföderation für den Zugriff auf Google Cloud-Ressourcen von Nicht-Google Cloud-Plattformen, einschließlich Amazon Web Services (AWS), Microsoft Azure oder jedem Identitätsanbieter, der OpenID Connect (OIDC) unterstützt. Workload Identity Federation wird für Nicht-Google Cloud-Umgebungen empfohlen, da es die Notwendigkeit vermeidet, private Schlüssel von Dienstkonten lokal herunterzuladen, zu verwalten und zu speichern, siehe: Workload Identity Federation.

Abrufen der Standardanmeldeinformationen für die Anwendung

Um die Standardanmeldeinformationen der Anwendung abzurufen, verwenden Sie GoogleCredentials.getApplicationDefault() oder GoogleCredentials.getApplicationDefault(HttpTransportFactory) . Diese Methoden geben die Standardanmeldeinformationen der Anwendung zurück, die zur Identifizierung und Autorisierung der gesamten Anwendung verwendet werden. Folgendes wird (der Reihe nach) durchsucht, um die Standardanmeldeinformationen der Anwendung zu finden:

1. Anmeldeinformationsdatei, auf die die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verweist
2. Vom Google Cloud SDK-Befehl gcloud auth application-default login bereitgestellte Anmeldeinformationen
3. Integrierte Anmeldeinformationen von Google App Engine
4. Integrierte Anmeldeinformationen für Google Cloud Shell
5. Integrierte Anmeldeinformationen für Google Compute Engine
   • Überspringen Sie diese Prüfung, indem Sie die Umgebungsvariable NO_GCE_CHECK=true festlegen
   • Passen Sie die GCE-Metadatenserveradresse an, indem Sie die Umgebungsvariable GCE_METADATA_HOST= festlegen

Explizites Laden von Anmeldeinformationen

Um Anmeldeinformationen von einem Dienstkonto-JSON-Schlüssel abzurufen, verwenden Sie GoogleCredentials.fromStream(InputStream) oder GoogleCredentials.fromStream(InputStream, HttpTransportFactory) . Beachten Sie, dass die Anmeldeinformationen aktualisiert werden müssen, 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 ();

ImpersonatedCredentials

Ermöglicht einem Benutzer oder Dienstkonto ausgestellte Anmeldeinformationen, sich als ein anderes Konto auszugeben. Das Quellprojekt, das ImpersonatedCredentials verwendet, muss die API „IAMCredentials“ aktivieren. Außerdem muss das Zieldienstkonto dem ursprünglichen Prinzipal die IAM-Rolle „Dienstkonto-Token-Ersteller“ gewähren.

 String credPath = "/path/to/svc_account.json" ;
ServiceAccountCredentials sourceCredentials = ServiceAccountCredentials
     . fromStream ( new FileInputStream ( credPath ));
sourceCredentials = ( ServiceAccountCredentials ) sourceCredentials
    . createScoped ( Arrays . asList ( "https://www.googleapis.com/auth/iam" ));

ImpersonatedCredentials targetCredentials = ImpersonatedCredentials . create ( sourceCredentials ,
    "[email protected]" , null ,
    Arrays . asList ( "https://www.googleapis.com/auth/devstorage.read_only" ), 300 );

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

for ( Bucket b : storage_service . list (). iterateAll ())
    System . out . println ( b ); 

Workload Identity Federation

Mithilfe der Workload Identity Federation kann Ihre Anwendung über Amazon Web Services (AWS), Microsoft Azure oder jeden Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud-Ressourcen zugreifen.

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

Zugriff auf Ressourcen von AWS

Um über Amazon Web Services (AWS) auf Google Cloud-Ressourcen zugreifen zu können, sind folgende Voraussetzungen erforderlich:

• Es muss ein Workload-Identity-Pool erstellt werden.
• AWS muss als Identitätsanbieter im Workload-Identitätspool hinzugefügt werden (die Google-Organisationsrichtlinie muss die Föderation von AWS zulassen).
• Der externen Identität muss die Berechtigung erteilt werden, die Identität eines Dienstkontos anzunehmen.

Befolgen Sie die detaillierten Anweisungen zum Konfigurieren der Workload Identity Federation von AWS.

Nachdem Sie den AWS-Anbieter so konfiguriert haben, dass er sich als Dienstkonto ausgibt, muss eine Konfigurationsdatei für Anmeldeinformationen generiert werden. Im Gegensatz zu Dienstkonto-Anmeldeinformationsdateien enthält die generierte Anmeldeinformationskonfigurationsdatei nicht vertrauliche Metadaten, um die Bibliothek anzuweisen, wie sie externe Betreff-Tokens abruft und sie gegen Dienstkonto-Zugriffstokens austauscht. Die Konfigurationsdatei kann mithilfe der gcloud-CLI generiert werden.

Führen Sie den folgenden Befehl aus, um die AWS-Workload-Identity-Konfiguration zu generieren:

 # Generate an AWS configuration file.
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

Wobei die folgenden Variablen ersetzt werden müssen:

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

Dadurch wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

Wenn Sie AWS IMDSv2 verwenden, muss ein zusätzliches Flag --enable-imdsv2 zum Befehl gcloud iam workload-identity-pools create-cred-config hinzugefügt werden:

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, um Google Cloud-Ressourcen von AWS aus aufzurufen.

Greifen Sie über Microsoft Azure auf Ressourcen zu

Um über Microsoft Azure auf Google Cloud-Ressourcen zugreifen zu können, sind folgende Voraussetzungen erforderlich:

• Es muss ein Workload-Identity-Pool erstellt werden.
• Azure muss als Identitätsanbieter im Workload-Identitätspool hinzugefügt werden (die Google-Organisationsrichtlinie muss die Föderation von Azure zulassen).
• Der Azure-Mandant muss für die Identitätsföderation konfiguriert werden.
• Der externen Identität muss die Berechtigung erteilt werden, die Identität eines Dienstkontos anzunehmen.

Befolgen Sie die detaillierten Anweisungen zum Konfigurieren der Workload Identity-Föderation von Microsoft Azure.

Nachdem Sie den Azure-Anbieter so konfiguriert haben, dass er sich als Dienstkonto ausgibt, muss eine Konfigurationsdatei für Anmeldeinformationen generiert werden. Im Gegensatz zu Dienstkonto-Anmeldeinformationsdateien enthält die generierte Anmeldeinformationskonfigurationsdatei nicht vertrauliche Metadaten, um die Bibliothek anzuweisen, wie sie externe Betreff-Tokens abruft und sie gegen Dienstkonto-Zugriffstokens austauscht. Die Konfigurationsdatei kann mithilfe der gcloud-CLI generiert werden.

Führen Sie den folgenden Befehl aus, um die Azure Workload Identity-Konfiguration zu generieren:

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

Wobei die folgenden Variablen ersetzt werden müssen:

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

Dadurch wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

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

Zugriff auf Ressourcen von einem OIDC-Identitätsanbieter

Um über einen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud-Ressourcen zuzugreifen, sind die folgenden Anforderungen erforderlich:

• Es muss ein Workload-Identity-Pool erstellt werden.
• Dem Workload-Identitätspool muss ein OIDC-Identitätsanbieter hinzugefügt werden (die Google-Organisationsrichtlinie muss die Föderation vom Identitätsanbieter zulassen).
• Der externen Identität muss die Berechtigung erteilt werden, die Identität eines Dienstkontos anzunehmen.

Befolgen Sie die detaillierten Anweisungen zum Konfigurieren der Workload-Identitätsföderation von einem OIDC-Identitätsanbieter.

Nachdem Sie den OIDC-Anbieter so konfiguriert haben, dass er sich als Dienstkonto ausgibt, muss eine Konfigurationsdatei für Anmeldeinformationen generiert werden. Im Gegensatz zu Dienstkonto-Anmeldeinformationsdateien enthält die generierte Anmeldeinformationskonfigurationsdatei nicht vertrauliche Metadaten, um die Bibliothek anzuweisen, wie sie externe Betreff-Tokens abruft und sie gegen Dienstkonto-Zugriffstokens austauscht. Die Konfigurationsdatei kann mithilfe der gcloud-CLI generiert werden.

Für OIDC-Anbieter kann die Auth-Bibliothek OIDC-Tokens entweder von einem lokalen Dateispeicherort (Anmeldeinformationen aus Dateiquellen) oder von einem lokalen Server (Anmeldeinformationen aus URL-Quellen) abrufen.

Dateibasierte Anmeldeinformationen Für dateibasierte Anmeldeinformationen muss ein Hintergrundprozess den Dateispeicherort vor Ablauf kontinuierlich mit einem neuen OIDC-Token aktualisieren. Bei Token mit einer Lebensdauer von einer Stunde muss das Token stündlich in der Datei aktualisiert werden. Der Token kann direkt als Klartext oder im JSON-Format gespeichert werden.

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/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID 
    --service-account $SERVICE_ACCOUNT_EMAIL 
    --credential-source-file $PATH_TO_OIDC_ID_TOKEN 
    # 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

Wobei die folgenden Variablen ersetzt werden müssen:

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

Dadurch wird die Konfigurationsdatei in der angegebenen Ausgabedatei generiert.

URL-basierte Anmeldeinformationen Für URL-basierte Anmeldeinformationen muss ein lokaler Server einen GET-Endpunkt hosten, um das OIDC-Token zurückzugeben. Die Antwort kann im Klartext oder JSON erfolgen. Zusätzliche erforderliche Anforderungsheader können ebenfalls angegeben werden.

Führen Sie den folgenden Befehl aus, um eine URL-basierte OIDC-Workload-Identitätskonfiguration zu generieren:

 # Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config 
    projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID 
    --service-account $SERVICE_ACCOUNT_EMAIL 
    --credential-source-url $URL_TO_GET_OIDC_TOKEN 
    --credential-source-headers $HEADER_KEY = $HEADER_VALUE 
    # 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

Wobei die folgenden Variablen ersetzt werden müssen:

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

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

Verwenden von Anmeldeinformationen aus ausführbaren Dateien mit OIDC und SAML

Ausführbare Anmeldeinformationen Bei ausführbaren Anmeldeinformationen wird eine lokale ausführbare Datei zum Abrufen des Drittanbieter-Tokens verwendet. Die ausführbare Datei muss die Bereitstellung eines gültigen, nicht abgelaufenen OIDC-ID-Tokens oder einer SAML-Assertion im JSON-Format an stdout verarbeiten.

Um aus ausführbaren Dateien stammende Anmeldeinformationen zu verwenden, muss die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1 gesetzt sein.

Führen Sie den folgenden Befehl aus, um eine aus einer ausführbaren Datei stammende Workload-Identitätskonfiguration zu generieren:

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

Wobei die folgenden Variablen ersetzt werden müssen:

• $PROJECT_NUMBER : Die Google Cloud-Projektnummer.
• $POOL_ID : Die Workload-Identity-Pool-ID.
• $PROVIDER_ID : Die OIDC- oder SAML-Anbieter-ID.
• $SERVICE_ACCOUNT_EMAIL : Die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
• $SUBJECT_TOKEN_TYPE : Der Subjekt-Token-Typ.
• $EXECUTABLE_COMMAND : Der vollständige auszuführende Befehl, einschließlich Argumenten. Muss ein absoluter Pfad zum Programm sein.

Das Flag --executable-timeout-millis ist optional. Dies ist die Dauer in Millisekunden, die die Authentifizierungsbibliothek auf den Abschluss der ausführbaren Datei wartet. Der Standardwert beträgt 30 Sekunden, wenn nicht angegeben. Der maximal zulässige Wert beträgt 2 Minuten. Das Minimum beträgt 5 Sekunden.

Das Flag --executable-output-file ist optional. Falls angegeben, muss der Dateipfad auf die von der ausführbaren Datei generierte 3PI-Anmeldeinformationsantwort verweisen. Dies ist nützlich, um die Anmeldeinformationen zwischenzuspeichern. Durch Angabe dieses Pfads prüfen die Auth-Bibliotheken zunächst seine Existenz, bevor sie die ausführbare Datei ausführen. Durch das Zwischenspeichern der ausführbaren JSON-Antwort auf diese Datei wird die Leistung verbessert, da vermieden wird, dass die ausführbare Datei ausgeführt werden muss, bis die zwischengespeicherten Anmeldeinformationen in der Ausgabedatei abgelaufen sind. Die ausführbare Datei muss das Schreiben in diese Datei übernehmen – die Authentifizierungsbibliotheken versuchen nur, von diesem Speicherort aus zu lesen. Das Format des Inhalts in der Datei sollte dem JSON-Format entsprechen, das von der unten gezeigten ausführbaren Datei erwartet wird.

Um das Drittanbieter-Token abzurufen, ruft die Bibliothek die ausführbare Datei mit dem angegebenen Befehl auf. Die Ausgabe der ausführbaren Datei muss dem unten angegebenen Antwortformat entsprechen. Die Antwort muss auf stdout ausgegeben werden.

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
}

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
}

Eine beispielhafte ausführbare Fehlerantwort:

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

Dies sind alles Pflichtfelder für eine Fehlerantwort. Die Code- und Nachrichtenfelder werden von der Bibliothek als Teil der ausgelösten Ausnahme verwendet.

Für erfolgreiche Antworten ist das Feld expiration_time nur erforderlich, wenn in der Anmeldeinformationskonfiguration eine Ausgabedatei angegeben ist.

Zusammenfassung der Antwortformatfelder:

• version : Die Version der JSON-Ausgabe. Derzeit wird nur Version 1 unterstützt.
• success : Wenn „true“, muss die Antwort das Drittanbieter-Token und den Token-Typ enthalten. Die Antwort muss auch das Feld expiration_time enthalten, wenn in der Anmeldeinformationskonfiguration eine Ausgabedatei angegeben wurde. Die ausführbare Datei muss außerdem 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 : Der Subjekt-Token-Typ des Drittanbieters. 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 eines Drittanbieters.
• saml_response : Die SAML-Antwort des Drittanbieters.
• expiration_time : Die Ablaufzeit des Drittanbieter-Subject-Tokens in Sekunden (Unix-Epochenzeit).
• code : Die Fehlercodezeichenfolge.
• message : Die Fehlermeldung.

Alle Antworttypen müssen sowohl das version als auch success enthalten.

• Erfolgreiche Antworten müssen token_type und entweder id_token oder saml_response enthalten. Das Feld expiration_time muss auch vorhanden sein, wenn in der Anmeldeinformationskonfiguration eine Ausgabedatei angegeben wurde.
• Fehlerantworten müssen sowohl das code als auch das message enthalten.

Die Bibliothek füllt die folgenden Umgebungsvariablen, wenn die ausführbare Datei ausgeführt wird:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE : Das Zielgruppenfeld aus der Anmeldeinformationskonfiguration. Immer präsent.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : Dieser erwartete Subjekt-Token-Typ. Immer präsent.
• GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL : Die E-Mail-Adresse des Dienstkontos. Nur vorhanden, wenn ein Dienstkontoidentitätswechsel verwendet wird.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : Der Speicherort der Ausgabedatei aus der Anmeldeinformationskonfiguration. Nur vorhanden, wenn in der Anmeldeinformationskonfiguration angegeben.

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

Sicherheitsüberlegungen

Die folgenden Sicherheitspraktiken werden dringend empfohlen:

• Der Zugriff auf das Skript sollte eingeschränkt werden, da es Anmeldeinformationen für stdout anzeigt. Dadurch wird sichergestellt, dass unerwünschte Prozesse keinen Zugriff auf das Skript erhalten.
• Die Konfigurationsdatei sollte nicht änderbar sein. Der Schreibzugriff sollte eingeschränkt werden, um zu verhindern, dass Prozesse den ausführbaren Befehlsteil ändern.

Angesichts der Komplexität der Verwendung von Anmeldeinformationen aus ausführbaren Dateien wird empfohlen, die vorhandenen unterstützten Mechanismen (Datei-/URL-Quelle) für die Bereitstellung von Anmeldeinformationen Dritter zu verwenden, es sei denn, diese erfüllen nicht Ihre spezifischen Anforderungen.

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

Verwendung eines benutzerdefinierten Lieferanten mit OIDC und SAML

Beim Erstellen von IdentityPoolCredentials kann eine benutzerdefinierte Implementierung von IdentityPoolSubjectTokenSupplier verwendet werden, um ein Betreff-Token bereitzustellen, das gegen ein GCP-Zugriffstoken ausgetauscht werden kann. Der Lieferant muss einen gültigen, nicht abgelaufenen Betreff-Token zurückgeben, wenn er von den GCP-Anmeldeinformationen aufgerufen wird.

IdentityPoolCredentials speichert das zurückgegebene Token nicht zwischen, daher sollte die Caching-Logik im Token-Anbieter implementiert werden, um mehrere Anforderungen für dasselbe Subjekt-Token zu verhindern.

 import java . io . IOException ;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @ Override
  public String getSubjectToken ( ExternalAccountSupplierContext context ) throws IOException {
    // Any call to the supplier will pass 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 do not 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 GCP audience.
        . setSubjectTokenType ( SubjectTokenTypes . JWT ) // Sets the subject token type.
        . build ();

Wo sich die Zielgruppe befindet: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID

Wobei die folgenden Variablen ersetzt werden müssen:

• $PROJECT_NUMBER : Die Google Cloud-Projektnummer.
• $WORKLOAD_POOL_ID : Die Workload-Identity-Pool-ID.
• $PROVIDER_ID : Die Anbieter-ID.

Die Werte für die Zielgruppe, die Dienstkonto-Identitätswechsel-URL und jedes andere Builder-Feld können auch durch Generieren einer Anmeldeinformationskonfigurationsdatei mit der gcloud-CLI ermittelt werden.

Verwendung eines benutzerdefinierten Lieferanten mit AWS

Bei der Initialisierung von AwsCredentials kann eine benutzerdefinierte Implementierung von AwsSecurityCredentialsSupplier bereitgestellt werden. Sofern bereitgestellt, überlässt die AwsCredentials-Instanz dem Lieferanten den Abruf von AWS-Sicherheitsanmeldeinformationen zum Austausch gegen ein GCP-Zugriffstoken. Der Lieferant muss gültige, nicht abgelaufene AWS-Sicherheitsanmeldeinformationen zurückgeben, wenn er von den GCP-Anmeldeinformationen aufgerufen wird.

AwsCredentials speichert die zurückgegebenen AWS-Sicherheitsanmeldeinformationen oder die Region nicht im Cache. Daher sollte die Caching-Logik im Lieferanten implementiert werden, um mehrere Anfragen für dieselben Ressourcen zu verhindern.

 class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @ Override
  AwsSecurityCredentials getAwsSecurityCredentials ( ExternalAccountSupplierContext context ) throws IOException {
    // Any call to the supplier will pass 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 do not 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 do not 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 GCP audience.
    . setAwsSecurityCredentialsSupplier ( supplier ) // Sets the supplier.
    . build ();

Wo sich die Zielgruppe befindet: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID

Wobei die folgenden Variablen ersetzt werden müssen:

• $PROJECT_NUMBER : Die Google Cloud-Projektnummer.
• $WORKLOAD_POOL_ID : Die Workload-Identity-Pool-ID.
• $PROVIDER_ID : Die Anbieter-ID.

Die Werte für die Zielgruppe, die Dienstkonto-Identitätswechsel-URL und jedes andere Builder-Feld können auch durch Generieren einer Anmeldeinformationskonfigurationsdatei mit der gcloud-CLI ermittelt werden.

Konfigurierbare Token-Lebensdauer

Wenn Sie eine Anmeldeinformationskonfiguration mit Workload Identity-Föderation mithilfe von Dienstkontoidentitätswechsel erstellen, können Sie ein optionales Argument angeben, um die Lebensdauer des Dienstkonto-Zugriffstokens zu konfigurieren.

Um die Konfiguration mit konfigurierbarer Token-Lebensdauer zu generieren, führen Sie den folgenden Befehl aus (in diesem Beispiel wird eine AWS-Konfiguration verwendet, aber die Token-Lebensdauer kann für alle Workload Identity Federation-Anbieter konfiguriert werden):

 # Generate an AWS configuration file with configurable token lifetime.
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 
    --service-account-token-lifetime-seconds $TOKEN_LIFETIME

Wobei die folgenden Variablen ersetzt werden müssen:

• $PROJECT_NUMBER : Die Google Cloud-Projektnummer.
• $POOL_ID : Die Workload-Identity-Pool-ID.
• $AWS_PROVIDER_ID : Die AWS-Anbieter-ID.
• $SERVICE_ACCOUNT_EMAIL : Die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen werden soll.
• $TOKEN_LIFETIME : Die gewünschte Lebensdauer des Dienstkonto-Zugriffstokens in Sekunden.

Das Flag service-account-token-lifetime-seconds ist optional. Wenn nicht angegeben, beträgt der Standardwert eine Stunde. Der minimal zulässige Wert beträgt 600 (10 Minuten) und der maximal zulässige Wert beträgt 43200 (12 Stunden). Wenn eine Lebensdauer von mehr als einer Stunde erforderlich ist, muss das Dienstkonto als zulässiger Wert in einer Organisationsrichtlinie hinzugefügt werden, die die Einschränkung constraints/iam.allowServiceAccountCredentialLifetimeExtension erzwingt.

Beachten Sie, dass die Konfiguration einer kurzen Lebensdauer (z. B. 10 Minuten) dazu führt, dass die Bibliothek alle 10 Minuten den gesamten Token-Austauschfluss initiiert, wodurch der Drittanbieter-Token-Anbieter aufgerufen wird, auch wenn der Drittanbieter-Token nicht abgelaufen ist.

Workforce Identity Federation

Mit der Workforce Identity Federation können Sie einen externen Identitätsanbieter (IdP) verwenden, um eine Belegschaft – eine Gruppe von Benutzern, z. B. Mitarbeiter, Partner und Auftragnehmer – mithilfe von IAM zu authentifizieren und zu autorisieren, damit die Benutzer auf Google Cloud-Dienste zugreifen können. Workforce Identity Federation erweitert die Identitätsfunktionen von Google Cloud, um synchronisierungsloses, attributbasiertes Single Sign-On zu unterstützen.

Mit Workforce Identity Federation können Ihre Mitarbeiter über einen externen Identitätsanbieter (IdP), der OpenID Connect (OIDC) oder SAML 2.0 unterstützt, wie Azure Active Directory (Azure AD), Active Directory Federation Services (AD FS) oder Okta, auf Google Cloud-Ressourcen zugreifen , und andere.

Zugriff auf Ressourcen über einen OIDC- oder SAML 2.0-Identitätsanbieter

Um über einen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud-Ressourcen zuzugreifen, sind die folgenden Anforderungen erforderlich:

• Es muss ein Workforce-Identity-Pool erstellt werden.
• Dem Workforce-Pool muss ein OIDC- oder SAML 2.0-Identitätsanbieter hinzugefügt werden.

Befolgen Sie die detaillierten Anweisungen zum Konfigurieren der Workforce Identity Federation.

Nach der Konfiguration eines OIDC- oder SAML 2.0-Anbieters muss eine Konfigurationsdatei für Anmeldeinformationen generiert werden. Die generierte Anmeldeinformationskonfigurationsdatei enthält nicht vertrauliche Metadaten, um die Bibliothek anzuweisen, wie sie externe Betreff-Tokens abruft und sie gegen GCP-Zugriffstokens austauscht. Die Konfigurationsdatei kann mithilfe der gcloud-CLI generiert werden.

Die Auth-Bibliothek kann externe Betreff-Tokens von einem lokalen Dateispeicherort (Anmeldeinformationen aus Dateiquellen), von einem lokalen Server (Anmeldeinformationen aus URL-Quellen) oder durch Aufrufen einer ausführbaren Datei (Anmeldeinformationen aus ausführbaren Dateien) abrufen.

Dateibasierte Anmeldeinformationen Für dateibasierte Anmeldeinformationen muss ein Hintergrundprozess den Dateispeicherort vor Ablauf kontinuierlich mit einem neuen Betreff-Token aktualisieren. Bei Token mit einer Lebensdauer von einer Stunde muss das Token stündlich in der Datei aktualisiert werden. Der Token kann direkt als Klartext oder im JSON-Format gespeichert werden.

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 workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token 
    --credential-source-file= $PATH_TO_OIDC_ID_TOKEN 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    # 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

Wobei die folgenden Variablen ersetzt werden müssen:

• $WORKFORCE_POOL_ID : Die Workforce-Pool-ID.
• $PROVIDER_ID : Die Anbieter-ID.
• $PATH_TO_OIDC_ID_TOKEN : Der Dateipfad, der zum Abrufen des OIDC-Tokens verwendet wird.
• $WORKFORCE_POOL_USER_PROJECT : Die Projektnummer, die dem Workforce-Pool-Benutzerprojekt zugeordnet ist.

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

 # Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --credential-source-file= $PATH_TO_SAML_ASSERTION 
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    --output-file=/path/to/generated/config.json 

Wobei die folgenden Variablen ersetzt werden müssen:

• $WORKFORCE_POOL_ID : Die Workforce-Pool-ID.
• $PROVIDER_ID : Die Anbieter-ID.
• $PATH_TO_SAML_ASSERTION : Der Dateipfad, der zum Abrufen der Base64-codierten SAML-Assertion verwendet wird.
• $WORKFORCE_POOL_USER_PROJECT : Die Projektnummer, die dem Workforce-Pool-Benutzerprojekt zugeordnet ist.

Diese Befehle generieren die Konfigurationsdatei in der angegebenen Ausgabedatei.

URL-basierte Anmeldeinformationen Für URL-basierte Anmeldeinformationen muss ein lokaler Server einen GET-Endpunkt hosten, um das OIDC-Token zurückzugeben. Die Antwort kann im Klartext oder JSON erfolgen. Zusätzliche erforderliche Anforderungsheader können ebenfalls angegeben werden.

Führen Sie den folgenden Befehl aus, um eine URL-basierte OIDC-Workforce-Identitätskonfiguration zu generieren:

 # Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token 
    --credential-source-url= $URL_TO_RETURN_OIDC_ID_TOKEN 
    --credential-source-headers $HEADER_KEY = $HEADER_VALUE 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    --output-file=/path/to/generated/config.json

Wobei die folgenden Variablen ersetzt werden müssen:

• $WORKFORCE_POOL_ID : Die Workforce-Pool-ID.
• $PROVIDER_ID : Die Anbieter-ID.
• $URL_TO_RETURN_OIDC_ID_TOKEN : Die URL des lokalen Serverendpunkts.
• $HEADER_KEY und $HEADER_VALUE : Die zusätzlichen Header-Schlüssel/Wert-Paare zur Weitergabe der GET-Anfrage an $URL_TO_GET_OIDC_TOKEN , z. B. Metadata-Flavor=Google .
• $WORKFORCE_POOL_USER_PROJECT : Die Projektnummer, die dem Workforce-Pool-Benutzerprojekt zugeordnet ist.

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

 # Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 
    --credential-source-url= $URL_TO_GET_SAML_ASSERTION 
    --credential-source-headers