Informationen zum Aufrufen authentifizierter Cloud Run-Funktionen

1. Einführung

Übersicht

Cloud Run Functions ist eine einfache Computing-Lösung für Entwickler zum Erstellen eigenständiger und zweckgebundener Funktionen, die über HTTPS ausgelöst werden können oder auf CloudEvents reagieren, ohne dass ein Server oder eine Laufzeitumgebung verwaltet werden muss. Weitere Informationen zu Cloud Run-Funktionen

Es gibt zwei Hauptansätze zur Steuerung von Aufrufen von Cloud Run-Funktionen: Identitätsbasierte Zugriffssteuerung und netzwerkbasierte Zugriffssteuerung. In diesem Codelab liegt der Schwerpunkt auf dem ersten Ansatz. Sie werden durch drei Szenarien zur Sicherung des identitätsbasierten Zugriffs zum Aufrufen einer Funktion geführt:

1. gcloud-Identitätstoken zum Aufrufen einer Funktion für lokale Entwicklungs- und Testzwecke verwenden
2. Dienstkonto bei der lokalen Entwicklung und dem lokalen Testen imitieren, um dieselben Anmeldedaten wie in der Produktion zu verwenden
3. Verwenden Sie Google-Clientbibliotheken, um die Authentifizierung bei Google Cloud APIs zu verwalten, z. B. wenn ein Dienst eine Funktion aufrufen muss.

Aufgaben in diesem Lab

• Authentifizierung für eine Cloud Run-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert ist
• Eine authentifizierte Funktion aus einer lokalen Entwicklungsumgebung aufrufen, indem Sie das Token für Ihre gcloud-Identität bereitstellen
• Dienstkonto erstellen und die entsprechende Rolle zum Aufrufen einer Funktion zuweisen
• So imitieren Sie einen Dienst aus einer lokalen Entwicklungsumgebung, der die entsprechenden Rollen für das Aufrufen einer Funktion hat

2. Einrichtung und Anforderungen

Voraussetzungen

• Sie sind in der Cloud Console angemeldet.
• Sie haben bereits eine HTTP-ausgelöste Cloud Run-Funktion bereitgestellt. Beispiel für den Schnellstart
• (optional) Für das dritte Szenario werden in diesem Codelab Node.js und npm als Beispiel verwendet. Sie können aber jede Laufzeit verwenden, die von den Google Auth-Clientbibliotheken unterstützt wird.

Cloud Shell aktivieren

1. Klicken Sie in der Cloud Console auf Cloud Shell aktivieren .

Wenn Sie Cloud Shell zum ersten Mal starten, wird ein Zwischenbildschirm mit einer Beschreibung angezeigt. Klicken Sie in diesem Fall auf Weiter.

Die Bereitstellung und Verbindung mit Cloud Shell sollte nur wenige Minuten dauern.

Auf dieser virtuellen Maschine sind alle erforderlichen Entwicklungstools installiert. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Die meisten, wenn nicht alle Aufgaben in diesem Codelab können mit einem Browser erledigt werden.

Sobald Sie mit Cloud Shell verbunden sind, sollten Sie sehen, dass Sie authentifiziert sind und das Projekt auf Ihre Projekt-ID festgelegt ist.

2. Führen Sie in Cloud Shell den folgenden Befehl aus, um zu prüfen, ob Sie authentifiziert sind:

gcloud auth list

Befehlsausgabe

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Hinweis:Das gcloud-Befehlszeilentool ist das leistungsstarke und einheitliche Befehlszeilentool in Google Cloud. Es ist in Cloud Shell vorinstalliert. Sie werden feststellen, dass die Tab-Vervollständigung unterstützt wird. Weitere Informationen finden Sie in der Übersicht zum gcloud-Befehlszeilentool.

3. Führen Sie in Cloud Shell den folgenden Befehl aus, um zu prüfen, ob der gcloud-Befehl Ihr Projekt kennt:

gcloud config list project

Befehlsausgabe

[core]
project = <PROJECT_ID>

Ist dies nicht der Fall, können Sie die Einstellung mit diesem Befehl vornehmen:

gcloud config set project <PROJECT_ID>

Befehlsausgabe

Updated property [core/project].

Hinweis: Wenn Sie diese Anleitung außerhalb von Cloud Shell durcharbeiten, folgen Sie der Anleitung unter Standardanmeldedaten für Anwendungen einrichten.

