Informationen zum Aufrufen authentifizierter Cloud Functions-Funktionen

1. Einführung

Übersicht

Cloud 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.

Es gibt zwei Hauptansätze, um Aufrufe von Cloud Functions zu steuern: Zugriff basierend auf der Identität sichern und Zugriff mit netzwerkbasierter Zugriffssteuerung sichern. In diesem Codelab geht es um den ersten Ansatz. Sie werden durch drei Szenarien geführt, in denen der Zugriff auf eine Funktion auf Grundlage der Identität gesichert wird:

1. gcloud-Identitätstoken verwenden, um eine Funktion für lokale Entwicklungs- und Testzwecke aufzurufen
2. Bei der lokalen Entwicklung und beim lokalen Testen die Identität eines Dienstkontos annehmen, um dieselben Anmeldedaten wie in der Produktion zu verwenden
3. Google-Clientbibliotheken für die Authentifizierung bei Google Cloud APIs verwenden, z.B. wenn ein Dienst eine Funktion aufrufen muss

Lerninhalte

• Authentifizierung für eine Cloud-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert wurde
• Authentifizierte Funktion aus einer lokalen Entwicklungsumgebung aufrufen, indem Sie das Token für Ihre gcloud-Identität angeben
• So erstellen Sie ein Dienstkonto und weisen ihm die entsprechende Rolle zum Aufrufen einer Funktion zu
• Identität eines Dienstes in einer lokalen Entwicklungsumgebung annehmen, 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 Cloud Functions-Funktion der 2. Generation mit HTTP-Trigger bereitgestellt.
• (Optional) Für das dritte Szenario wird 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 Fenster mit einer Beschreibung eingeblendet. Klicken Sie in diesem Fall einfach auf Weiter.

Das Herstellen der Verbindung mit der Cloud Shell sollte nur wenige Augenblicke 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 sogar alle Aufgaben in diesem Codelab können mit einem Browser erledigt werden.

Sobald die Verbindung mit der Cloud Shell hergestellt ist, sehen Sie, dass Sie authentifiziert sind und für das Projekt Ihre Projekt-ID eingestellt ist.

2. Führen Sie in der 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 ein leistungsstarkes und vereinheitlichtes Befehlszeilentool in Google Cloud. Das Tool ist in der 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 den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass 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 ausführen, folgen Sie der Anleitung unter Standardanmeldedaten für Anwendungen einrichten.

3. Authentifizierte Cloud Functions-Funktion erstellen und testen

In diesem Codelab wird der Console-Schnellstart für Cloud Functions verwendet. Eine wichtige Ausnahme ist jedoch, dass für Ihre Funktion eine Authentifizierung erforderlich ist.

Wenn eine Authentifizierung erforderlich ist, muss das Hauptkonto, das die Funktion aufruft, die Rollen „Cloud Functions Invoker“ (und „Cloud Run Invoker“ für Funktionen der 2. Generation) haben. Andernfalls gibt die Funktion den Fehler „403 Forbidden“ zurück. In diesem Codelab wird gezeigt, wie Sie einem Prinzipal die entsprechenden Aufruferrollen zuweisen.

Authentifizierte Funktion erstellen

So verwenden Sie die Cloud Console:

1. Rufen Sie die Cloud Functions-Übersicht auf und klicken Sie auf Funktion erstellen.
2. Wählen Sie unter der Option Umgebung die Option 2. Generation aus.
3. Geben Sie der Funktion den Namen my-authenticated-function.
4. Lassen Sie im Feld „Authentifizierung“ die Standardeinstellung Authentifizierung erforderlich bei.

5. Klicken Sie auf Weiter.
6. Für dieses Codelab können Sie eine beliebige Sprache auswählen.
7. Klicken Sie dann auf Bereitstellen.

Die Bereitstellung der Funktion dauert etwa eine Minute.

Lokale Umgebungsvariablen für vereinfachte gcloud-Befehle einrichten

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

Sie müssen die Region für Ihre Funktion angeben. In diesem Beispiel wird us-central1 verwendet.

REGION="us-central1"

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

PROJECT_ID=$(gcloud config get-value project)
FUNCTION_URL="$(gcloud functions describe my-authenticated-function --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 Sie den erwarteten 403-Fehler erhalten.

Führen Sie über die Befehlszeile den folgenden curl-Befehl aus:

curl $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 können Sie sich drei Szenarien ansehen, in denen Sie Ihre Funktion durch Authentifizierung aufrufen können.

4. Szenario 1: gcloud-Identitätstoken verwenden

