Workload Identity-Föderation mit Bereitstellungspipelines konfigurieren

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In diesem Leitfaden wird beschrieben, wie Sie mit Workload Identity-Föderation Bereitstellungspipelines bei Google Cloud authentifizieren.

Je nach verwendetem CI/CD-System haben Ihre Bereitstellungspipelines möglicherweise Zugriff auf umgebungsspezifische Anmeldedaten. Beispiele:

  • GitHub Actions-Workflows können ein GitHub-OIDC-Token abrufen, das den Workflow und sein Repository eindeutig identifiziert.
  • Terraform Cloud kann Ihrer Terraform-Konfiguration ein OIDC-Token bereitstellen, das den Arbeitsbereich und die Umgebung eindeutig identifiziert.

Mithilfe der Workload Identity-Föderation können Sie vermeiden, dass Dienstkontoschlüssel gespeichert und verwaltet werden müssen, und stattdessen Bereitstellungspipelines ihre umgebungsspezifischen Anmeldedaten für den Zugriff auf Google Cloud APIs verwenden lassen.

Externen IdP vorbereiten

GitHub Actions

Sie müssen keine Änderungen an der Konfiguration in Ihrem GitHub-Konto vornehmen.

Nachdem Sie einen Workload Identity-Pool so konfiguriert haben, dass er Ihrem GitHub-Repository vertraut, können Sie zulassen, dass Workflows in diesem Repository ihr GitHub-OIDC-Token verwenden, um kurzlebige Google Cloud-Anmeldedaten abzurufen.

Terraform Cloud

Sie müssen keine Änderungen an der Konfiguration in Ihrem Terraform Cloud-Konto vornehmen.

Nachdem Sie einen Workload Identity-Pool für die Vertrauensstellung von Terraform Cloud konfiguriert haben, können Sie die Identitätsföderation von Arbeitslasten für einzelne Arbeitsbereiche aktivieren.

Workload Identity-Föderation konfigurieren

Sie müssen diese Schritte für jede GitHub- oder Terraform Cloud-Organisation ausführen.

So konfigurieren Sie die Workload Identity-Föderation:

  1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  2. Es wird empfohlen, ein dediziertes Projekt zum Verwalten von Workload Identity-Pools und -Anbietern zu verwenden.
  3. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

  4. IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs aktivieren.

    Aktivieren Sie die APIs

Attributzuordnung und -bedingung definieren

Die umgebungsspezifischen Anmeldedaten Ihrer Bereitstellungspipeline enthalten mehrere Attribute. Sie müssen entscheiden, welches Attribut Sie in Google Cloud als Subjekt-ID (google.subject) verwenden möchten.

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

GitHub Actions

Ihre Attributzuordnungen können die im OIDC-Token eingebetteten Anforderungen als Quellattribute verwenden, darunter:

  • sub: Enthält den Repository-Namen und die Git-Referenz, z. B. repo:username/reponame:ref:refs/heads/master.
  • repository: Enthält den Namen des Inhabers und des Repositorys, z. B. username/reponame.
  • repository_owner: Enthält den Inhaber, der ein Nutzername oder der Name einer GitHub-Organisation sein kann.
  • ref: Enthält die Git-Referenz, z. B. refs/heads/main.

Mit der folgenden Attributzuordnung wird google.subject auf die Anforderung sub aus dem OIDC-Token von GitHub Actions festgelegt. Da die Anforderung sub sowohl den Repository-Namen als auch die Git-Referenz enthält, können Sie über diese Zuordnung den Zugriff nach Repository und Zweig steuern:

google.subject=assertion.sub

Die Steuerung des Zugriffs nach Repository und Zweig kann nützlich sein, wenn bestimmte Zweige (z. B. main) anderen Zugriff auf Ressourcen benötigen als andere Zweige (z. B. Feature-Zweige).

Wenn Sie den Zugriff nicht nach Zweigen unterscheiden möchten, können Sie die folgende Attributzuordnung verwenden, bei der google.subject auf die Anforderung repository festgelegt wird:

