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

1. Wprowadzenie

Przegląd

Cloud Functions to wymagające niewielu zasobów rozwiązanie do przetwarzania danych, które umożliwia programistom tworzenie samodzielnych funkcji o ściśle zdefiniowanym przeznaczeniu, które można wywoływać za pomocą protokołu HTTPS lub które reagują na CloudEvents bez konieczności zarządzania serwerem lub środowiskiem wykonawczym.

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

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

Czego się nauczysz

• Jak skonfigurować uwierzytelnianie w funkcji w Cloud Functions i sprawdzić, czy zostało ono prawidłowo skonfigurowane
• Wywoływanie uwierzytelnionej funkcji z lokalnego środowiska programistycznego przez podanie tokena tożsamości gcloud
• Jak utworzyć konto usługi i przypisać mu odpowiednią rolę do wywoływania funkcji
• Jak przyjmować tożsamość usługi w lokalnym środowisku programistycznym, które ma odpowiednie role do wywoływania funkcji

2. Konfiguracja i wymagania

Wymagania wstępne

• Jesteś zalogowany(-a) w Cloud Console.
• Masz już wdrożoną funkcję Cloud Functions 2 generacji aktywowaną przez HTTP.
• (opcjonalnie) W przypadku scenariusza 3 w tym ćwiczeniu używamy Node.js i npm jako przykładu, ale możesz użyć dowolnego środowiska wykonawczego obsługiwanego 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 tego środowiska. Jeśli pojawił się ekran pośredni, kliknij Dalej.

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

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Większość zadań w tym ćwiczeniu, a być może wszystkie, możesz wykonać w przeglądarce.

Po połączeniu z Cloud Shell zobaczysz, że uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu.

2. Aby potwierdzić, że uwierzytelnianie zostało przeprowadzone, uruchom w Cloud Shell to polecenie:

gcloud auth list

Wynik 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 i ujednolicone narzędzie wiersza poleceń w Google Cloud. Jest już zainstalowane w Cloud Shell. Zauważysz, że obsługuje on uzupełnianie za pomocą klawisza Tab. Więcej informacji znajdziesz w omówieniu narzędzia wiersza poleceń gcloud.

3. Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Wynik polecenia

[core]
project = <PROJECT_ID>

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

gcloud config set project <PROJECT_ID>

Wynik polecenia

Updated property [core/project].

Uwaga: jeśli wykonujesz ten samouczek poza Cloud Shell, postępuj zgodnie z instrukcjami w artykule Konfigurowanie domyślnego uwierzytelniania aplikacji.

3. Tworzenie i testowanie uwierzytelnionej funkcji w Cloud Functions

To ćwiczenie zawiera te same instrukcje co krótkie wprowadzenie do Cloud Functions w konsoli, z jednym istotnym wyjątkiem: funkcja będzie wymagać uwierzytelniania.

Wymaganie uwierzytelniania oznacza, że podmiot zabezpieczeń wywołujący funkcję musi mieć rolę wywołującego funkcje Cloud Functions (a w przypadku funkcji 2 generacji – rolę wywołującego Cloud Run). W przeciwnym razie funkcja zwróci błąd 403 Forbidden. W tym ćwiczeniu dowiesz się, jak przyznać odpowiednie role wywołującego podmiotowi zabezpieczeń.

Tworzenie funkcji uwierzytelnionej

Aby korzystać z Cloud Console:

1. Otwórz stronę Podsumowanie 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 domyślną wartość Wymagaj uwierzytelniania.

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

Wdrożenie funkcji zajmuje około minuty.

Konfigurowanie lokalnych zmiennych środowiskowych w celu uproszczenia poleceń gcloud

Najpierw utworzysz kilka zmiennych środowiskowych, aby zwiększyć czytelność poleceń gcloud używanych w tym ćwiczeniu.

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

REGION="us-central1"

Następnie możesz zapisać adres URL funkcji jako zmienną środowiskową, aby użyć jej później.

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 ją wywołać jako anonimowy rozmówca.

