Workload Identity-Föderation mit X.509-Zertifikaten konfigurieren

In diesem Leitfaden wird beschrieben, wie Sie die Workload Identity-Föderation mit X.509-Zertifikaten verwenden, die von Ihrer Zertifizierungsstelle (Certificate Authority, CA) ausgestellt wurden, um sich bei Trusted Cloud zu authentifizieren und auf Trusted Cloud Ressourcen zuzugreifen.

Wenn Ihre Arbeitslasten ein mTLS-Clientzertifikat haben, können Sie sich beiTrusted Cloud authentifizieren, indem Sie eine oder mehrere Zertifizierungsstellen bei der Workload Identity-Föderation als Vertrauensanker registrieren. Sie können auch Zwischenzertifizierungsstellen registrieren.

Durch die Verwendung der Workload Identity-Föderation können diese Arbeitslasten kurzlebige Trusted Cloud Anmeldedaten über eine gegenseitige TLS-Verbindung (mTLS) abrufen. Arbeitslasten können mit diesen kurzlebigen Anmeldedaten aufTrusted Cloud APIs zugreifen.

Konzepte

Die auf X.509-Zertifikaten basierenden Verbundkonzepte umfassen Folgendes:

• Ein Vertrauensanker ist ein CA-Zertifikat, das als Vertrauensbasis gilt. Alle Clientzertifikatsketten sollten mit einem der Trust-Anker verkettet sein.

• Eine CA-Zwischenzertifizierungsstelle ist ein optionales Zertifizierungsstellenzertifikat, das zum Erstellen der Clientzertifikatskette verwendet wird.

• Ein Trust Store enthält die Trust-Anchor-Zertifikate und Zwischen-CA-Zertifikate, die zum Validieren der Clientzertifikatskette verwendet werden. Eine CA stellt vertrauenswürdige Zertifikate für den Client aus.

  Sie können die folgenden Arten von Clientzertifikaten in den Trust Store hochladen:

  • Zertifikate, die von Drittanbieter-Zertifizierungsstellen Ihrer Wahl ausgestellt wurden
  • Von Ihren privaten Zertifizierungsstellen ausgestellte Zertifikate
  • Signierte Zertifikate, wie unter Selbst signierte Zertifikate erstellen beschrieben

Hinweise

So konfigurieren Sie die Workload Identity-Föderation:

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

Wir empfehlen, ein dediziertes Projekt zur Verwaltung von Workload Identity-Pools und -Anbietern.

2. Verify that billing is enabled for your Trusted Cloud project.

3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

   Enable the APIs

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren der Workload Identity-Föderation benötigen:

• Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Alternativ enthält die einfache Rolle „IAM-Inhaber“ (roles/owner) auch Berechtigungen zum Konfigurieren der Identitätsföderation. In einer Produktionsumgebung sollten Sie keine einfachen Rollen zuweisen, Sie können sie aber in einer Entwicklungs- oder Testumgebung gewähren.

Truststore erstellen

In diesem Abschnitt wird beschrieben, wie Sie einen Truststore erstellen. Auf übergeordneter Ebene sind folgende Schritte erforderlich:

• Selbstsignierte Zertifikate generieren
• Zertifikate formatieren
• Vertrauensspeicher erstellen

Selbst signierte Zertifikate generieren

In diesem Abschnitt wird beschrieben, wie Sie Schlüssel generieren und signierte Zertifikate erstellen. Wenn Sie bereits Zertifikate erstellt haben, können Sie diesen Abschnitt überspringen und mit Zertifikate formatieren fortfahren.

In diesem Abschnitt werden openssl-Befehle verwendet, um Root- und Zwischenzertifikate zu erstellen.

So generieren Sie ein Root-Zertifikat und ein signiertes Zwischenzertifikat mit gültigen Feldern keyUsage und extendedKeyUsage:

1. Erstellen Sie eine openssl-Konfigurationsdatei, um Ihre Signaturzertifikate zu erstellen. Die Datei sieht mindestens so aus wie unten. Sie können aber bei Bedarf zusätzliche Felder festlegen.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command-line argument.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   [leaf_exts]
   keyUsage=critical,Digital Signature, Key Encipherment
   basicConstraints=critical, CA:FALSE
   EOF
   

2. Erstellen Sie das Root-Zertifikat.

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. Erstellen Sie die Signierungsanfrage für das Zwischenzertifikat.

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. Erstellen Sie das Zwischenzertifikat.

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

5. Erstellen Sie die Signierungsanfrage für das Leaf-Zertifikat.

   openssl req -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=example' \
       -config example.cnf \
       -extensions leaf_exts \
       -keyout leaf.key -out leaf.req
   