google.subject=assertion.repository

Terraform Cloud

Ihre Attributzuordnungen können die in das Terraform-Token von Terraform eingebetteten Anforderungen verwenden, einschließlich der folgenden:

  • terraform_organization_id: Enthält die eindeutige ID der Organisation, z. B. org-xxxxxxxxxxxxxxxx.
  • terraform_workspace_id: Enthält die eindeutige ID des Arbeitsbereichs, z. B. ws-xxxxxxxxxxxxxxxx.
  • terraform_workspace_name: Enthält den Anzeigenamen des Arbeitsbereichs.
  • sub: Enthält den Anzeigenamen der Organisation, des Arbeitsbereichs und der Phase, z. B. organization:example-org:workspace:example-workspace:run_phase:apply.

Mit der folgenden Attributzuordnung wird google.subject auf die Anforderung terraform_workspace_id aus dem Terraform Cloud-OIDC-Token festgelegt:

google.subject=assertion.terraform_workspace_id

Mit dieser Zuordnung können Sie den Zugriff auf Google Cloud-Ressourcen nach Arbeitsbereich steuern.

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.

GitHub Actions

Verwenden Sie die folgende Bedingung, um den Zugriff auf Tokens einzuschränken, die von Ihrer GitHub-Organisation ausgegeben werden:

assertion.repository_owner=='ORGANIZATION'

Ersetzen Sie dabei ORGANIZATION durch den Namen Ihrer GitHub-Organisation.

Erweitern Sie optional die Attributbedingung, um den Zugriff auf eine Teilmenge von Workflows oder Zweige zu beschränken. Die folgende Bedingung begrenzt beispielsweise den Zugriff auf Workflows, die den Git-Zweig main verwenden:

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

Terraform Cloud

Verwenden Sie die folgende Bedingung, um den Zugriff auf Tokens einzuschränken, die von Ihrer Terraform Cloud-Organisation ausgestellt werden:

assertion.terraform_organization_id=='ORGANIZATION_ID'

Ersetzen Sie ORGANIZATION_ID durch die eindeutige ID Ihrer Organisation, z. B. org-xxxxxxxxxxxxxxxx. Erweitern Sie optional die Attributbedingung, um den Zugriff auf eine Teilmenge von Workflows oder Zweige zu beschränken. Die folgende Bedingung begrenzt beispielsweise den Zugriff auf einen bestimmten Arbeitsbereich:

assertion.terraform_organization_id=='ORGANIZATION_ID' && terraform_workspace_id=='WORKSPACE_ID'