Wywołasz funkcję bez uwierzytelniania, aby sprawdzić, czy otrzymasz oczekiwany błąd 403.

W wierszu poleceń uruchom to polecenie curl:

curl $FUNCTION_URL

Wyświetli się ten 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 zapoznać się z 3 scenariuszami, w których możesz wywołać funkcję, podając dane uwierzytelniające.

4. Scenariusz 1. Użyj tokena tożsamości gcloud

Jako programista chcesz mieć możliwość testowania funkcji podczas jej tworzenia lokalnie. W tej sekcji przeprowadzisz szybki test, aby sprawdzić, czy funkcja jest prawidłowo uwierzytelniona przy użyciu Twojej tożsamości.

Sprawdź, czy uwierzytelnianie za pomocą gcloud działa prawidłowo, uruchamiając to polecenie:

gcloud auth list

Obok aktywnej tożsamości powinien wyświetlać się znak gwiazdki, np.:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Gdy potwierdzisz, że używasz właściwej tożsamości, zapisz adres e-mail konta w zmiennej środowiskowej.

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

Więcej informacji o konfigurowaniu gcloud init i gcloud auth login znajdziesz w dokumentacji.

Następnie wywołaj funkcję i przekaż jej 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 otrzymasz błąd 403 Forbidden, sprawdź, czy Twoja tożsamość ma rolę Wywołujący funkcje Cloud Functions lub Wywołujący Cloud Run w przypadku funkcji 2 generacji. Aby sprawdzić role przypisane do podmiotu zabezpieczeń, możesz użyć konsoli IAM.

Używanie własnego tokena tożsamości to szybki sposób na testowanie funkcji podczas programowania, ale osoba wywołująca uwierzytelnioną funkcję musi mieć odpowiednie role. W przeciwnym razie otrzyma błąd 403 Forbidden.

Zgodnie z zasadą jak najmniejszych uprawnień ogranicz liczbę tożsamości i kont usług, które mają role umożliwiające wywoływanie funkcji.

utworzenie nowego konta usługi i przyznanie mu niezbędnych ról,

5. Scenariusz 2. Przyjmowanie tożsamości konta usługi

W tym scenariuszu będziesz przyjmować tożsamość (czyli przyjmować uprawnienia) konta usługi, aby wywoływać funkcję podczas programowania i testowania lokalnego. Dzięki podszywaniu się pod konto usługi możesz testować funkcję przy użyciu tych samych danych logowania co w środowisku produkcyjnym.

Dzięki temu nie tylko zweryfikujesz role, ale też zastosujesz zasadę jak najmniejszych uprawnień, ponieważ nie musisz przyznawać roli wywołującego Cloud Functions innym tożsamościom tylko na potrzeby testowania lokalnego.

Na potrzeby tego ćwiczenia utworzysz nowe konto usługi, które będzie miało tylko role umożliwiające wywoływanie funkcji utworzonej w tym ćwiczeniu.

Utwórz nowe konto usługi

Najpierw utworzysz kilka dodatkowych zmiennych środowiskowych, które będą reprezentować 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 przyznaj kontu usługi rolę Wywołujący funkcje 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 przyznać kontu usługi dodatkową rolę Wywołujący Cloud Run. Naciśnij „y” lub Enter, aby dodać rolę Wywołujący Cloud Run.

Wywoływanie funkcji przez podawanie się za konto usługi

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

Dodawanie wymaganych ról do przyjmowania tożsamości

Aby podszywać się pod konto usługi, Twoje konto użytkownika musi mieć rolę Twórca tokenów kont usługi (roles/iam.serviceAccountTokenCreator), która umożliwia generowanie tokena tożsamości dla konta usługi.

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

Używanie tokena tożsamości 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)" 

