Dowiedz się, jak wywoływać uwierzytelnione funkcje w Cloud Functions

1. Wprowadzenie

Omówienie

Cloud Functions to wymagające niewielu zasobów rozwiązanie obliczeniowe, które umożliwia programistom tworzenie jednozadaniowych, samodzielnych funkcji, które można uruchamiać za pomocą protokołu HTTPS lub reagować na zdarzenia CloudEvents bez konieczności zarządzania serwerem lub środowiskiem wykonawczym.

Istnieją 2 główne sposoby kontrolowania wywołań do Cloud Functions: zabezpieczanie dostępu na podstawie tożsamości i zabezpieczanie dostępu za pomocą kontroli dostępu opartej na sieci. To ćwiczenie w Codelabs koncentruje się na pierwszym podejściu i przedstawia 3 scenariusze zabezpieczania dostępu na podstawie tożsamości w celu wywołania funkcji:

1. Użyj tokena tożsamości gcloud do wywoływania funkcji na potrzeby programowania lokalnego & cele testowania
2. Podczas programowania i testowania lokalnie przyjmij tożsamość konta usługi, aby używać tych samych danych logowania co w środowisku produkcyjnym
3. Używaj bibliotek klienta Google do obsługi uwierzytelniania w interfejsach Google Cloud APIs, np. gdy usługa musi wywołać funkcję.

Czego się nauczysz

• Jak skonfigurować uwierzytelnianie w funkcji w Cloud Functions i sprawdzić, czy uwierzytelnianie zostało prawidłowo skonfigurowane
• Wywołaj uwierzytelnione funkcję z lokalnego środowiska programistycznego, podając token tożsamości gcloud.
• Jak utworzyć konto usługi i przypisać mu odpowiednią rolę do wywoływania funkcji
• Jak przyjąć usługę w lokalnym środowisku programistycznym, które ma odpowiednie role do wywoływania funkcji

2. Konfiguracja i wymagania

Wymagania wstępne

• Jesteś zalogowany(-a) w konsoli Google Cloud
• Masz już wdrożoną funkcję w Cloud Functions 2 generacji aktywowaną przez HTTP
• (Opcjonalnie) W trzecim scenariuszu to ćwiczenie w Codelabs używa jako przykładu Node.js i npm. Możesz jednak użyć dowolnego środowiska wykonawczego, które jest obsługiwane przez biblioteki klienta Google Auth.

Aktywowanie Cloud Shell

1. W konsoli Cloud kliknij Aktywuj Cloud Shell .

Jeśli uruchamiasz Cloud Shell po raz pierwszy, zobaczysz ekran pośredni z opisem tej usługi. Jeśli wyświetlił się ekran pośredni, kliknij Dalej.

Uzyskanie dostępu do Cloud Shell i połączenie się z nim powinno zająć tylko kilka chwil.

Ta maszyna wirtualna ma wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i uwierzytelnianie. Większość zadań w ramach tego ćwiczenia z programowania można wykonać w przeglądarce.

Po nawiązaniu połączenia z Cloud Shell powinno pojawić się potwierdzenie, że użytkownik jest uwierzytelniony, a projekt jest ustawiony na identyfikator Twojego projektu.

2. Uruchom to polecenie w Cloud Shell, aby potwierdzić, że jesteś uwierzytelniony:

gcloud auth list

Dane wyjściowe polecenia

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

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

Uwaga: narzędzie wiersza poleceń gcloud to zaawansowane, ujednolicone narzędzie wiersza poleceń w Google Cloud. Jest ona wstępnie zainstalowana w Cloud Shell. Zauważysz, że obsługuje ona funkcję autouzupełniania. Więcej informacji znajdziesz w artykule Omówienie narzędzia wiersza poleceń gcloud.

3. Uruchom to polecenie w Cloud Shell, aby sprawdzić, czy polecenie gcloud zna Twój projekt:

gcloud config list project

Dane wyjściowe polecenia

[core]
project = <PROJECT_ID>

Jeśli tak nie jest, możesz go ustawić za pomocą tego polecenia:

gcloud config set project <PROJECT_ID>

Dane wyjściowe polecenia

Updated property [core/project].

Uwaga: jeśli wykonujesz ten samouczek poza Cloud Shell, przeczytaj artykuł Konfigurowanie domyślnych danych logowania aplikacji.

3. Tworzenie i testowanie uwierzytelnionej funkcji w Cloud Functions

To ćwiczenie w Codelabs zawiera te same instrukcje z krótkiego wprowadzenia do konsoli dla Cloud Functions, z jednym istotnym wyjątkiem: funkcja będzie wymagać uwierzytelnienia.

Wymaganie uwierzytelniania oznacza, że zasada wywołująca funkcję musi mieć role wywołującego Cloud Functions (oraz wywołującego Cloud Run 2 generacji). W przeciwnym razie funkcja zwróci błąd 403 (zabroniony). Dzięki temu ćwiczeniu w Codelabs dowiesz się, jak przypisać do zasady odpowiednie role wywołującego.

Utwórz funkcję uwierzytelnioną

Aby zacząć korzystać z konsoli Google Cloud:

1. Otwórz stronę z podsumowaniem funkcji w Cloud Functions i kliknij Utwórz funkcję.
2. W sekcji Środowisko wybierz 2 generacji.
3. Nazwij funkcję my-authenticated-function.
4. W polu Uwierzytelnianie pozostaw wartość domyślną Wymagaj uwierzytelniania.

5. Kliknij Dalej.
6. W tym ćwiczeniu z programowania możesz wybrać dowolny język
7. Następnie kliknij Deploy (Wdróż).

Wdrożenie funkcji trwa około 1 minuty.

Konfigurowanie lokalnych zmiennych środowiskowych na potrzeby uproszczonych poleceń gcloud

Najpierw utwórz kilka zmiennych środowiskowych, aby poprawić czytelność poleceń gcloud używanych w tym ćwiczeniu z programowania.

Musisz określić region dla swojej funkcji. W tym przykładzie użyto elementu us-central1.

REGION="us-central1"

a potem zapisać URL funkcji jako zmienną środowiskową do późniejszego użycia.

PROJECT_ID=$(gcloud config get-value project)
FUNCTION_URL="$(gcloud functions describe my-authenticated-function --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

Sprawdź, czy funkcja wymaga uwierzytelniania, próbując wywołać anonimowy element wywołujący

Wywołujesz funkcję bez uwierzytelniania, aby sprawdzić, czy pojawia się oczekiwany błąd 403.

W wierszu poleceń uruchom następujące polecenie curl:

curl $FUNCTION_URL

Zobaczysz następujący wynik:

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

Teraz możesz przejść przez 3 scenariusze, w których można wywołać funkcję przez zapewnienie uwierzytelniania.

4. Scenariusz 1. Korzystanie z tokena tożsamości gcloud

Jako programista przyda Ci się możliwość testowania funkcji podczas jej lokalnego programowania. W tej sekcji przeprowadzisz szybki test, aby sprawdzić, czy funkcja jest prawidłowo uwierzytelniona przy użyciu Twojej tożsamości.

Sprawdź swoje uwierzytelnianie przy użyciu gcloud, uruchamiając następujące polecenie:

gcloud auth list

Gwiazdka powinna być widoczna obok aktywnej tożsamości, na przykład:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Gdy upewnisz się, że używasz prawidłowej tożsamości, zapiszesz adres e-mail powiązany z kontem w zmiennej środowiskowej.

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

Więcej informacji na temat konfigurowania gcloud init i gcloud auth login znajdziesz w dokumentacji.

Następnie wywołaj funkcję i przekaż jej swój token tożsamości.

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

Teraz zobaczysz wynik:

Hello World!

Rozwiązywanie problemów

Jeśli pojawi się błąd 403 „Dostęp zabroniony”, sprawdź, czy Twoja tożsamość ma rolę wywołującego funkcje Cloud Functions lub rolę wywołującego Cloud Run w przypadku funkcji 2 generacji. Role przypisane podmiotowi zabezpieczeń możesz zweryfikować w konsoli uprawnień.