3. Authentifizierte Cloud Run-Funktion erstellen und testen

Eine Authentifizierung erfordert, dass das Prinzip, das die Funktion aufruft, die Rolle „Cloud Run Invoker“ haben muss. Andernfalls gibt die Funktion den Fehler „403 Forbidden“ zurück. In diesem Codelab erfahren Sie, wie Sie einem Prinzipal die entsprechenden Invoker-Rollen gewähren.

Lokale Umgebungsvariablen für vereinfachte gcloud-Befehle einrichten

Zuerst erstellen Sie einige Umgebungsvariablen, um die Lesbarkeit der gcloud-Befehle in diesem Codelab zu verbessern.

REGION=us-central1
PROJECT_ID=$(gcloud config get-value project)

Quellcode für die Funktion erstellen

In diesem Codelab wird Node.js verwendet. Sie können jedoch jede Laufzeit verwenden, die von den Google Auth-Clientbibliotheken unterstützt wird.

Erstellen Sie zunächst ein Verzeichnis und speichern Sie das Verzeichnis mit cd.

mkdir auth-function-codelab && cd $_

Erstellen Sie dann die Datei „package.json“.

touch package.json

echo '{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
' > package.json

Erstellen Sie als Nächstes die Quelldatei „index.js“.

touch index.js

echo 'const functions = require("@google-cloud/functions-framework");

functions.http("helloWorld", (req, res) => {
 res.send(`Hello ${req.query.name || req.body.name || "World"}!`);
});' > index.js

Authentifizierte Funktion erstellen

So erstellen Sie eine authentifizierte Funktion für die nodejs20-Laufzeit: Sie können jedoch jede Laufzeit verwenden, die von den Google Auth-Clientbibliotheken unterstützt wird.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

Führen Sie den folgenden Befehl aus, um eine Cloud Run-Funktion direkt in Cloud Run bereitzustellen:

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated

Sie können die Funktions-URL dann als Umgebungsvariable speichern, um sie später zu verwenden.

FUNCTION_URL="$(gcloud run services describe $FUNCTION_NAME --region $REGION --format 'value(status.url)')"

Wenn Sie die Bereitstellung als Cloud Functions (2. Generation) bevorzugen, verwenden Sie den folgenden Befehl:

gcloud functions deploy nodejs-http-function \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated

Sie können die Funktions-URL dann als Umgebungsvariable speichern, um sie später zu verwenden.

FUNCTION_URL="$(gcloud functions describe $FUNCTION_NAME --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

Prüfen Sie, ob für die Funktion eine Authentifizierung erforderlich ist, indem Sie versuchen, sie als anonymer Aufrufer aufzurufen.

Sie rufen die Funktion ohne Authentifizierung auf, um zu prüfen, ob der erwartete 403-Fehler auftritt.

Führen Sie in der Befehlszeile den folgenden curl-Befehl aus:

curl -i $FUNCTION_URL

Sie sehen Folgendes:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

Jetzt sind Sie bereit, drei Szenarien durchzugehen, in denen Sie Ihre Funktion durch Authentifizierung aufrufen können.

4. Szenario 1: gcloud-Identitätstoken verwenden

Als Entwickler möchten Sie Ihre Funktion während der lokalen Entwicklung testen. In diesem Abschnitt führen Sie einen kurzen Test durch, um zu prüfen, ob die Funktion mit Ihrer eigenen Identität ordnungsgemäß authentifiziert wurde.

Prüfen Sie, ob Sie mit gcloud authentifiziert sind. Führen Sie dazu den folgenden Befehl aus:

gcloud auth list

Neben der aktiven Identität sollte ein Sternchen angezeigt werden, z. B.:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Weitere Informationen zum Einrichten von gcloud init und gcloud auth login finden Sie in der Dokumentation.

Rufen Sie als Nächstes die Funktion auf und übergeben Sie ihr Ihr Identitätstoken.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

Jetzt sehen Sie das Ergebnis:

Hello World!

Fehlerbehebung

Wenn Sie den Fehler 403 „Forbidden“ (Nicht zulässig) erhalten, prüfen Sie, ob Ihrer Identität die Rolle „Cloud Run Invoker“ zugewiesen ist. In der IAM-Konsole können Sie die Rollen prüfen, die einem Hauptkonto zugewiesen wurden.

