Mempelajari cara memanggil fungsi Cloud Run yang diautentikasi

1. Pengantar

Ringkasan

Fungsi Cloud Run adalah solusi komputasi ringan bagi developer untuk membuat fungsi mandiri dengan tujuan tunggal yang dapat dipicu menggunakan HTTPS atau merespons CloudEvents tanpa perlu mengelola lingkungan server atau runtime. Pelajari lebih lanjut fungsi Cloud Run di postingan blog kami.

Ada dua pendekatan utama untuk mengontrol pemanggilan ke fungsi Cloud Run: mengamankan akses berdasarkan identitas dan mengamankan akses menggunakan kontrol akses berbasis jaringan. Codelab ini berfokus pada pendekatan pertama dan memandu Anda melalui 3 skenario untuk mengamankan akses berdasarkan identitas guna memanggil fungsi:

1. Menggunakan token identitas gcloud Anda untuk memanggil fungsi untuk tujuan pengembangan &pengujian lokal
2. Meniru identitas akun layanan saat mengembangkan dan menguji secara lokal untuk menggunakan kredensial yang sama seperti dalam produksi
3. Menggunakan library klien Google untuk menangani autentikasi ke Google Cloud API, misalnya saat layanan perlu memanggil fungsi

Yang akan Anda pelajari

• Cara mengonfigurasi autentikasi pada fungsi Cloud Run dan memverifikasi bahwa autentikasi telah dikonfigurasi dengan benar
• Memanggil fungsi yang diautentikasi dari lingkungan pengembangan lokal dengan memberikan token untuk identitas gcloud Anda
• Cara membuat akun layanan dan memberinya peran yang sesuai untuk memanggil fungsi
• Cara meniru identitas layanan dari lingkungan pengembangan lokal yang memiliki peran yang sesuai untuk memanggil suatu fungsi

2. Penyiapan dan Persyaratan

Prasyarat

• Anda sudah login ke Konsol Cloud
• Sebelumnya, Anda telah men-deploy fungsi Cloud Run yang dipicu HTTP. Lihat contoh panduan memulai.
• (opsional) Untuk skenario ke-3, codelab ini menggunakan Node.js dan npm sebagai contoh, tetapi Anda dapat menggunakan runtime apa pun yang didukung oleh library klien Google Auth.

Mengaktifkan Cloud Shell

1. Dari Cloud Console, klik Aktifkan Cloud Shell .

Jika ini adalah pertama kalinya Anda memulai Cloud Shell, Anda akan melihat layar perantara yang menjelaskan apa itu Cloud Shell. Jika Anda melihat layar perantara, klik Lanjutkan.

Perlu waktu beberapa saat untuk penyediaan dan terhubung ke Cloud Shell.

Mesin virtual ini dimuat dengan semua alat pengembangan yang diperlukan. VM ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Sebagian besar pekerjaan Anda dalam codelab ini dapat dilakukan dengan browser.

Setelah terhubung ke Cloud Shell, Anda akan melihat bahwa Anda telah diautentikasi dan project sudah ditetapkan ke project ID Anda.

2. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa Anda telah diautentikasi:

gcloud auth list

Output perintah

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

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

Catatan: Alat command-line gcloud adalah alat command-line yang canggih dan terpadu di Google Cloud. Alat ini sudah diinstal lebih dulu di Cloud Shell. Anda akan melihat dukungannya untuk penyelesaian tab. Untuk mengetahui informasi selengkapnya, baca ringkasan alat command line gcloud.

3. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda:

gcloud config list project

Output perintah

[core]
project = <PROJECT_ID>

Jika tidak, Anda dapat menyetelnya dengan perintah ini:

gcloud config set project <PROJECT_ID>

Output perintah

Updated property [core/project].

Catatan: Jika Anda menyelesaikan tutorial ini di luar Cloud Shell, ikuti Menyiapkan Kredensial Default Aplikasi.

3. Membuat dan menguji fungsi Cloud Run yang diautentikasi

Memerlukan autentikasi berarti prinsip yang memanggil fungsi harus memiliki peran Cloud Run Invoker; jika tidak, fungsi akan menampilkan error 403 Forbidden. Codelab ini akan menunjukkan cara memberikan peran Invoker yang sesuai kepada akun utama.

Menyiapkan variabel lingkungan lokal untuk perintah gcloud yang disederhanakan

Pertama, Anda akan membuat beberapa variabel lingkungan untuk meningkatkan keterbacaan perintah gcloud yang digunakan dalam codelab ini.

REGION=us-central1
PROJECT_ID=$(gcloud config get-value project)

Membuat kode sumber untuk fungsi

Meskipun codelab ini menggunakan Node.js, Anda dapat menggunakan runtime apa pun yang didukung oleh library klien Google Auth.

Pertama, buat direktori dan cd ke direktori tersebut.

mkdir auth-function-codelab && cd $_

Kemudian, buat file package.json.

touch package.json

echo '{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
' > package.json

Selanjutnya, buat file sumber 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

Membuat fungsi terautentikasi