Als Entwickler benötigen Sie eine Möglichkeit, Ihre Funktion während der lokalen Entwicklung zu testen. 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 Ihrer aktiven Identität sollte ein Sternchen zu sehen sein, z. B.:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Nachdem Sie bestätigt haben, dass Sie die richtige Identität verwenden, speichern Sie die Konto-E-Mail-Adresse in einer Umgebungsvariablen.

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(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 Identitätstoken.

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

Jetzt sehen Sie das Ergebnis:

Hello World!

Fehlerbehebung

Wenn Sie einen Fehler vom Typ „403 Forbidden“ erhalten, prüfen Sie, ob Ihre Identität für Funktionen der 2. Generation die Rolle Cloud Functions Invoker oder Cloud Run Invoker hat. Mit der IAM-Konsole können Sie die Rollen prüfen, die einem Hauptkonto zugewiesen sind.

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

Sie sollten das Prinzip der geringsten Berechtigung anwenden und die Anzahl der Identitäten und Dienstkonten mit Rollen zum Aufrufen der Funktion begrenzen.

ein neues Dienstkonto erstellen und ihm die erforderlichen Rollen zuweisen.

5. Szenario 2: Identität eines Dienstkontos übernehmen

In diesem Szenario übernehmen Sie die Identität eines Dienstkontos (d.h. Sie nehmen dessen Berechtigungen an), um eine Funktion aufzurufen, wenn Sie lokal entwickeln und testen. Durch die Identitätsübernahme eines Dienstkontos 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 die Rolle „Cloud Functions-Aufrufer“ nur für lokale Testzwecke zuweisen müssen.

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

Neues Dienstkonto erstellen

Zuerst erstellen Sie einige zusätzliche Umgebungsvariablen, die die in den gcloud-Befehlen verwendeten Dienstkonten darstellen.

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 Function Authentication codelab"

Weisen Sie dem Dienstkonto die Rolle „Cloud Functions-Aufrufer“ zu.

gcloud functions add-iam-policy-binding my-authenticated-function \
  --region=us-central1 --gen2 \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/cloudfunctions.invoker'

Sie werden gefragt, ob Sie dem Dienstkonto eine zusätzliche Rolle für Cloud Run Invoker zuweisen möchten. Drücken Sie „y“ oder die Eingabetaste, um die Rolle „Cloud Run Invoker“ hinzuzufügen.

Funktion durch Identitätsübernahme des Dienstkontos aufrufen

Dazu übernehmen Sie die Identität des neu erstellten Dienstkontos, indem Sie das ID-Token abrufen.

Erforderliche Rollen für die Identitätsübernahme 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.

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

ID-Token des Dienstkontos verwenden

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

Im letzten Teil dieses 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 programmatisch mit den Google Auth-Clientbibliotheken und Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) auf. Weitere Informationen zu Google-Clientbibliotheken finden Sie im Abschnitt Erläuterung zu Clientbibliotheken der Dokumentation.

Die Verwendung von ADC ist besonders wichtig, wenn Sie Ihre Funktion lokal (z. B. auf Ihrem Laptop oder in Cloud Shell) schreiben und testen möchten und dabei mit anderen Google Cloud-Ressourcen (z. B. Cloud Storage oder Vision API) interagieren. In diesem Beispiel wird gezeigt, 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 How to develop and test your Cloud Functions locally | Google Cloud Blog.

gcloud-Befehl zum Annehmen der Identität eines Dienstkontos ausführen

ADC findet Anmeldedaten automatisch 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 für die Authentifizierung bei Google Cloud APIs übernehmen.

Führen Sie den folgenden Befehl aus, um die Identität eines Dienstkontos anzunehmen:

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

Sie führen jetzt gcloud-Befehle als dieses Dienstkonto und nicht als Ihre Identität aus.

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-App lokal erstellen und ausführen.

So gehts:

1. Neue Node.js-Anwendung erstellen

npm init

2. Google Auth-Clientbibliothek installieren

npm install google-auth-library

3. index.js-Datei erstellen
4. Rufen Sie die URL Ihrer Cloud Functions-Funktion ab, die Sie im nächsten Schritt in Ihren Code einfügen.

echo $FUNCTION_URL

5. Fügen Sie den folgenden Code in die Datei „index.js“ ein. Achten Sie darauf, die Variable „targetAudience“ in Ihre Cloud Functions-URL zu ändern.

index.js

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

const targetAudience = '<YOUR-CLOUD-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;
});

6. Anwendung ausführen

node index.js

Sie sollten das Ergebnis „Hello World!“ sehen.

Fehlerbehebung

Wenn Sie den Fehler „Permission ‚iam.serviceAccounts.getOpenIdToken‘ denied on resource (or it may not exist).“ (Berechtigung „iam.serviceAccounts.getOpenIdToken“ für Ressource verweigert (oder sie ist möglicherweise nicht vorhanden)) sehen, warten Sie einige Minuten, bis die Rolle „Ersteller von Dienstkonto-Tokens“ übernommen wird.

Wenn Sie den Fehler „Cannot fetch ID token in this environment, use GCE or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account credentials JSON file“ (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!

Wir empfehlen, die Dokumentation zum Sichern von Cloud Functions zu lesen.

Wir empfehlen Ihnen außerdem diesen Blogbeitrag zur lokalen Entwicklung mit Cloud Functions, in dem Sie erfahren, wie Sie Ihre Cloud Functions-Funktion in Ihrer lokalen Entwicklungsumgebung entwickeln und testen.

Behandelte Themen

• Authentifizierung für eine Cloud-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert wurde
• Authentifizierte Funktion aus einer lokalen Entwicklungsumgebung aufrufen, indem Sie das Token für Ihre gcloud-Identität angeben
• So erstellen Sie ein Dienstkonto und weisen ihm die entsprechende Rolle zum Aufrufen einer Funktion zu
• Identität eines Dienstes in einer lokalen Entwicklungsumgebung annehmen, die die entsprechenden Rollen zum Aufrufen einer Funktion hat

8. Bereinigen

Um unbeabsichtigte Gebühren zu vermeiden (z. B. wenn diese Cloud Functions-Funktion versehentlich öfter aufgerufen wird als Ihre monatliche Zuweisung von Cloud Functions-Aufrufen im kostenlosen Kontingent), können Sie entweder die Cloud Functions-Funktion oder das Projekt löschen, das Sie in Schritt 2 erstellt haben.

Wenn Sie die Identitätsübernahme des Dienstkontos beenden möchten, können Sie sich mit Ihrer Identität neu anmelden:

gcloud auth application-default login

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

Wählen Sie die zuvor bereitgestellte Funktion my-authenticated-function aus. 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 Projekt aus, das Sie in Schritt 2 erstellt haben, und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie das Projekt in Ihrem Cloud SDK ändern. Sie können die Liste aller verfügbaren Projekte mit gcloud projects list aufrufen.