ID-Token abrufen

Auf dieser Seite werden einige Möglichkeiten zum Abrufen eines von Google signierten OIDC-ID-Tokens (OpenID Connect) beschrieben. Für die folgenden Authentifizierungsanwendungsfälle benötigen Sie ein von Google signiertes ID-Token:

Informationen zu Inhalt und Lebensdauer von ID-Tokens finden Sie unter ID-Tokens.

ID-Tokens haben einen bestimmten Dienst oder eine bestimmte Anwendung, für den sie verwendet werden können. Dies wird durch den Wert ihrer aud-Anforderung angegeben. Auf dieser Seite wird der Begriff Zieldienst verwendet, um sich auf den Dienst oder die Anwendung zu beziehen, mit dem das ID-Token authentifiziert werden kann.

Wenn Sie das ID-Token abrufen, können Sie es in einen Authorization-Header in der Anfrage an den Zieldienst einfügen.

Methoden zum Abrufen eines ID-Tokens

Es gibt verschiedene Möglichkeiten, ein ID-Token abzurufen. Auf dieser Seite werden die folgenden Methoden beschrieben:

Cloud Run und Cloud Functions bieten dienstspezifische Möglichkeiten zum Abrufen eines ID-Tokens. Weitere Informationen finden Sie unter Bei Anwendungen authentifizieren, die in Cloud Run oder Cloud Functions gehostet werden.

Wenn Sie ein ID-Token für eine Anwendung benötigen, die nicht in Google Cloud gehostet wird, können Sie diese Methoden wahrscheinlich verwenden. Sie sollten jedoch feststellen, welche ID-Token-Anforderungen die Anwendung erfordert.

ID-Token vom Metadatenserver abrufen

Wenn Ihr Code auf einer Ressource ausgeführt wird, der ein Dienstkonto angehängt sein kann, kann der Metadatenserver für den zugehörigen Dienst in der Regel ein ID-Token angeben. Der Metadatenserver generiert ID-Tokens für das angehängte Dienstkonto. Sie können kein ID-Token basierend auf Nutzeranmeldedaten vom Metadatenserver abrufen.

Sie können ein ID-Token vom Metadatenserver abrufen, wenn Ihr Code in den folgenden Google Cloud-Diensten ausgeführt wird:

Um ein ID-Token vom Metadatenserver abzurufen, fragen Sie den Identitätsendpunkt für das Dienstkonto ab, wie in diesem Beispiel gezeigt.

curl

Ersetzen Sie AUDIENCE durch den URI für den Zieldienst, z. B. http://www.example.com.

curl -H "Metadata-Flavor: Google" \
  'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE'

PowerShell

Ersetzen Sie AUDIENCE durch den URI für den Zieldienst, z. B. http://www.example.com.