6. Erstellen Sie das vom Zwischenzertifikat ausgestellte Leaf-Zertifikat.

   openssl x509 -req \
       -CAkey int.key -CA int.cert \
       -set_serial 1 -days 3650 \
       -extfile example.cnf \
       -extensions leaf_exts \
       -in leaf.req -out leaf.cert
   

Zertifikate formatieren

Wenn Sie neue oder vorhandene Zertifikate in einen Trust Store aufnehmen möchten, formatieren Sie die Zertifikate als einzeiligen String und speichern Sie sie in Umgebungsvariablen. Die Zertifikate müssen im PEM-Format vorliegen. So formatieren Sie die Zertifikate und speichern sie in Umgebungsvariablen:

1. Speichern Sie das Root-Zertifikat als einzeiligen String.

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. Speichern Sie ein Zwischenzertifikat als einzeiligen String.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

Truststore erstellen

In diesem Abschnitt erstellen Sie einen Truststore mit einer YAML-formatierten Datei, die Ihre Trust-Anker und Zwischenzertifizierungsstellen enthält.

Diese Datei enthält den Zertifikatsinhalt aus den Umgebungsvariablen, die Sie unter Zertifikate formatieren erstellt haben. Wenn Sie weitere Vertrauensanker hinzufügen möchten, fügen Sie unter trustStore weitere trustAnchors-Einträge hinzu. Wenn Sie zusätzliche Zwischen-CA-Zertifikate hinzufügen möchten, fügen Sie unter trustStore zusätzliche intermediateCas-Einträge hinzu.

Führen Sie den folgenden Befehl aus, um die Trust Store-Datei zu erstellen:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Attributzuordnung und -bedingung definieren

Das X.509-Clientzertifikat kann mehrere Attribute enthalten. Sie müssen auswählen, welches Attribut Sie als Subjekt-ID verwenden möchten, indem Sie google.subject in Trusted Cloud dem Attribut aus Ihrem Zertifikat zuordnen. Wenn das Attribut im Zertifikat beispielsweise der allgemeine Name des Subjekts ist, sieht die Zuordnung so aus: google.subject=assertion.subject.dn.cn

Optional können Sie zusätzliche Attribute zuordnen. Sie können dann auf diese Attribute verweisen, wenn Sie Zugriff auf Ressourcen gewähren.

Ihre Attributzuordnungen können die Attribute im Clientzertifikat verwenden, darunter:

• serialNumberHex: die Seriennummer
• subject.dn.cn: der allgemeine Name des Subjekts
• subject.dn.o: der Name der betroffenen Organisation
• subject.dn.ou: die letzte Organisationseinheit des Subjekts
• issuer.dn.cn: der allgemeine Name des Ausstellers
• issuer.dn.o: der Name der ausstellenden Organisation
• issuer.dn.ou: die letzte Organisationseinheit des Ausstellers
• san.dns: der erste DNS-Name des alternativen Antragstellernamens
• san.uri: Der erste URI des alternativen Subjektnamens
• sha256Fingerprint: SHA256-Hash des Blattzertifikats (Base64)

Sie müssen eines dieser Attribute google.subject zuordnen, um das Subjekt eindeutig zu identifizieren. Wählen Sie zum Schutz vor Spoofing-Bedrohungen ein Attribut mit einem eindeutigen Wert aus, der nicht geändert werden kann. Standardmäßig ist die google.subject-Kennung auf den allgemeinen Subjektnamen des Clientzertifikats, assertion.subject.dn.cn, festgelegt.

Optional können Sie eine Attributbedingung definieren. Attributbedingungen sind CEL-Ausdrücke, die Assertion-Attribute und Zielattribute prüfen können. Wenn die Attributbedingung bei bestimmten Anmeldedaten als true ausgewertet wird, werden die Anmeldedaten akzeptiert. Andernfalls werden die Anmeldedaten abgelehnt.

Mit einer Attributbedingung können Sie einschränken, welche Identitäten die Workload Identity-Föderation verwenden können, um kurzlebige Trusted CloudTokens abzurufen.

Die folgende Bedingung beschränkt beispielsweise den Zugriff auf Clientzertifikate, die die SPIFFE-ID spiffe://example/path enthalten:

assertion.san.uri=="spiffe://example/path"

Identitätsföderation von Arbeitslasten konfigurieren

In diesem Abschnitt wird gezeigt, wie Sie einen Workload Identity-Pool und einen Workload Identity-Poolanbieter konfigurieren. Sie müssen diese Schritte nur einmal für jeden Truststore ausführen. Sie können dann denselben Workload Identity-Pool und -Anbieter für mehrere Arbeitslasten und mehrere Trusted Cloud -Projekte verwenden.

Workload Identity-Pool erstellen