Zobaczysz te informacje:

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 ostatniej części tego ćwiczenia uruchomisz małą usługę lokalnie, aby wygenerować token identyfikatora dla konta usługi, a następnie programowo wywołać funkcję za pomocą bibliotek klienta Google Auth i domyślnego uwierzytelniania aplikacji (ADC). Więcej informacji o bibliotekach klienta Google znajdziesz w sekcji wyjaśniającej biblioteki klienta w dokumentacji.

Korzystanie z ADC jest szczególnie ważne, gdy chcesz pisać i testować funkcję lokalnie (np. na laptopie, w Cloud Shell itp.) podczas interakcji z innymi zasobami Google Cloud (np. Cloud Storage, Vision API itp.). W tym przykładzie dowiesz się, jak sprawić, aby usługa wywoływała inną funkcję, która wymaga uwierzytelniania. Więcej informacji o ADC i lokalnym programowaniu znajdziesz w poście na blogu How to develop and test your Cloud Functions locally | Google Cloud Blog (Jak programować i testować funkcje Cloud Functions lokalnie | Blog Google Cloud).

Uruchamianie polecenia gcloud w celu przyjęcia tożsamości konta usługi

ADC automatycznie znajduje dane logowania na podstawie środowiska aplikacji i używa ich do uwierzytelniania w interfejsach Google Cloud APIs. Flaga –impersonate-service-account umożliwia przyjmowanie tożsamości konta usługi przez używanie jego tożsamości do uwierzytelniania w interfejsach Google Cloud APIs.

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

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

Polecenia gcloud są teraz uruchamiane jako to konto usługi, a nie jako Twoja tożsamość.

Tworzenie i uruchamianie usługi do wywoływania uwierzytelnionej funkcji

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

Oto instrukcje dla Node.js:

1. Tworzenie nowej aplikacji Node.js

npm init

2. Instalowanie biblioteki klienta Google Auth

npm install google-auth-library

3. Tworzenie pliku index.js
4. Pobierz adres URL funkcji w Cloud Functions, który dodasz do kodu w następnym kroku.

echo $FUNCTION_URL

5. Dodaj ten 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. Uruchamianie aplikacji

node index.js

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

Rozwiązywanie problemów

Jeśli pojawi się błąd „Permission ‘iam.serviceAccounts.getOpenIdToken' denied on resource (or it may not exist)” (Odmowa dostępu do zasobu (lub zasób może nie istnieć) z powodu uprawnienia „iam.serviceAccounts.getOpenIdToken”), poczekaj kilka minut, aż rola Twórca tokenów konta usługi zostanie rozpowszechniona.

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 konta usługi, być może zapomniałeś(-aś) uruchomić polecenie

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

7. Gratulacje!

Gratulujemy ukończenia ćwiczenia!

Zalecamy zapoznanie się z dokumentacją na temat zabezpieczania Cloud Functions.

Aby dowiedzieć się, jak programować i testować funkcję w Cloud Functions w lokalnym środowisku programistycznym, przeczytaj ten post na blogu o lokalnym programowaniu z wykorzystaniem Cloud Functions.

Omówione zagadnienia

• Jak skonfigurować uwierzytelnianie w funkcji w Cloud Functions i sprawdzić, czy zostało ono prawidłowo skonfigurowane
• Wywoływanie uwierzytelnionej funkcji z lokalnego środowiska programistycznego przez podanie tokena tożsamości gcloud
• Jak utworzyć konto usługi i przypisać mu odpowiednią rolę do wywoływania funkcji
• Jak przyjmować tożsamość usługi w lokalnym środowisku programistycznym, które ma odpowiednie role do wywoływania funkcji

8. Czyszczenie danych

Aby uniknąć przypadkowych opłat (np. gdy ta funkcja w Cloud Functions zostanie przypadkowo wywołana więcej razy niż miesięczny limit wywołań funkcji w Cloud Functions w warstwie bezpłatnej), możesz usunąć funkcję w Cloud Functions lub projekt utworzony w kroku 2.

Aby przestać podszywać się pod konto usługi, możesz zalogować się ponownie, używając swojej tożsamości:

gcloud auth application-default login

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

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

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