Użycie własnego tokena tożsamości to szybki sposób na przetestowanie funkcji w trakcie programowania, jednak osoba wywołująca uwierzytelnione funkcje wymaga odpowiednich ról. W przeciwnym razie element wywołujący wyświetli błąd 403 (Zabroniony).

Zalecamy, aby postępować zgodnie z zasadą jak najmniejszych uprawnień przez ograniczenie liczby tożsamości i kont usługi z rolami wywołującymi tę funkcję.

przez utworzenie nowego konta usługi i przypisanie mu niezbędnych ról, czyli

5. Scenariusz 2. Odgrywaj rolę konta usługi

W tym scenariuszu odbierzesz się (czyli przyjmiesz uprawnienia) konta usługi, aby wywołać funkcję podczas programowania i testowania lokalnie. Podejmując rolę konta usługi, możesz przetestować funkcję z tymi samymi danymi uwierzytelniającymi co w środowisku produkcyjnym.

W ten sposób nie tylko weryfikujesz role, lecz także przestrzegasz zasady jak najmniejszych uprawnień, ponieważ nie musisz przypisywać roli wywołującego funkcje w Cloud Functions innym tożsamościom tylko na potrzeby lokalnych testów.

Na potrzeby tego ćwiczenia w Codelabs utworzysz nowe konto usługi, które ma tylko role do wywoływania funkcji utworzonej w ramach tego ćwiczenia.

Utwórz nowe konto usługi

Najpierw utwórz kilka dodatkowych zmiennych środowiskowych reprezentujących konta usługi używane w poleceniach gcloud.

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

Następnie utwórz konto usługi.

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

I przypisz do konta usługi rolę wywołującego funkcję w Cloud Functions

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

Pojawi się pytanie, czy chcesz przypisać do konta usługi dodatkową rolę dla wywołującego Cloud Run. Naciśnij „y”. lub naciśnij Enter, aby dodać rolę wywołującego Cloud Run.

Wywołaj funkcję przez przyjęcie tożsamości konta usługi

W tym celu przejmiesz tożsamość nowo utworzonego konta usługi, uzyskując jego token identyfikatora.

Dodawanie wymaganych ról na potrzeby przyjmowania innej tożsamości

Aby można było odgrywać rolę konta usługi, konto użytkownika musi mieć rolę Twórca tokenów konta usługi (roles/iam.serviceAccountTokenCreator), co pozwoli na wygenerowanie tokena identyfikatora konta usługi.

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

Użyj tokena identyfikatora konta usługi

Teraz możesz wywołać funkcję, przekazując token identyfikatora konta usługi.

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

Oto, co zobaczysz:

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. Scenariusz 3. Korzystanie z bibliotek klienta Google

W tej ostatniej części ćwiczenia w Codelabs uruchomisz małą usługę lokalnie, aby wygenerować token identyfikatora dla konta usługi, a następnie automatycznie wywołasz funkcję za pomocą bibliotek klienta Google Auth i domyślnych danych logowania aplikacji (ADC). Więcej informacji o bibliotekach klienta Google znajdziesz w sekcji o bibliotekach klienta w dokumentacji.

Użycie ADC jest szczególnie ważne, gdy chcesz zapisywać i testować swoją funkcję lokalnie (np. na laptopie, w Cloud Shell itp.) podczas interakcji z innymi zasobami Google Cloud (np. Cloud Storage, Vision API itp.) Z tego przykładu dowiesz się, jak usługa wywołuje inną funkcję, która wymaga uwierzytelnienia. Więcej informacji na temat ADC i programowania lokalnego znajdziesz w poście na blogu Jak lokalnie tworzyć i testować funkcje w Cloud Functions | Blog Google Cloud

Uruchom polecenie gcloud, aby przyjąć tożsamość konta usługi

ADC automatycznie wyszukuje dane logowania na podstawie środowiska aplikacji i używa ich do uwierzytelniania w interfejsach Google Cloud APIs. Flaga –impersonate-service-account umożliwia przyjęcie tożsamości konta usługi przez użycie jego tożsamości do uwierzytelniania w odniesieniu do interfejsów API Google Cloud.