1. Führen Sie folgenden Befehl aus, um einen neuen Workload Identity-Pool zu erstellen:

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Ersetzen Sie Folgendes:

   • POOL_ID: die eindeutige ID des Pools.
   • DISPLAY_NAME: der Name des Pools.
   • DESCRIPTION: eine Beschreibung des von Ihnen gewählten Pools. Diese Beschreibung wird angezeigt, wenn Sie Zugriff auf Poolidentitäten gewähren.

Workload Identity-Poolanbieter erstellen

1. Führen Sie den folgenden Befehl aus, um einen X.509-Workload Identity-Poolanbieter hinzuzufügen:

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Ersetzen Sie Folgendes:

   • PROVIDER_ID: eine eindeutige Anbieter-ID für Workload Identity-Pool Ihrer Wahl.
   • POOL_ID: die ID des Workload Identity-Pools, die Sie zuvor erstellt haben.
   • TRUST_STORE_CONFIG: Die YAML-Datei des Trust Stores.
   • MAPPINGS: eine durch Kommas getrennte Liste der Attributzuordnungen, die Sie zuvor in dieser Anleitung erstellt haben. Beispiel: google.subject=assertion.subject.dn.cn
   • CONDITIONS: Optional. Eine Attributbedingung, die Sie zuvor in dieser Anleitung erstellt haben. Entfernen Sie den Parameter, wenn keine Attributbedingung vorliegt.

Arbeitslast authentifizieren

Sie müssen diese Schritte einmal für jede Arbeitslast ausführen.

Externer Arbeitslast den Zugriff auf Trusted Cloud -Ressourcen erlauben

Damit Ihre Arbeitslast auf Trusted Cloud -Ressourcen zugreifen kann, empfehlen wir, dem Hauptkonto direkten Ressourcenzugriff zu gewähren. In diesem Fall ist das Hauptkonto der föderierte Nutzer. Für einige Trusted Cloud Produkte gelten Einschränkungen für Google Cloud APIs. Wenn Ihre Arbeitslast einen API-Endpunkt aufruft, der eingeschränkt ist, können Sie stattdessen die Identitätsübernahme des Dienstkontos verwenden. In diesem Fall ist das Hauptkonto dasTrusted Cloud -Dienstkonto, das als Identität fungiert. Sie gewähren dem Dienstkonto Zugriff auf die Ressource.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Anmeldedaten-Konfiguration herunterladen oder erstellen

Die Cloud-Clientbibliotheken und die gcloud CLI können automatisch externe Anmeldedaten abrufen und mit diesen die Identität eines Dienstkontos übernehmen. Damit Bibliotheken und Tools diesen Vorgang abschließen können, müssen Sie eine Konfigurationsdatei für Anmeldedaten angeben. Diese Datei enthält die folgenden Informationen:

• Wo externe Anmeldedaten abgerufen werden
• Welcher Workload Identity-Pool und -Anbieter verwendet werden
• Welches Dienstkonto übernommen wird

Für die X.509-Zertifikatsföderation ist außerdem eine Zertifikatskonfigurationsdatei erforderlich. Diese Datei enthält Pfade zu den X.509-Clientzertifikats- und privaten Schlüsseldateien.

Erstellen Sie Konfigurationsdateien für Anmeldedaten und Zertifikate, mit denen die Bibliothek Zugriffstokens mithilfe von X.509-Zertifikaten abrufen kann.

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Anmeldedatenkonfiguration für den Zugriff auf Trusted Cloudverwenden

Gehen Sie so vor, damit Ihre Anmeldedatenkonfiguration von Tools und Clientbibliotheken verwendet werden kann. Weitere Informationen zu Standardanmeldedaten für Anwendungen finden Sie unter Funktionsweise von Standardanmeldedaten für Anwendungen.

1. Initialisieren Sie eine Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS und legen Sie sie auf die Konfigurationsdatei für Anmeldedaten fest:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   Ersetzen Sie FILEPATH durch den relativen Pfad zur Konfigurationsdatei für Anmeldedaten.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   Ersetzen Sie FILEPATH durch den relativen Pfad zur Konfigurationsdatei für Anmeldedaten.

2. Prüfen Sie, ob die Clientbibliothek die Zertifikatskonfigurationsdatei finden kann. Die Zertifikatskonfigurationsdatei befindet sich an einem der folgenden Pfade:

   • Der Standardpfad für die gcloud CLI:

     • Linux und macOS: ~/.config/gcloud/certificate_config.json

     • Windows: %APPDATA%\gcloud\certificate_config.json

   • Der in der Umgebungsvariable GOOGLE_API_CERTIFICATE_CONFIG festgelegte Pfad.

