Informationen zum Aufrufen authentifizierter Cloud Functions-Funktionen

1. Einführung

Übersicht

Cloud Functions ist eine ressourcensparende Computing-Lösung, mit der Entwickler zweckgebundene, eigenständige Funktionen erstellen können, die über HTTPS ausgelöst werden oder auf CloudEvents reagieren können, ohne einen Server oder eine Laufzeitumgebung verwalten zu müssen.

Es gibt zwei Hauptansätze zur Steuerung von Aufrufen von Cloud Functions: Zugriff basierend auf der Identität sichern 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. gcloud-Identitätstoken zum Aufrufen einer Funktion für die lokale Entwicklung verwenden Testzwecke
2. Beim lokalen Entwickeln und Testen die Identität eines Dienstkontos übernehmen, um dieselben Anmeldedaten wie in der Produktion zu verwenden
3. Verwenden Sie Google-Clientbibliotheken für die Authentifizierung bei Google Cloud APIs, z.B. Ein Dienst muss eine Funktion aufrufen.

Aufgaben in diesem Lab

• Authentifizierung für eine Cloud Functions-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert wurde
• 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 zuvor eine HTTP-ausgelöste Cloud Functions-Funktion der 2. Generation bereitgestellt
• (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 der Funktion angezeigt. Wenn ein Zwischenbildschirm angezeigt wird, klicken Sie auf Weiter.

Die Bereitstellung und Verbindung mit Cloud Shell dauert nur einen Moment.

Diese virtuelle Maschine verfügt über alle erforderlichen Entwicklertools. Es bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und wird in Google Cloud ausgeführt, wodurch die Netzwerkleistung und Authentifizierung erheblich verbessert werden. 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 eingestellt 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 ein leistungsstarkes und einheitliches 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 Functions-Funktion erstellen und testen

Dieses Codelab funktioniert genauso wie in der Console-Kurzanleitung für Cloud Functions. Es gibt jedoch eine Ausnahme: Für die Funktion ist eine Authentifizierung erforderlich.

Eine Authentifizierung erfordert, dass das Prinzip zum Aufrufen der Funktion die Rollen „Cloud Functions-Aufrufer“ (und „Cloud Run-Aufrufer“ für die 2. Generation) haben muss. Andernfalls gibt die Funktion den Fehler 403 Forbidden zurück. In diesem Codelab erfahren Sie, wie Sie einem Hauptkonto die entsprechenden Invoker-Rollen zuweisen.

Authentifizierte Funktion erstellen

So verwenden Sie die Cloud Console:

1. Rufen Sie die Seite Cloud Functions – Übersicht auf und klicken Sie auf Funktion erstellen.
2. Wählen Sie unter Umgebung die Option 2. Generation aus.
3. Nennen Sie die Funktion my-Authenticate-function
4. Übernehmen Sie im Feld „Authentifizierung“ die Standardeinstellung Authentifizierung erforderlich.

5. Klicken Sie auf Weiter.
6. Für dieses Codelab kannst du eine beliebige Sprache auswählen
7. Klicke dann auf Bereitstellen.

Das Bereitstellen der Funktion dauert ungefähr 1 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 die Funktion angeben. In diesem Beispiel wird us-central1 verwendet.

REGION="us-central1"

Dann 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, 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 einer 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 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 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 ordnungsgemäß authentifiziert wurde.

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

gcloud auth list

Neben deiner aktiven Identität sollte ein Sternchen angezeigt werden, zum Beispiel:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Nachdem Sie überprüft haben, ob Sie die richtige Identität verwenden, speichern Sie die E-Mail-Adresse des Kontos in einer Umgebungsvariablen.

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(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 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 Functions Invoker oder Cloud Run Invoker für Funktionen der 2. Generation hat. Sie können die IAM-Konsole verwenden, um Rollen zu 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 Ihrer 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.

ein neues Dienstkonto zu erstellen und ihm die erforderlichen Rollen zu gewähren.

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

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 die Identität eines Dienstkontos übernehmen, können Sie Ihre Funktion mit denselben Anmeldedaten wie in der Produktionsumgebung 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 Function Authentication codelab"

Gewähren Sie dem Dienstkonto die Rolle „Cloud Functions-Aufrufer“.

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

Sie werden aufgefordert, dem Dienstkonto eine zusätzliche Rolle für Cloud Run Invoker zu gewähren. Drücken Sie „y“. oder drücken Sie die Eingabetaste, um die Rolle „Cloud Run Invoker“ hinzuzufügen.

Funktion aufrufen, indem Sie die Identität des Dienstkontos übernehmen

Zu diesem Zweck übernehmen Sie die Identität des neu erstellten Dienstkontos, indem Sie sein 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-Token (roles/iam.serviceAccountTokenCreator) haben, damit ein ID-Token für das Dienstkonto generiert werden kann.

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

ID-Token des Dienstkontos verwenden

Jetzt können Sie die Funktion 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 im Abschnitt „Erläuterung der Clientbibliotheken“ der Dokumentation.

Die Verwendung von ADC ist besonders wichtig, wenn Sie Ihre Funktion lokal (z. B. auf Ihrem Laptop, in Cloud Shell usw.) schreiben und testen möchten, während Sie mit anderen Google Cloud-Ressourcen (z. B. Cloud Storage, Vision API usw.) interagieren. In diesem Beispiel sehen Sie, wie ein Dienst eine andere Funktion aufruft, die eine Authentifizierung erfordert. Weitere Informationen zu ADC und lokaler Entwicklung finden Sie im Blogpost How toDevelop and Testing your Cloud Functions local | Google Cloud-Blog

gcloud-Befehl ausführen, um die Identität eines Dienstkontos zu übernehmen

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 übernehmen, indem Sie dessen Identität zur Authentifizierung bei Google Cloud APIs verwenden.

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 und nicht mehr als Ihre Identität aus.

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.

Führen Sie für Node.js die folgenden Schritte aus:

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 folgenden Schritt Ihrem Code hinzufügen.

echo $FUNCTION_URL

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

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

Jetzt sollten Sie das Ergebnis "Hello World!"

Fehlerbehebung

Wenn der Fehler „Berechtigung“ „iam.serviceAccounts.getOpenIdToken“ angezeigt wird für Ressource abgelehnt (oder ist möglicherweise nicht vorhanden). Warten Sie einige Minuten, bis die Rolle „Ersteller von Dienstkonto-Tokens“ weitergegeben 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 Functions-Funktionen zu lesen.

Wir empfehlen außerdem diesen Blogpost zur lokalen Entwicklung mit Cloud Functions. Darin erfahren Sie, wie Sie eine Cloud Functions-Funktion in Ihrer lokalen Entwicklungsumgebung entwickeln und testen.

Behandelte Themen

• Authentifizierung für eine Cloud Functions-Funktion konfigurieren und prüfen, ob die Authentifizierung richtig konfiguriert wurde
• 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 versehentliche Gebühren zu vermeiden, z. B. wird diese Cloud Functions-Funktion versehentlich häufiger aufgerufen als Ihre monatliche Zuweisung von Cloud Functions-Aufrufen 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 noch einmal mit Ihrer Identität anmelden:

gcloud auth application-default login

Rufen Sie zum Löschen der Cloud Functions-Funktion die 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 die zuvor bereitgestellte my-Authenticate-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 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 die Liste aller verfügbaren Projekte mit dem Befehl gcloud projects list aufrufen.