Aby przyjąć tożsamość konta usługi, możesz uruchomić to polecenie:

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

Teraz uruchamiasz polecenia gcloud jako konto usługi, a nie swoją tożsamość.

Utwórz i uruchom usługę do wywoływania uwierzytelnionej funkcji

Każde środowisko wykonawcze ma własną bibliotekę klienta Google Auth, którą możesz zainstalować. Dzięki temu ćwiczeniu w Codelabs dowiesz się, jak utworzyć i uruchomić aplikację Node.js lokalnie.

Wykonaj te czynności w przypadku środowiska Node.js:

1. Tworzenie nowej aplikacji w Node.js

npm init

2. Instalowanie biblioteki klienta Auth Google

npm install google-auth-library

3. Utwórz plik index.js
4. Pobierz adres URL funkcji w Cloud Functions, który dodasz do kodu w kolejnym kroku.

echo $FUNCTION_URL

5. Dodaj poniższy kod do pliku index.js. Pamiętaj, aby zmienić zmienną targetAudience na adres URL funkcji w Cloud Functions.

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. Uruchom aplikację

node index.js

Powinien wyświetlić się komunikat „Hello World”.

Rozwiązywanie problemów

Jeśli pojawia się błąd uprawnienia „iam.serviceAccounts.getOpenIdToken” odmowa dostępu do zasobu (lub może on nie istnieć). Poczekaj kilka minut na rozpowszechnienie roli twórcy tokenów konta usługi.

Jeśli pojawi się błąd Nie można pobrać tokena identyfikatora w tym środowisku, użyj GCE lub ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na plik JSON z danymi logowania na konto usługi, możliwe, że nie uruchomiono polecenia

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

7. Gratulacje!

Gratulujemy ukończenia ćwiczeń z programowania.

Zalecamy zapoznanie się z dokumentacją dotyczącą zabezpieczania funkcji w Cloud Functions.

Zalecamy też zapoznanie się z tym postem na blogu na temat lokalnego programowania w Cloud Functions, z którego dowiesz się, jak tworzyć i testować funkcje w Cloud Functions w lokalnym środowisku programistycznym.

Omówione zagadnienia

• Jak skonfigurować uwierzytelnianie w funkcji w Cloud Functions i sprawdzić, czy uwierzytelnianie zostało prawidłowo skonfigurowane
• Wywołaj uwierzytelnione funkcję z lokalnego środowiska programistycznego, podając token tożsamości gcloud.
• Jak utworzyć konto usługi i przypisać mu odpowiednią rolę do wywoływania funkcji
• Jak przyjąć usługę w lokalnym środowisku programistycznym, które ma odpowiednie role do wywoływania funkcji

8. Czyszczenie danych

Aby uniknąć niezamierzonych opłat (na przykład ta funkcja w Cloud Functions jest nieumyślnie wywoływana więcej razy niż miesięczny przydział wywołań funkcji w Cloud Functions na poziomie bezpłatnym), możesz usunąć funkcję w Cloud Functions lub projekt utworzony w kroku 2.

Aby przestać odgrywać rolę konta usługi, możesz zalogować się ponownie przy użyciu swojej tożsamości:

gcloud auth application-default login

Aby usunąć funkcję w Cloud Functions, otwórz konsolę Cloud Functions w Cloud Functions na https://console.cloud.google.com/functions/. Upewnij się, że projekt utworzony w kroku 2 jest obecnie wybranym projektem.

Wybierz wdrożoną wcześniej my-authenticated-function. Następnie kliknij Usuń.

Jeśli zdecydujesz się usunąć cały projekt, możesz otworzyć stronę https://console.cloud.google.com/cloud-resource-manager, wybrać projekt utworzony w kroku 2 i kliknąć Usuń. Jeśli usuniesz projekt, musisz zmienić projekty w pakiecie SDK Cloud. Aby wyświetlić listę wszystkich dostępnych projektów, uruchom polecenie gcloud projects list.