3. Verwenden Sie die folgenden Cloud-Clientbibliotheken, die die Workload Identity-Föderation mit X.509-Zertifikaten unterstützen.

   Go

   Clientbibliotheken für Go unterstützen die X.509-Identitätsföderation von Arbeitslasten, wenn sie Version 0.16.0 oder höher des cloud.google.com/go/auth-Moduls und Version 0.189.0 des google.golang.org/api-Moduls verwenden.

   Führen Sie den folgenden Befehl im Verzeichnis mit der Datei „go.mod“ für Ihr Modul aus, um zu prüfen, welche Version dieser Module in Ihrer Clientbibliothek verwendet wird:

     go list -m cloud.google.com/go/auth
     go list -m cloud.google.com/api
   

   Python

   Clientbibliotheken für Python unterstützen die X.509-Identitätsföderation von Arbeitslasten, wenn sie Version 2.39.0 oder höher des google-auth-Pakets verwenden.

   Führen Sie den folgenden Befehl in der Umgebung aus, in der das Paket installiert ist, um zu ermitteln, welche Version dieses Pakets verwendet wird:

     pip show google-auth
   

   Wenn Sie eine Projekt-ID für den Authentifizierungsclient angeben, können Sie die Umgebungsvariable GOOGLE_CLOUD_PROJECT festlegen oder Sie gestatten dem Client, automatisch nach der Projekt-ID zu suchen. Damit automatisch nach der Projekt-ID gesucht werden kann, muss das Dienstkonto in der Konfigurationsdatei in Ihrem Projekt die Rolle „Sucher“ (roles/browser) oder eine Rolle mit entsprechenden Berechtigungen haben. Weitere Informationen finden Sie im Nutzerhandbuch für das Paket google-auth.

4. Wenn Ihre Arbeitslast unter macOS ausgeführt wird, legen Sie CLOUDSDK_PYTHON_SITEPACKAGES=1 fest, um die gcloud CLI so zu konfigurieren, dass Python-Bibliotheken außerhalb des Installationsverzeichnisses verwendet werden.

5. Führen Sie den folgenden Befehl aus, um sich mit der gcloud CLI zu authentifizieren:

   gcloud auth login --cred-file=FILEPATH.json
   

   Ersetzen Sie FILEPATH durch den Pfad zur Konfigurationsdatei für Anmeldedaten.

   Unterstützung für die X.509-Workload Identity-Föderation in der gcloud CLI ist in Version 519.0 und höher der gcloud CLI verfügbar.

Zugriffstoken mit einfacher Anfrage für den Zugriff auf Trusted Cloudabrufen

Vertrauenskette erstellen

In diesem Schritt wird beschrieben, wie Sie die Vertrauenskette erstellen. Sie übergeben die Vertrauenskette im Feld subject_token, wenn Sie den Security Token Service in einer einfachen Anfrage aufrufen.

Formatieren Sie die Zertifikate, die in der Kette enthalten sein müssen, als JSON-formatierte Liste gemäß RFC 7515. Das für den mTLS-Handshake verwendete Leaf-Zertifikat muss als erstes Element angegeben werden. Jedes Zertifikat im Bundle muss ein base64-codierter String sein.

1. Speichern Sie das Endzertifikat und das Zwischenzertifikat als base64-codierte Strings.

   export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)
   

   export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)
   

2. Erstellen Sie eine JSON-formatierte Liste von Strings, die als subject_token im Aufruf des Security Token Service übergeben werden kann (siehe weiter unten in diesem Dokument).

   export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
   

Zugriffstoken abrufen

So erhalten Sie das Zugriffstoken:

1. Führen Sie den Tokenaustausch mit mTLS und dem Clientzertifikat durch:

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.s3nsapis.fr/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
       "subject_token": "TRUST_CHAIN"
   }'
   

   Ersetzen Sie Folgendes:

   • CLIENT_CERT_KEY: Der private Schlüssel des Clientzertifikats.
   • CLIENT_CERT: das Clientzertifikat

   • WORKLOAD_IDENTITY_POOL_URI: die URL des Anbieters des Workload Identity-Pools im folgenden Format:

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

   • TRUST_CHAIN: Die Vertrauenskette, die zum Überprüfen des untergeordneten Zertifikats erforderlich ist, muss mindestens CLIENT_CERT als erstes Element enthalten. Wenn Sie der Anleitung im Abschnitt Zertifikate formatieren gefolgt sind, ersetzen Sie TRUST_CHAIN durch '"${TRUST_CHAIN}"'.

2. Verwenden Sie das im vorherigen Schritt generierte Bearer-Zugriffstoken, um aufTrusted Cloud -Ressourcen zuzugreifen, z. B.:

   curl -X GET 'https://storage.s3nsapis.fr/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

Limits

In der folgenden Tabelle sind die Limits aufgeführt.

Nächste Schritte

• Weitere Informationen zur Workload Identity-Föderation
• Best Practices für die Verwendung der Workload Identity-Föderation
• Workload Identity-Pools und -Anbieter verwalten