Obwohl die Verwendung Ihres eigenen Identitätstokens eine schnelle Möglichkeit ist, Ihre Funktion während der Entwicklung zu testen, benötigt der Aufrufer der authentifizierten Funktion die entsprechenden Rollen. Andernfalls erhält der Aufrufer den Fehler 403 Forbidden.

Folgen Sie dem Prinzip der geringsten Berechtigung, indem Sie die Anzahl der Identitäten und Dienstkonten begrenzen, die Rollen zum Aufrufen der Funktion haben. Im nächsten Szenario erfahren Sie, wie Sie ein neues Dienstkonto erstellen und ihm die entsprechenden Rollen zuweisen, um die Funktion aufzurufen.

5. Szenario 2: Identitätswechsel des Dienstkontos

In diesem Szenario nehmen Sie die Identität eines Dienstkontos an, d.h. Sie nehmen die Berechtigungen eines Dienstkontos an, um beim lokalen Entwickeln und Testen eine Funktion aufzurufen. Wenn Sie sich als Dienstkonto ausgeben, können Sie Ihre Funktion mit denselben Anmeldedaten wie in der Produktion testen.

So können Sie nicht nur Rollen überprüfen, sondern auch das Prinzip der geringsten Berechtigung einhalten, da Sie anderen Identitäten nicht nur zu lokalen Testzwecken die Rolle „Cloud Functions-Aufrufer“ zuweisen müssen.

Für dieses Codelab erstellen Sie ein neues Dienstkonto, das nur Rollen zum Aufrufen der in diesem Codelab erstellten Funktion hat.

Neues Dienstkonto erstellen

Zuerst erstellen Sie einige zusätzliche Umgebungsvariablen für die Dienstkonten, die in den gcloud-Befehlen verwendet werden.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

Als Nächstes erstellen Sie das Dienstkonto.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Run function Authentication codelab"

Gewähren Sie dem Dienstkonto die Rolle „Cloud Run-Aufrufer“:

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1  \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/run.invoker'

Funktion durch Identitätswechsel des Dienstkontos aufrufen

Zu diesem Zweck übernehmen Sie die Identität des neu erstellten Dienstkontos, indem Sie sein ID-Token abrufen.

Erforderliche Rollen für die Identitätsdiebstahl-Funktion hinzufügen

Wenn Sie die Identität eines Dienstkontos übernehmen möchten, muss Ihr Nutzerkonto die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) haben, um ein ID-Token für das Dienstkonto zu generieren.

Sie können die folgenden Befehle ausführen, um Ihrem aktiven Nutzerkonto diese Rolle zuzuweisen:

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

ID-Token des Dienstkontos verwenden

Warten Sie einige Minuten, bis die Berechtigungen übernommen wurden. Sie können die Funktion jetzt aufrufen, indem Sie das ID-Token des Dienstkontos übergeben.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)" 

Sie sehen Folgendes:

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].

Hello World!

6. Szenario 3: Google-Clientbibliotheken verwenden

In diesem letzten Teil des Codelabs führen Sie einen kleinen Dienst lokal aus, um ein ID-Token für ein Dienstkonto zu generieren, und rufen dann die Funktion mithilfe der Google Auth-Clientbibliotheken und der Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) programmatisch auf. Weitere Informationen zu Google-Clientbibliotheken finden Sie im Abschnitt „Erläuterung der Clientbibliotheken“ der Dokumentation.

Die Verwendung von ADC ist besonders wichtig, wenn Sie Ihre Funktion lokal schreiben und testen möchten (z. B. auf Ihrem Laptop oder in Cloud Shell), während Sie mit anderen Google Cloud-Ressourcen wie Cloud Storage oder der Vision API interagieren. In diesem Beispiel erfahren Sie, wie ein Dienst eine andere Funktion aufruft, für die eine Authentifizierung erforderlich ist. Weitere Informationen zu ADC und zur lokalen Entwicklung finden Sie im Blogpost So entwickeln und testen Sie Ihre Cloud Functions lokal | Google Cloud-Blog.

Gcloud-Befehl zum Impersonate eines Dienstkontos ausführen

ADC sucht automatisch Anmeldedaten basierend auf der Anwendungsumgebung und verwendet diese zur Authentifizierung bei Google Cloud APIs. Mit dem Flag „–impersonate-service-account“ können Sie die Identität eines Dienstkontos verwenden, um sich bei Google Cloud APIs zu authentifizieren.

Wenn Sie sich als Dienstkonto ausgeben möchten, können Sie den folgenden Befehl ausführen:

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