Berikut adalah langkah-langkah membuat fungsi terautentikasi untuk runtime nodejs20. Namun, Anda dapat menggunakan runtime apa pun yang didukung oleh library klien Google Auth.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

Untuk men-deploy fungsi Cloud Run langsung ke Cloud Run, jalankan perintah berikut:

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated

lalu Anda dapat menyimpan URL fungsi sebagai variabel lingkungan untuk digunakan nanti.

FUNCTION_URL="$(gcloud run services describe $FUNCTION_NAME --region $REGION --format 'value(status.url)')"

Jika Anda lebih memilih untuk men-deploy sebagai Cloud Functions generasi ke-2, gunakan perintah berikut:

gcloud functions deploy nodejs-http-function \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated

lalu Anda dapat menyimpan URL fungsi sebagai variabel lingkungan untuk digunakan nanti.

FUNCTION_URL="$(gcloud functions describe $FUNCTION_NAME --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

Memverifikasi bahwa fungsi memerlukan autentikasi dengan mencoba memanggil sebagai pemanggil anonim

Anda akan memanggil fungsi tanpa autentikasi untuk memverifikasi bahwa Anda menerima error 403 yang diharapkan.

Dari command line, jalankan perintah curl berikut:

curl -i $FUNCTION_URL

Anda akan melihat hasil berikut:

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

Sekarang Anda siap untuk mempelajari 3 skenario tempat Anda dapat memanggil Fungsi dengan memberikan autentikasi.

4. Skenario 1: Menggunakan token identitas gcloud

Sebagai developer, Anda memerlukan cara untuk menguji fungsi saat mengembangkannya secara lokal. Di bagian ini, Anda akan melakukan pengujian cepat untuk memverifikasi bahwa fungsi diautentikasi dengan benar menggunakan identitas Anda sendiri.

Pastikan Anda diautentikasi menggunakan gcloud dengan menjalankan perintah berikut:

gcloud auth list

Anda akan melihat tanda bintang di samping identitas aktif, misalnya:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Anda dapat menemukan informasi selengkapnya tentang menyiapkan gcloud init dan gcloud auth login dalam dokumen.

Selanjutnya, panggil Fungsi dan teruskan token identitas Anda.

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

Sekarang Anda akan melihat hasilnya:

Hello World!

Pemecahan masalah

Jika Anda menerima error 403 Forbidden, pastikan identitas Anda memiliki peran Cloud Run Invoker. Anda dapat menggunakan konsol IAM untuk memverifikasi peran yang diberikan kepada akun utama.

Meskipun menggunakan token identitas Anda sendiri adalah cara cepat untuk menguji fungsi selama pengembangan, pemanggil fungsi yang diautentikasi akan memerlukan peran yang sesuai; jika tidak, pemanggil akan menerima error 403 Forbidden.

Anda harus mengikuti prinsip hak istimewa terendah dengan membatasi jumlah identitas dan akun layanan yang memiliki peran untuk memanggil fungsi. Dalam skenario berikutnya, Anda akan mempelajari cara membuat akun layanan baru dan memberikan peran yang sesuai untuk memanggil fungsi.

5. Skenario 2: Meniru identitas akun layanan

Dalam skenario ini, Anda akan meniru identitas (yaitu mengasumsikan izin) akun layanan untuk memanggil fungsi saat mengembangkan dan menguji secara lokal. Dengan meniru identitas akun layanan, Anda dapat menguji fungsi dengan kredensial yang sama seperti dalam produksi.

Dengan melakukan hal ini, Anda tidak hanya memverifikasi peran, tetapi juga mengikuti prinsip hak istimewa terendah dengan tidak harus memberikan peran Invoker Cloud Function ke identitas lain hanya untuk tujuan pengujian lokal.

Untuk tujuan codelab ini, Anda akan membuat akun layanan baru yang hanya memiliki peran untuk memanggil fungsi yang dibuat di codelab ini.

Buat akun layanan baru

Pertama, Anda akan membuat beberapa variabel lingkungan tambahan untuk mewakili akun layanan yang digunakan dalam perintah gcloud.

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

Selanjutnya, Anda akan membuat akun layanan.

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

Dan berikan peran Cloud Run invoker ke akun layanan:

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1  \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/run.invoker'

Memanggil fungsi dengan meniru identitas akun layanan

Untuk itu, Anda akan meniru identitas akun layanan yang baru dibuat dengan mendapatkan token ID-nya.

Menambahkan peran yang diperlukan untuk peniruan identitas

Untuk meniru identitas akun layanan, akun pengguna Anda harus memiliki peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) untuk membuat token ID untuk akun layanan.

Anda dapat menjalankan perintah berikut untuk memberikan peran ini ke akun pengguna aktif:

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'

Menggunakan token ID akun layanan

Tunggu beberapa menit hingga izin diterapkan. Sekarang, Anda dapat memanggil Function dengan meneruskan token ID akun layanan.

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

Dan Anda akan melihat hal berikut:

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. Skenario 3: Menggunakan library klien Google