Workload Identity-Pool und -Anbieter erstellen

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-Pooladministrator (roles/iam.workloadIdentityPoolAdmin)
  • Dienstkontoadministrator (roles/iam.serviceAccountAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

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.

Sie haben jetzt alle Informationen erfasst, die Sie zum Erstellen eines Workload Identity-Pools und -Anbieters benötigen:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Neuer Arbeitslastanbieter und -Pool auf.

    Zum neuen Arbeitslastanbieter und -anbieterpool

  2. Geben Sie unter Identity-Pool erstellen Folgendes ein:

    • Name: ist der Name für den Pool. Der Name wird auch als Pool-ID verwendet. Sie können die Pool-ID später nicht ändern.
    • Beschreibung: Text, der den Zweck des Pools beschreibt.
  3. Klicken Sie auf Weiter.

  4. Konfigurieren Sie die Anbietereinstellungen:

    GitHub Actions

    • Anbieter auswählen: OpenID Connect (OIDC).
    • Name des Anbieters: Name des Anbieters. Der Name wird auch als Anbieter-ID verwendet. Sie können die Anbieter-ID später nicht mehr ändern.
    • Aussteller-URL: https://token.actions.githubusercontent.com/
    • Zielgruppen: Standardzielgruppe

    Terraform Cloud

    • Anbieter auswählen: OpenID Connect (OIDC).
    • Name des Anbieters: Name des Anbieters. Der Name wird auch als Anbieter-ID verwendet. Sie können die Anbieter-ID später nicht mehr ändern.
    • Aussteller-URL: https://app.terraform.io
    • Zielgruppen: Standardzielgruppe
  5. Klicken Sie auf Weiter.

  6. Fügen Sie unter Anbieterattribute konfigurieren die zuvor identifizierten Attributzuordnungen hinzu.

  7. Geben Sie unter Attributbedingungen die zuvor identifizierte Attributbedingung ein. Lassen Sie das Feld leer, wenn Sie keine Attributbedingung haben.

  8. Klicken Sie auf Speichern, um den Workload Identity-Pool und -Poolanbieter zu erstellen.

gcloud

  1. Erstellen Sie einen neuen Workload Identity-Pool:

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

    Ersetzen Sie die folgenden Werte:

    • POOL_ID: die eindeutige ID des Pools.
    • DISPLAY_NAME: der Name des Pools.
    • DESCRIPTION: die Beschreibung des Pools. Diese Beschreibung wird angezeigt, wenn Zugriff auf Poolidentitäten gewährt wird.
  2. Fügen Sie einen Workload Identity-Pool-Anbieter hinzu:

    GitHub Actions

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="https://token.actions.githubusercontent.com/" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    Ersetzen Sie die folgenden Werte:

    Terraform Cloud

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="https://app.terraform.io" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    Ersetzen Sie die folgenden Werte:

Bereitstellungspipeline authentifizieren

Sie müssen diese Schritte für jeden GitHub Actions-Workflow oder jeden Terraform Cloud-Arbeitsbereich ausführen.

Dienstkonto für die Bereitstellungspipeline erstellen

  1. IAM, Security Token Service, and Service Account Credentials APIs aktivieren.

    Aktivieren Sie die APIs

  2. Erstellen Sie ein Dienstkonto, das die Arbeitslast darstellt. Wir empfehlen, für jede Bereitstellungspipeline ein eigenes Dienstkonto zu verwenden.

    Das Dienstkonto muss sich nicht im selben Projekt wie der Workload Identity-Pool befinden.

  3. Gewähren Sie dem Dienstkonto Zugriff auf Ressourcen, auf die externe Identitäten zugreifen können sollen.

Der Bereitstellungspipeline erlauben, die Identität des Dienstkontos zu übernehmen

Damit externe Identitäten die Identität eines Dienstkontos übernehmen können, müssen Sie ihnen die Rolle "Workload Identity-Nutzer" (roles/iam.workloadIdentityUser) für das Dienstkonto zuweisen. Sie können die Rolle einer bestimmten externen Identität oder mehreren externen Identitäten zuweisen:

  • Schreiben Sie für eine bestimmte externe Identität eine Attributbedingung, die das Attribut google.subject prüft.
  • Schreiben Sie für eine Gruppe externer Identitäten eine Attributbedingung, die das Attribut google.groups oder ein benutzerdefiniertes Attribut attribute.NAME prüft.
  • Verwenden Sie für keine der externen Identitäten im Workload Identity-Pool eine Attributbedingung.

Console

So nutzen Sie die Google Cloud Console, um zuzulassen, dass externe Identitäten die Identität eines Dienstkontos übernehmen:

  1. Rufen Sie in der Google Cloud Console die Seite Workload Identity-Pools auf.

    Zu Workload Identity-Pools

  2. Suchen Sie den Workload Identity-Pool, den Sie aktualisieren möchten, und wählen Sie ihn aus.

  3. Klicken Sie auf Zugriff erlauben, um Zugriff auf den ausgewählten Workload Identity-Pool zu gewähren.

  4. Wählen Sie in der Liste Dienstkonto das Dienstkonto aus, das von den externen Identitäten übernommen werden soll.

  5. Führen Sie eine der folgenden Aktionen aus, um auszuwählen, welche Identitäten im Pool die Identität des Dienstkontos übernehmen können:

    • Damit nur bestimmte Identitäten des Workload Identity-Pools die Identität des Dienstkontos übernehmen können, wählen Sie Nur Identitäten, die dem Filter entsprechen aus.

      Wählen Sie in der Liste Attributname das Attribut aus, nach dem Sie filtern möchten.

      Geben Sie im Feld Attributwert den erwarteten Wert des Attributs ein. Wenn Sie beispielsweise eine Attributzuordnung google.subject=assertion.sub verwenden, legen Sie den Attributnamen auf subject und den Attributwert auf den Wert der sub-Anforderung in Tokens fest, die von Ihrem externen Identitätsanbieter ausgestellt wurden.

    • Damit alle externen Identitäten des Workload Identity-Pools die Identität des Dienstkontos übernehmen können, wählen Sie Alle Identitäten im Pool aus.

  6. Klicken Sie zum Speichern der Konfiguration auf Speichern und dann auf Schließen.

gcloud

So nutzen Sie die gcloud CLI, um externen Identitäten zu erlauben, die Identität eines Dienstkontos zu übernehmen:

  1. Führen Sie den folgenden Befehl aus, um die Projektnummer Ihres aktuellen Projekts abzurufen:

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. So weisen Sie externen Identitäten, die bestimmte Kriterien erfüllen, die Rolle „Workload Identity-Nutzer“ (roles/iam.workloadIdentityUser) zu:

    Nach Thema

    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"
    

    Nach Gruppe

    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"
    

    Nach Attribut

    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"
    

    Alle externen Identitäten

    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/*"
    

    Dabei gilt:

    • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.
    • PROJECT_NUMBER: die Projektnummer des Projekts, das den Workload Identity-Pool enthält
    • POOL_ID: die Pool-ID des Workload Identity-Pools
    • SUBJECT: der erwartete Wert für das Attribut, das Sie google.subject zugeordnet haben
    • GROUP: der erwartete Wert für das Attribut, das Sie google.groups zugeordnet haben
    • ATTRIBUTE_NAME: der Name eines benutzerdefinierten Attributs in Ihrer Attributzuordnung

Bereitstellungspipeline konfigurieren

Sie können die Workload Identity-Föderation in Ihrer Deployment-Pipeline jetzt verwenden.

GitHub Actions

Mit der Aktion google-github-actions/auth können Sie während der Workflowausführung automatisch eine Konfigurationsdatei für Anmeldedaten generieren. Clientbibliotheken und Tools wie terraform können diese Konfigurationsdatei für Anmeldedaten dann verwenden, um Google-Anmeldedaten automatisch zu erhalten.

Bearbeiten Sie Ihre YAML-Datei für GitHub Actions und fügen Sie Folgendes hinzu:

  • Erlauben Sie dem Job, ein GitHub-ID-Token durch Hinzufügen der folgenden Konfiguration abzurufen:

    permissions:
      id-token: write
      contents: read
    
  • Fügen Sie einen Schritt zum Erstellen einer Konfigurationsdatei für Anmeldedaten hinzu:

    - id: 'auth'
      name: 'Authenticate to Google Cloud'
      uses: 'google-github-actions/auth@v0'
      with:
        create_credentials_file: true
        workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
        service_account: 'SERVICE_ACCOUNT_EMAIL'
    

Ersetzen Sie die folgenden Werte:

  • PROJECT_NUMBER: die Projektnummer des Projekts, das den Workload Identity-Pool enthält
  • POOL_ID: die ID des Workload Identity-Pools
  • PROVIDER_ID: die ID des Workload Identity-Poolanbieters
  • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.

Beispiel:

jobs:
  build:
    # Allow the job to fetch a GitHub ID token
    permissions:
      id-token: write
      contents: read

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v0'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'

Weitere Informationen zur Verwendung der Aktion google-github-actions/auth finden Sie unter Identitätsföderation von Arbeitslasten einrichten.

Terraform Cloud

Konfigurieren Sie Ihren Arbeitsbereich so, dass Ihre Konfiguration ein Terraform-Cloud-OIDC-Token abrufen kann:

  1. Öffnen Sie in Terraform Cloud Ihren Arbeitsbereich und rufen Sie Variablen auf.

  2. Klicken Sie auf Variable hinzufügen und fügen Sie die folgende Variable hinzu:

    • Variablenkategorie: Umgebungsvariable
    • Key: TFC_WORKLOAD_IDENTITY_AUDIENCE
    • Wert:
      https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    Ersetzen Sie die folgenden Werte:

    • PROJECT_NUMBER: die Projektnummer des Projekts, das den Workload Identity-Pool enthält
    • POOL_ID: die ID des Workload Identity-Pools
    • PROVIDER_ID: die ID des Workload Identity-Poolanbieters
  3. Klicken Sie auf Variable speichern.

Aktualisieren Sie Ihre Terraform-Konfiguration so, dass ausführbare Anmeldedaten und ein Shell-Skript verwendet werden, um das OIDC-Token aus der Umgebungsvariable TFC_WORKLOAD_IDENTITY_AUDIENCE zu lesen, und verwenden Sie es für die Identitätsföderation von Arbeitslasten:

  1. Fügen Sie in Terraform Cloud in Ihrer Arbeitsbereichkonfiguration zwei zusätzliche Variablen hinzu:

    Variablenkategorie Schlüssel Wert
    Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS .google-cloud/workload-identity.json
    Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 1

    Diese Variablen weisen terraform und die Clientbibliotheken an, ausführbare Dateianmeldedaten und die in der Datei .google-cloud/workload-identity.json gespeicherte Konfiguration zu verwenden.

  2. Erstellen Sie in Ihrem Quellcode-Repository die Datei .google-cloud/workload-identity.json und kopieren Sie die folgende Konfiguration:

    {
      "type": "external_account",
      "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "token_url": "https://sts.googleapis.com/v1/token",
      "credential_source": {
        "executable": {
          "command": "/bin/bash .google-cloud/workload-token.sh",
          "timeout_millis": 5000
        }
      },
      "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken"
    }
    

    Ersetzen Sie die folgenden Werte:

    • PROJECT_NUMBER: die Projektnummer des Projekts, das den Workload Identity-Pool enthält
    • POOL_ID: die ID des Workload Identity-Pools
    • PROVIDER_ID: die ID des Workload Identity-Poolanbieters
    • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.

    Diese Konfiguration weist Clientbibliotheken an, ein Skript (.google-cloud/workload-token.sh) auszuführen, um ein Terraform Cloud-OIDC-Token abzurufen.

  3. Erstellen Sie in Ihrem Quellcode-Repository die weitere Datei .google-cloud/workload-token.sh und kopieren Sie das folgende Skript:

    #!/bin/sh
    if [ -z $TFC_WORKLOAD_IDENTITY_TOKEN ]
    then
        echo '{"version": 1, "success": false, "code": "missing-variable", "message": "TFC_WORKLOAD_IDENTITY_TOKEN not defined in workspace."}'
    else
        echo '{"version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "'"$TFC_WORKLOAD_IDENTITY_TOKEN"'"}'
    fi
    

    Dieses Skript liest das OIDC-Token von Terraform Cloud aus der Umgebungsvariable TFC_WORKLOAD_IDENTITY_TOKEN und gibt das Token in dem von den Clientbibliotheken erwarteten Format zurück.

  4. Prüfen Sie, ob Ihre Terraform-Konfiguration Version 4.48.0 oder höher des Google Cloud-Anbieters verwendet, und aktualisieren Sie sie bei Bedarf so:

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 4.48.0"
        }
      }
    }
    
  5. Senden Sie die Änderungen an Ihr Quellcode-Repository.

Nächste Schritte