Über einen OIDC-Identitätsanbieter auf Ressourcen zugreifen

In diesem Dokument erfahren Sie, wie Sie mithilfe von Identitätsföderation über einen Identitätsanbieter, der OpenID Connect (OIDC) unterstützt, auf Google Cloud-Ressourcen zugreifen.

In der Vergangenheit haben Anwendungen, die außerhalb von Google Cloud ausgeführt werden, Dienstkontoschlüssel für den Zugriff auf Google Cloud-Ressourcen verwendet. Mithilfe der Identitätsföderation können Sie zulassen, dass eine externe Identität die Identität eines Dienstkontos übernehmen kann. Dadurch kann Ihre Arbeitslast direkt mit einem kurzlebigen Zugriffstoken auf Google Cloud-Ressourcen zugreifen und der mit Dienstkontoschlüsseln verbundene Wartungs- und Sicherheitsaufwand entfällt.

Hinweis

  1. Sie benötigen die Rolle "Workload Identity Pool Administrator" (roles/iam.workloadIdentityPoolAdmin).

    Die einfachen IAM-Rollen "Inhaber" (roles/owner) und "Bearbeiter" (roles/editor) gewähren auch die Berechtigung zum Konfigurieren der Identitätsföderation. Wir empfehlen jedoch, die Rolle "Workload Identity Pool Administrator" zu verwenden, um keinen unnötigen Zugriff auf Google Cloud-Ressourcen zu gewähren.

  2. Erstellen Sie ein Google Cloud-Dienstkonto.

  3. Gewähren Sie dem Dienstkonto Zugriff, um die für Ihre Arbeitslast erforderlichen Google Cloud APIs aufzurufen.

Workload Identity-Pool erstellen

Ein Workload Identity-Pool ist ein Container für eine Sammlung externer Identitäten. Workload Identity-Pools sind voneinander isoliert, ein einzelner Pool kann jedoch eine beliebige Anzahl von Dienstkonten imitieren. Im Allgemeinen empfehlen wir, für jede Umgebung einen neuen Pool zu erstellen, z. B. für Entwicklung, Staging oder Produktion.

Sie müssen eine ID angeben, um einen neuen Workload Identity-Pool zu erstellen. Sie können auch eine optionale Beschreibung und einen Anzeigenamen angeben.

gcloud

Führen Sie den Befehl gcloud beta iam workload-identity-pools create aus, um einen Workload Identity-Pool zu erstellen:

gcloud beta iam workload-identity-pools create pool-id \
    --location="global" \
    --description="description" \
    --display-name="display-name"

REST API

Mit der Methode projects.locations.workloadIdentityPools.create wird ein Workload Identity-Pool erstellt.

HTTP-Methode und URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

JSON-Text anfordern:

{
  "description": "description",
  "display-name": "display-name"
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

 

OIDC-Identitätsanbieter hinzufügen

Zum Konfigurieren eines OIDC-Identitätsanbieters für den Workload Identity-Pool sollten Sie mindestens Folgendes angeben:

  • Eine ID für den Anbieter.

  • Die Workload Identity-Pool-ID aus dem vorherigen Abschnitt in diesem Dokument.

  • Den Aussteller-URI des Anbieters. Dieser hat normalerweise das Format https://example.com. Informationen zum Ermitteln des URI finden Sie in der Dokumentation Ihres Anbieters zur OIDC-Einbindung.

  • Eine Liste von Attributzuordnungen, die die Anforderungen in einem externen Token den Attributen in einem Google-Token zuordnen. Verwenden Sie assertion, um auf die externen Anmeldedaten zu verweisen, google für Google-Attribute und attribute für benutzerdefinierte Attribute.

    Es gibt zwei Google-Attribute: google.subject und google.groups. Sie können in IAM-Bindungen auf diese Attribute verweisen. google.subject wird auch in Cloud Logging-Logeinträgen angezeigt.

    Sie müssen eine Zuordnung für google.subject bereitstellen. Im Allgemeinen empfehlen wir die Zuordnung zu assertion.sub. Damit erhalten Sie eine stabile Kennung zur Verwendung in IAM-Bindungen. Die Zuordnung sieht so aus:

    google.subject=assertion.sub
    

    Für komplexere Assertions können Sie die Common Expression Language verwenden. Wenn Ihr Workload Identity-Pool beispielsweise mehrere Identitätsanbieter enthält, können Sie ein Präfix anhängen, um zwischen diesen zu unterscheiden:

    google.subject="provider-a::" + assertion.sub
    

    Das Feld google.subject darf höchstens 127 Zeichen enthalten.

    Sie können auch benutzerdefinierte Attribute angeben. Im Folgenden wird zum Beispiel assertion.foo zu attribute.bar zugeordnet:

    attribute.bar=assertion.foo
    

    Eine vollständige Liste der Anforderungen, auf die Sie verweisen können, finden Sie in der Dokumentation Ihres Anbieters zu Zugriffstoken

    Wenn Sie auf einen bestimmten Teil eine Anforderung in einem Ausdruck verweisen möchten, verwenden Sie die CEL-Funktion extract(), die einen Wert aus einer Anforderung anhand einer von Ihnen bereitgestellten Vorlage extrahiert. Weitere Informationen zu extract() finden Sie unter Werte aus Attributen extrahieren.

    Verwenden Sie die Funktion has(), um zu prüfen, ob Anmeldedaten eine Anforderung enthalten.

  • Eine Liste der zulässigen Zielgruppen, die angeben, welche Werte das Feld aud für die externen Anmeldedaten enthalten kann. Sie können maximal zehn Zielgruppen mit jeweils bis zu 256 Zeichen konfigurieren. Informationen zu den Standardwerten für aud finden Sie in der Dokumentation Ihres Anbieters.

    Wenn Ihr Identitätsanbieter das Konfigurieren eines benutzerdefinierten Werts für aud zulässt, können Sie den Parameter für die zulässigen Zielgruppen auch leer lassen und den Wert von aud auf den vollständigen Ressourcennamen Ihres Workload Identity-Anbieters festlegen. Das HTTP-Präfix ist optional. Beispiel:

    //iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
    https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
    

    In beiden Fällen werden alle Tokenaustauschanfragen abgelehnt, die keinen der zulässigen Werte enthalten.

Sie können auch mehrere optionale Parameter angeben:

  • Einen Anzeigenamen und eine Beschreibung.

  • Eine Attributbedingung zum Angeben von Attributen, die das Hauptkonto enthalten muss. Die Bedingung kann für Anforderungen in den externen Anmeldedaten oder Attribute in den Google-Anmeldedaten gelten. Alle Anfragen, die die Bedingung nicht erfüllen, werden abgelehnt.

    Attributbedingungen werden als CEL-Ausdruck formatiert, der einen booleschen Wert zurückgibt. Der folgende Ausdruck lehnt beispielsweise Anfragen von Identitäten ab, die nicht Mitglied einer bestimmten Gruppe sind:

    group in assertion.groups
    

    Die Verwendung von Attributbedingungen wird dringend empfohlen, wenn der Identitätsanbieter öffentlich verfügbar ist. Weitere Informationen zu gängigen Anwendungsfällen für Attributbedingungen finden Sie in der Übersicht zur Workload Identity-Föderation.

Das folgende Beispiel zeigt, wie Sie einen Identitätsanbieter hinzufügen:

gcloud

Führen Sie den Befehl gcloud beta iam workload-identity-pools providers create-oidc aus, um einen Identitätsanbieter hinzuzufügen:

gcloud beta iam workload-identity-pools providers create-oidc provider-id \
    --workload-identity-pool="pool-id" \
    --issuer-uri="issuer-uri" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

REST API

Mit der Methode projects.locations.workloadIdentityPools.providers.create wird ein OIDC-Identitätsanbieter hinzugefügt.

HTTP-Methode und URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

JSON-Text anfordern:

{
  "issuerUrl": "issuer-uri"
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

 

Identität eines Dienstkontos übernehmen

Sie können Workload Identity-Pools und Identitäten, die von ihren Anbietern föderiert werden, Rollen auf Ressourcen mit IAM zuweisen. Die Workload Identity-Nutzerrolle (roles/iam.workloadIdentityUser) gewährt die Berechtigung, die Identität eines Dienstkontos zu übernehmen. Dadurch können externe Identitäten auf Google Cloud-Ressourcen zugreifen.

Verwenden Sie den Wert, den Sie google.subject zugeordnet haben, um diese Bindung für eine bestimmte Identität hinzuzufügen:

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"

So fügen Sie diese Bindung für alle Mitglieder einer Gruppe hinzu:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principalSet://iam.googleapis.com/project/project-number/workloadIdentityPools/pool-id/groups/group-name"

Sie können den Zugriff auch basierend auf benutzerdefinierten Attributen gewähren. Beispiel:

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.custom-attribute-name/custom-attribute-value"

Wenn Sie den Zugriff widerrufen möchten, ersetzen Sie add-iam-policy-binding durch remove-iam-policy-binding.

Außerdem können Sie über die REST API oder Clientbibliotheken Bindungen hinzufügen oder widerrufen. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.

Externes Token gegen Google-Token austauschen

Sobald Ihre externe Identität die Identität eines Dienstkontos übernehmen kann, können Sie deren Anmeldedaten gegen Google-Anmeldedaten austauschen.

So tauschen Sie Anmeldedaten aus:

  1. Fordern Sie ein OIDC-ID-Token von Ihrem Identitätsanbieter an. Eine ausführliche Anleitung finden Sie in der Dokumentation Ihres Identitätsanbieters.

  2. Übergeben Sie das OIDC-ID-Token an die Methode token() des Security Token Service, um ein föderiertes Zugriffstoken abzurufen:

    REST API

    Mit der Methode token wird das Token eines Drittanbieters gegen ein Google-Token ausgetauscht.

    Ersetzen Sie diese Werte in den folgenden Anweisungen:

    • project-number: Ihre Google Cloud-Projektnummer.
    • pool-id: Die ID des Workload Identity-Pools, den Sie zuvor in dieser Anleitung erstellt haben.
    • provider-id: Die ID des Identitätsanbieters, den Sie zuvor in dieser Anleitung konfiguriert haben.

    HTTP-Methode und URL:

    POST https://sts.googleapis.com/v1beta/token

    JSON-Text anfordern:

    {
      "audience": "https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id",
      "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
      "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
      "scope": "https://www.googleapis.com/auth/cloud-platform",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "subject_token": "oidc-id-token"
    }
    

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

     

    Die Methode gibt ein föderiertes Token zurück.

  3. Tauschen Sie mit generateAccessToken() das föderierte Token gegen ein OAuth 2.0-Zugriffstoken aus:

    REST API

    Die Methode serviceAccounts.generateAccessToken der Service Account Credentials API generiert ein OAuth 2.0-Zugriffstoken für ein Dienstkonto.

    Ersetzen Sie diese Werte in den folgenden Anweisungen:

    • project-id: Ihre Google Cloud-Projekt-ID.
    • sa-id: Die ID Ihres Dienstkontos. Dies kann entweder die E-Mail-Adresse des Dienstkontos im Format sa-name@project-id.iam.gserviceaccount.com oder die eindeutige numerische ID des Dienstkontos sein.
    • token: Das föderierte Zugriffstoken.

    HTTP-Methode und URL:

    POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com:generateAccessToken

    JSON-Text anfordern:

    {
      "scope": [
        "https://www.googleapis.com/auth/cloud-platform"
      ]
    }
    

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Wenn die Anfrage generateAccessToken erfolgreich war, enthält der Antworttext ein OAuth 2.0-Zugriffstoken und eine Ablaufzeit. Das accessToken kann dann verwendet werden, um eine Anfrage im Namen des Dienstkontos zu authentifizieren, bis die expireTime erreicht wurde:

    {
      "accessToken": "eyJ0eXAi...NiJ9",
      "expireTime": "2020-04-07T15:01:23.045123456Z"
    }
    

Sobald Sie ein Zugriffstoken für ein Dienstkonto haben, können Sie damit Google Cloud APIs aufrufen. Dazu nehmen Sie das Token in den Header Authorization Ihrer Anfrage auf:

Authorization: Bearer service-account-access-token

Die Anfrage ist als Dienstkonto autorisiert.

Nächste Schritte