Untuk bagian terakhir codelab ini, Anda akan menjalankan layanan kecil secara lokal guna membuat token ID untuk akun layanan, lalu memanggil Function secara terprogram menggunakan library klien Google Auth dan Kredensial Default Aplikasi (ADC). Anda dapat membaca lebih lanjut library klien Google di bagian penjelasan library klien dalam dokumen.

Penggunaan ADC sangat penting jika Anda ingin menulis dan menguji Fungsi secara lokal (misalnya, di laptop, di Cloud Shell, dll.) saat berinteraksi dengan resource Google Cloud lainnya (misalnya, Cloud Storage, Vision API, dll.) Untuk contoh ini, Anda akan melihat cara membuat layanan memanggil Fungsi lain yang memerlukan autentikasi. Untuk mengetahui info selengkapnya tentang ADC dan pengembangan lokal, lihat postingan blog Cara mengembangkan dan menguji Cloud Functions secara lokal | Blog Google Cloud

Menjalankan perintah gcloud untuk meniru identitas akun layanan

ADC otomatis menemukan kredensial berdasarkan lingkungan aplikasi dan menggunakan kredensial tersebut untuk melakukan autentikasi ke Google Cloud API. Flag –impersonate-service-account memungkinkan Anda meniru akun layanan dengan menggunakan identitasnya untuk autentikasi terhadap Google Cloud API.

Untuk meniru identitas akun layanan, Anda dapat menjalankan perintah berikut:

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

Sekarang Anda menjalankan perintah gcloud sebagai akun layanan tersebut, bukan sebagai identitas Anda.

Membuat dan menjalankan layanan untuk memanggil fungsi yang diautentikasi

Setiap runtime memiliki library klien Google Auth sendiri yang dapat Anda instal. Codelab ini memandu Anda membuat dan menjalankan aplikasi Node.js secara lokal.

Berikut adalah langkah-langkah untuk Node.js:

1. Membuat direktori baru

mkdir local-dev && cd $_

2. Membuat aplikasi Node.js baru

npm init -y

3. Menginstal library klien Google Auth

npm install google-auth-library

4. Membuat file index.js
5. Ambil URL fungsi Cloud Run Anda, yang akan ditambahkan ke kode pada langkah berikut.

echo $FUNCTION_URL

6. Tambahkan kode berikut ke index.js. Pastikan untuk mengubah variabel targetAudience ke URL fungsi Cloud Run Anda.

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. Menjalankan aplikasi

node index.js

Anda akan melihat pesan "Hello World!" yang muncul

Pemecahan masalah

Jika Anda melihat error Izin 'iam.serviceAccounts.getOpenIdToken' ditolak pada resource (atau mungkin tidak ada), tunggu beberapa menit hingga peran Service Account Token Creator diterapkan.

Jika Anda menerima error Tidak dapat mengambil token ID di lingkungan ini, gunakan GCE atau tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke file JSON kredensial akun layanan, Anda mungkin lupa menjalankan perintah

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

7. Selamat!

Selamat, Anda telah menyelesaikan codelab.

Sebaiknya tinjau dokumentasi tentang cara mengamankan fungsi Cloud Run.

Sebaiknya baca juga postingan blog tentang pengembangan lokal dengan fungsi Cloud Run untuk mempelajari cara mengembangkan dan menguji fungsi Cloud Run di lingkungan developer lokal Anda.

Yang telah kita bahas

• Cara mengonfigurasi autentikasi pada fungsi Cloud Run dan memastikan autentikasi telah dikonfigurasi dengan benar
• Memanggil fungsi yang diautentikasi dari lingkungan pengembangan lokal dengan memberikan token untuk identitas gcloud Anda
• Cara membuat akun layanan dan memberinya peran yang sesuai untuk memanggil fungsi
• Cara meniru identitas layanan dari lingkungan pengembangan lokal yang memiliki peran yang sesuai untuk memanggil fungsi

8. Pembersihan

Untuk menghindari tagihan yang tidak disengaja, (misalnya, Cloud Function ini tidak sengaja dipanggil lebih dari alokasi pemanggilan fungsi Cloud Run bulanan Anda di paket gratis), Anda dapat menghapus Cloud Function atau menghapus project yang Anda buat di Langkah 2.

Untuk berhenti meniru identitas akun layanan, Anda dapat login kembali menggunakan identitas Anda:

gcloud auth application-default login

Untuk menghapus fungsi Cloud Run, buka Konsol Cloud fungsi Cloud Run di https://console.cloud.google.com/functions/ Pastikan project yang Anda buat pada langkah 2 adalah project yang sedang dipilih.

Pilih my-authenticated-function yang Anda deploy sebelumnya. Kemudian, tekan Hapus.

Jika memilih untuk menghapus seluruh project, Anda dapat membuka https://console.cloud.google.com/cloud-resource-manager, memilih project yang Anda buat di Langkah 2, lalu memilih Hapus. Jika menghapus project, Anda harus mengubah project di Cloud SDK. Anda dapat melihat daftar semua project yang tersedia dengan menjalankan gcloud projects list.