Jetzt führen Sie gcloud-Befehle als dieses Dienstkonto aus, anstatt als Ihre Identität.

Dienst zum Aufrufen einer authentifizierten Funktion erstellen und ausführen

Jede Laufzeit hat ihre eigene Google Auth-Clientbibliothek, die Sie installieren können. In diesem Codelab erfahren Sie, wie Sie eine Node.js-Anwendung lokal erstellen und ausführen.

So gehts mit Node.js:

1. Neues Verzeichnis erstellen

mkdir local-dev && cd $_

2. Neue Node.js-Anwendung erstellen

npm init -y

3. Google Auth-Clientbibliothek installieren

npm install google-auth-library

4. index.js-Datei erstellen
5. Rufen Sie die URL Ihrer Cloud Run-Funktion ab, die Sie im folgenden Schritt Ihrem Code hinzufügen.

echo $FUNCTION_URL

6. Fügen Sie "index.js" den folgenden Code hinzu. Ändern Sie die Variable „targetAudience“ in die URL Ihrer Cloud Run-Funktion.

index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-RUN-FUNCTION-URL>';

// For Cloud Functions, endpoint(`url`) and `targetAudience` should be equal

const url = targetAudience;

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

async function request() {
    console.info(`request ${url} with target audience ${targetAudience}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

request().catch(err => {
    console.error(err.message);
    process.exitCode = 1;
});

7. Anwendung ausführen

node index.js

Sie sollten nun die Ausgabe „Hello World!“ sehen.

Fehlerbehebung

Wenn der Fehler „Berechtigung „iam.serviceAccounts.getOpenIdToken“ verweigert für die Ressource angezeigt wird oder möglicherweise nicht vorhanden ist, warten Sie einige Minuten, bis die Rolle „Ersteller von Dienstkonto-Tokens“ übertragen wurde.

Wenn die Fehlermeldung „ID-Token kann in dieser Umgebung nicht abgerufen werden“ angezeigt wird, verwenden Sie GCE oder legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf eine JSON-Datei mit den Anmeldedaten für das Dienstkonto fest. Möglicherweise haben Sie vergessen, den Befehl auszuführen.

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs!

Wir empfehlen Ihnen, die Dokumentation zum Sichern von Cloud Run-Funktionen zu lesen.

In diesem Blogpost zur lokalen Entwicklung mit Cloud Run-Funktionen erfahren Sie, wie Sie Ihre Cloud Run-Funktion in Ihrer lokalen Entwicklungsumgebung entwickeln und testen.

Behandelte Themen

• Authentifizierung für eine Cloud Run-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert ist
• Eine authentifizierte Funktion aus einer lokalen Entwicklungsumgebung aufrufen, indem Sie das Token für Ihre gcloud-Identität bereitstellen
• Dienstkonto erstellen und die entsprechende Rolle zum Aufrufen einer Funktion zuweisen
• So übernehmen Sie die Identität eines Dienstes aus einer lokalen Entwicklungsumgebung, die die entsprechenden Rollen zum Aufrufen einer Funktion hat

8. Bereinigen

Um unbeabsichtigte Gebühren zu vermeiden, z. B. weil diese Cloud Functions-Funktion versehentlich häufiger aufgerufen wird als Ihre monatliche Zuweisung von Cloud Run-Funktionsaufrufen in der kostenlosen Stufe, können Sie entweder die Cloud Functions-Funktion oder das in Schritt 2 erstellte Projekt löschen.

Wenn Sie die Identität des Dienstkontos nicht mehr übernehmen möchten, können Sie sich mit Ihrer Identität wieder anmelden:

gcloud auth application-default login

Wenn Sie die Cloud Run-Funktion löschen möchten, rufen Sie die Cloud Run-Funktion in der Cloud Console unter https://console.cloud.google.com/functions/ auf. Achten Sie darauf, dass das in Schritt 2 erstellte Projekt das aktuell ausgewählte Projekt ist.

Wählen Sie my-Authenticate-function aus, die Sie zuvor bereitgestellt haben. Klicken Sie dann auf Löschen.

Wenn Sie das gesamte Projekt löschen möchten, rufen Sie https://console.cloud.google.com/cloud-resource-manager auf, wählen Sie das in Schritt 2 erstellte Projekt aus und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie die Projekte in Ihrem Cloud SDK ändern. Sie können eine Liste aller verfügbaren Projekte aufrufen, indem Sie gcloud projects list ausführen.