$value = (Invoke-RestMethod `
  -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE")
$value

Java

Sie müssen die Google API-Clientbibliothek für Java installieren, um dieses Codebeispiel auszuführen.


import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.IdTokenCredentials;
import com.google.auth.oauth2.IdTokenProvider;
import com.google.auth.oauth2.IdTokenProvider.Option;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Arrays;

public class IdTokenFromMetadataServer {

  public static void main(String[] args) throws IOException, GeneralSecurityException {
    // TODO(Developer): Replace the below variables before running the code.

    // The url or target audience to obtain the ID token for.
    String url = "https://example.com";

    getIdTokenFromMetadataServer(url);
  }

  // Use the Google Cloud metadata server to create an identity token and add it to the
  // HTTP request as part of an Authorization header.
  public static void getIdTokenFromMetadataServer(String url) throws IOException {
    // Construct the GoogleCredentials object which obtains the default configuration from your
    // working environment.
    GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

    IdTokenCredentials idTokenCredentials =
        IdTokenCredentials.newBuilder()
            .setIdTokenProvider((IdTokenProvider) googleCredentials)
            .setTargetAudience(url)
            // Setting the ID token options.
            .setOptions(Arrays.asList(Option.FORMAT_FULL, Option.LICENSES_TRUE))
            .build();

    // Get the ID token.
    // Once you've obtained the ID token, you can use it to make an authenticated call to the
    // target audience.
    String idToken = idTokenCredentials.refreshAccessToken().getTokenValue();
    System.out.println("Generated ID token.");
  }
}

Einfach loslegen (Go)

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	"google.golang.org/api/idtoken"
	"google.golang.org/api/option"
)

// getIdTokenFromMetadataServer uses the Google Cloud metadata server environment
// to create an identity token and add it to the HTTP request as part of an Authorization header.
func getIdTokenFromMetadataServer(w io.Writer, url string) error {
	// url := "http://www.example.com"

	ctx := context.Background()

	// Construct the GoogleCredentials object which obtains the default configuration from your
	// working environment.
	credentials, err := google.FindDefaultCredentials(ctx)
	if err != nil {
		return fmt.Errorf("failed to generate default credentials: %w", err)
	}

	ts, err := idtoken.NewTokenSource(ctx, url, option.WithCredentials(credentials))
	if err != nil {
		return fmt.Errorf("failed to create NewTokenSource: %w", err)
	}

	// Get the ID token.
	// Once you've obtained the ID token, you can use it to make an authenticated call
	// to the target audience.
	_, err = ts.Token()
	if err != nil {
		return fmt.Errorf("failed to receive token: %w", err)
	}
	fmt.Fprintf(w, "Generated ID token.\n")

	return nil
}

Node.js

/**
 * TODO(developer):
 *  1. Uncomment and replace these variables before running the sample.
 */
// const targetAudience = 'http://www.example.com';

const {GoogleAuth} = require('google-auth-library');

async function getIdTokenFromMetadataServer() {
  const googleAuth = new GoogleAuth();

  const client = await googleAuth.getIdTokenClient(targetAudience);

  // Get the ID token.
  // Once you've obtained the ID token, you can use it to make an authenticated call
  // to the target audience.
  await client.idTokenProvider.fetchIdToken(targetAudience);
  console.log('Generated ID token.');
}

getIdTokenFromMetadataServer();

Python

Zum Ausführen dieses Codebeispiels müssen Sie die Google-Authentifizierungs-Python-Bibliothek installieren.


import google
import google.oauth2.credentials
from google.auth import compute_engine
import google.auth.transport.requests

def idtoken_from_metadata_server(url: str):
    """
    Use the Google Cloud metadata server in the Cloud Run (or AppEngine or Kubernetes etc.,)
    environment to create an identity token and add it to the HTTP request as part of an
    Authorization header.

    Args:
        url: The url or target audience to obtain the ID token for.
            Examples: http://www.example.com
    """

    request = google.auth.transport.requests.Request()
    # Set the target audience.
    # Setting "use_metadata_identity_endpoint" to "True" will make the request use the default application
    # credentials. Optionally, you can also specify a specific service account to use by mentioning
    # the service_account_email.
    credentials = compute_engine.IDTokenCredentials(
        request=request, target_audience=url, use_metadata_identity_endpoint=True
    )

    # Get the ID token.
    # Once you've obtained the ID token, use it to make an authenticated call
    # to the target audience.
    credentials.refresh(request)
    # print(credentials.token)
    print("Generated ID token.")

Ruby

Sie müssen die Google-Authentifizierungsbibliothek für Ruby installieren, um dieses Codebeispiel auszuführen.

require "googleauth"

##
# Uses the Google Cloud metadata server environment to create an identity token
# and add it to the HTTP request as part of an Authorization header.
#
# @param url [String] The url or target audience to obtain the ID token for
#   (e.g. "http://www.example.com")
#
def auth_cloud_idtoken_metadata_server url:
  # Create the GCECredentials client.
  id_client = Google::Auth::GCECredentials.new target_audience: url

  # Get the ID token.
  # Once you've obtained the ID token, you can use it to make an authenticated call
  # to the target audience.
  id_client.fetch_access_token
  puts "Generated ID token."

  id_client.refresh!
end

Verbindungsdienst zum Generieren eines ID-Tokens verwenden

Einige Google Cloud-Dienste unterstützen Sie beim Aufrufen anderer Dienste. Diese Verbindungsdienste können helfen, den Zeitpunkt des Aufrufs zu bestimmen, oder einen Workflow verwalten, der den Aufruf des Dienstes umfasst. Die folgenden Dienste können automatisch ein ID-Token mit dem entsprechenden Wert für die aud-Anforderung enthalten, wenn sie einen Aufruf eines Dienstes initiieren, der ein ID-Token erfordert:

Cloud Scheduler
Cloud Scheduler ist ein vollständig verwalteter Cronjob-Planer für Unternehmen. Sie können Cloud Scheduler so konfigurieren, dass er entweder ein ID-Token oder ein Zugriffstoken enthält, wenn er einen anderen Dienst aufruft. Weitere Informationen finden Sie unter Authentifizierung mit HTTP-Zielen verwenden.
Cloud Tasks
Mit Cloud Tasks können Sie die Ausführung verteilter Aufgaben verwalten. Sie können eine Aufgabe so konfigurieren, dass sie entweder ein ID-Token oder ein Zugriffstoken enthält, wenn sie einen Dienst aufruft. Weitere Informationen finden Sie unter HTTP-Zielaufgaben mit Authentifizierungstokens verwenden.
Pub/Sub
Pub/Sub ermöglicht die asynchrone Kommunikation zwischen Diensten. Sie können Pub/Sub so konfigurieren, dass ein ID-Token mit einer Nachricht hinzugefügt wird. Weitere Informationen finden Sie unter Authentifizierung für Push-Abos.
Workflows
Workflows ist eine vollständig verwaltete Orchestrierungsplattform, die Dienste in einer von Ihnen definierten Reihenfolge ausführt: ein Workflow. Sie können einen Workflow definieren, um entweder ein ID-Token oder ein Zugriffstoken aufzunehmen, wenn er einen anderen Dienst aufruft. Weitere Informationen finden Sie unter Authentifizierte Anfragen von einem Workflow aus ausführen.

ID-Token durch Übernahme der Identität eines Dienstkontos generieren

Die Identitätsübertragung für ein Dienstkonto ermöglicht es einem Hauptkonto, kurzlebige Anmeldedaten für ein vertrauenswürdiges Dienstkonto zu generieren. Das Hauptkonto kann diese Anmeldedaten dann zur Authentifizierung als Dienstkonto verwenden.

Bevor ein Hauptkonto die Identität eines Dienstkontos übernehmen kann, muss es für dieses Dienstkonto eine IAM-Rolle haben, die die Identitätsübertragung aktiviert. Wenn das Hauptkonto selbst ein anderes Dienstkonto ist, scheint es einfacher, die erforderlichen Berechtigungen direkt für dieses Dienstkonto bereitzustellen und eine Identitätsübernahme zu ermöglichen. Diese Konfiguration, die als Selbstidentität bezeichnet wird, erstellt eine Sicherheitslücke, da das Dienstkonto ein Zugriffstoken erstellen kann, das unbefristet aktualisiert werden kann.

Die Identitätsübertragung für ein Dienstkonto sollte immer zwei Hauptkonten umfassen: ein Hauptkonto, das den Aufrufer darstellt, und das Dienstkonto, dessen Identität imitiert wird. Dieses Konto wird als das privilegierte Dienstkonto bezeichnet, das die Berechtigung übernimmt.

Gehen Sie so vor, um ein ID-Token durch Übernahme der Identität eines Dienstkontos zu generieren.

Eine detaillierte Anleitung finden Sie unter ID-Token erstellen.

  1. Ermitteln oder erstellen Sie ein Dienstkonto, das das Dienstkonto ist, das Berechtigungen verwendet. Gewähren Sie diesem Dienstkonto die erforderliche IAM-Rolle für den Zieldienst:

    • Gewähren Sie für Cloud Run-Dienste die Rolle "Cloud Run Invoker" (roles/run.invoker).
    • Gewähren Sie für Cloud Functions die Rolle "Cloud Functions-Invoker" (roles/cloudfunctions.invoker).
    • Informationen zu anderen Zieldiensten finden Sie in der Produktdokumentation für den Dienst.
  2. Identifizieren Sie das Hauptkonto, das die ldentitätsübertragung durchführt, und richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein, um die Anmeldedaten für dieses Hauptkonto zu verwenden.

    In Entwicklungsumgebungen ist das Hauptkonto in der Regel das Nutzerkonto, das Sie mithilfe der gcloud-Befehlszeile für ADC bereitgestellt haben. Wenn Sie jedoch eine Ressource mit einem angehängten Dienstkonto ausführen, ist das angehängte Dienstkonto das Hauptkonto.

  3. Gewähren Sie dem Hauptkonto die Rolle OpenID Connect-Identitätsersteller für das Dienstkonto (roles/iam.serviceAccountOpenIdTokenCreator).

  4. Generieren Sie mithilfe der IAM Credentials API das ID-Token für das autorisierte Dienstkonto.

Generisches ID-Token für die Entwicklung mit Cloud Run und Cloud Functions generieren

Sie können die gcloud CLI verwenden, um ein ID-Token für Ihre Nutzeranmeldedaten zu erhalten, das mit jedem Cloud Run-Dienst oder jeder Cloud Functions-Funktion verwendet werden kann, für deren Aufruf der Aufrufer über die erforderlichen IAM-Berechtigungen verfügt. Dieses Token funktioniert nicht für andere Anwendungen.

ID-Token mit einem externen Identitätsanbieter generieren

Das Generieren eines ID-Tokens mithilfe eines externen Identitätsanbieters verwendet die Workload Identity-Föderation, mit der Sie eine Beziehung zwischen Google Cloud und Ihrem externen Identitätsanbieter einrichten können. Sie können dann mit den Anmeldedaten Ihres externen Identitätsanbieters ID-Tokens oder Zugriffstokens generieren, die in Google Cloud verwendet werden können.

So generieren Sie ein ID-Token für von einem externen Identitätsanbieter bereitgestellte Anmeldedaten:

  1. Identifizieren oder erstellen Sie ein Dienstkonto, um die erforderlichen IAM-Rollen für den Aufruf des Zieldienstes bereitzustellen.

    Es hat sich bewährt, ein Dienstkonto speziell für diesen Zweck zu erstellen und ihm nur die erforderliche Rolle zuzuweisen. Dieser Ansatz folgt dem Prinzip der geringsten Berechtigung.

  2. Ermitteln Sie die erforderlichen Rollen, um den Zieldienst aufzurufen. Weisen Sie dem Dienstkonto für den Zieldienst diese Rollen zu:

    • Gewähren Sie für Cloud Run-Dienste die Rolle "Cloud Run Invoker" (roles/run.invoker).
    • Gewähren Sie für Cloud Functions die Rolle "Cloud Functions-Invoker" (roles/cloudfunctions.invoker).
    • Informationen zu anderen Zieldiensten finden Sie in der Produktdokumentation für den Dienst.
  3. Konfigurieren Sie die Workload Identity-Föderation für Ihren Identitätsanbieter, wie unter Workload Identity-Föderation konfigurieren beschrieben.

  4. Folgen Sie der Anleitung unter Externe Identitäten die Berechtigung erteilen, die Identität eines Dienstkontos zu übernehmen. Verwenden Sie dazu das Dienstkonto, das Sie in den vorherigen Schritten eingerichtet haben, als das Dienstkonto, dessen Identität angenommen wird.

  5. Verwenden Sie die REST API, um ein kurzlebiges Token abzurufen. Für den letzten Schritt verwenden Sie stattdessen die Methode generateIdToken. So rufen Sie ein ID-Token ab:

    Bash

    ID_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken \
        -H "Content-Type: text/json; charset=utf-8" \
        -H "Authorization: Bearer $STS_TOKEN" \
        -d @- <<EOF | jq -r .token
        {
            "audience": "AUDIENCE"
        }
    EOF
    )
    echo $ID_TOKEN
    

    PowerShell

    $IdToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken" `
        -Headers @{ "Authorization" = "Bearer $StsToken" } `
        -ContentType "application/json" `
        -Body (@{
            "audience" = "AUDIENCE"
        } | ConvertTo-Json)).token
    Write-Host $IdToken
    

    Dabei gilt:

    • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.
    • AUDIENCE: die Zielgruppe für das Token, z. B. die Anwendung oder der Dienst, auf die das Token zugegriffen wird

Nächste Schritte