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. Dieses Codelab konzentriert sich auf den ersten Ansatz und führt Sie durch drei Szenarien zum Sichern des Zugriffs basierend auf der Identität zum Aufrufen einer Funktion:

1. Mit Ihrem gcloud-Identitätstoken eine Funktion für die lokale Entwicklung und Tests aufrufen
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 übernehmen Sie die Identität eines Dienstes aus einer lokalen Entwicklungsumgebung, die die entsprechenden Rollen zum 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. Kurzanleitungsbeispiel ansehen.
• Optional: Für das dritte Szenario werden in diesem Codelab Node.js und npm als Beispiel verwendet. Sie können jedoch 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. Es bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und wird in Google Cloud ausgeführt. Dadurch werden die Netzwerkleistung und die Authentifizierung erheblich verbessert. Viele, wenn nicht sogar alle Arbeiten 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 über das 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 nicht in Cloud Shell ausführen, folgen Sie der Anleitung unter Standardanmeldedaten für Anwendungen einrichten.

3. Authentifizierte Cloud Run-Funktion erstellen und testen

Wenn die Authentifizierung erforderlich ist, muss das Hauptkonto, das die Funktion aufruft, die Rolle „Cloud Run Invoker“ haben. Andernfalls gibt die Funktion den Fehler 403 „Forbidden“ zurück. In diesem Codelab erfahren Sie, wie Sie einem Hauptkonto die entsprechenden Invoker-Rollen zuweisen.

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

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

Erstellen Sie zuerst ein Verzeichnis und wechseln Sie dann in dieses Verzeichnis.

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, ob die Funktion eine Authentifizierung erfordert, indem versucht wird, sie als anonymer Aufrufer aufzurufen

Sie rufen die Funktion ohne Authentifizierung auf, um zu überprüfen, ob Sie den erwarteten Fehler 403 erhalten.

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

curl -i $FUNCTION_URL

Sie sehen das folgende Ergebnis:

<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 Angabe einer Authentifizierung aufrufen können.

4. Szenario 1: gcloud-Identitätstoken verwenden

Als Entwickler möchten Sie Ihre Funktion testen können, während sie lokal entwickelt wird. In diesem Abschnitt führen Sie einen kurzen Test durch, um zu prüfen, ob die Funktion mit Ihrer eigenen Identität richtig authentifiziert wird.

Prüfen Sie mit dem folgenden Befehl, ob Sie mit gcloud authentifiziert sind:

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 zum 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 die Fehlermeldung 403 Forbidden erhalten, prüfen Sie, ob Ihre Identität die Rolle Cloud Run Invoker hat. In der IAM-Konsole können Sie die Rollen prüfen, die einem Hauptkonto zugewiesen wurden.

Die Verwendung Ihres eigenen Identitätstokens ist zwar eine schnelle Möglichkeit, Ihre Funktion während der Entwicklung zu testen, der Aufrufer Ihrer authentifizierten Funktion benötigt jedoch die entsprechenden Rollen. Andernfalls erhält er die Fehlermeldung „403 Forbidden“.

Sie sollten dem Prinzip der geringsten Berechtigung folgen, 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 übernehmen Sie die Identität (d.h. die Berechtigungen) eines Dienstkontos, um eine Funktion bei der lokalen Entwicklung und dem lokalen Testen aufzurufen. Wenn Sie sich als Dienstkonto ausgeben, können Sie Ihre Funktion mit denselben Anmeldedaten wie in der Produktion testen.

Auf diese Weise prüfen Sie nicht nur Rollen, sondern folgen auch dem Prinzip der geringsten Berechtigung, da Sie anderen Identitäten die Rolle „Cloud Functions-Aufrufer“ nicht nur für lokale Testzwecke 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"

Weisen Sie dem Dienstkonto die Rolle „Cloud Run Invoker“ zu:

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 nun 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

Für diesen letzten Teil des Codelabs führen Sie einen kleinen Dienst lokal aus, um ein ID-Token für ein Dienstkonto zu generieren. Anschließend rufen Sie die Funktion mithilfe der Google Auth-Clientbibliotheken und Standardanmeldedaten für Anwendungen programmatisch auf. Weitere Informationen zu Google-Clientbibliotheken finden Sie in der Dokumentation im Abschnitt Erläuterung zu Clientbibliotheken.

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 lokaler Entwicklung finden Sie im Blogpost How toDevelop and test your Cloud Functions local | Google Cloud Blog.

Gcloud-Befehl zum Impersonate eines Dienstkontos ausführen

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

Mit dem folgenden Befehl können Sie die Identität eines Dienstkontos übernehmen:

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

Für jede Laufzeit gibt es eine 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 nächsten Schritt in Ihren Code einfü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 die Fehlermeldung „Berechtigung ‚iam.serviceAccounts.getOpenIdToken‘ für die Ressource verweigert (oder nicht vorhanden)“ angezeigt wird, warten Sie einige Minuten, bis die Rolle „Ersteller von Dienstkonto-Tokens“ übernommen wurde.

Wenn Sie die Fehlermeldung „ID-Token kann in dieser Umgebung nicht abgerufen werden. Verwenden Sie GCE oder legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf eine JSON-Datei mit Dienstkontoanmeldedaten fest.“ erhalten haben, haben Sie möglicherweise vergessen, den Befehl

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

7. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs!

Weitere Informationen finden Sie in der Dokumentation zum Sichern von Cloud Run-Funktionen.

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 imitieren Sie einen Dienst aus einer lokalen Entwicklungsumgebung, der die entsprechenden Rollen für das Aufrufen einer Funktion hat

8. Bereinigen

Wenn Sie versehentliche Kosten vermeiden möchten, z. B. wenn diese Cloud-Funktion versehentlich öfter aufgerufen wird als Ihre monatliche Zuweisung für Cloud Run-Funktionen in der kostenlosen Stufe, können Sie entweder die Cloud-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.