نحوه فراخوانی توابع Cloud Run احراز هویت شده را بیاموزید

۱. مقدمه

نمای کلی

توابع Cloud Run یک راهکار محاسباتی سبک برای توسعه‌دهندگان است تا توابع تک‌منظوره و مستقلی ایجاد کنند که می‌توانند با استفاده از HTTPS فعال شوند یا بدون نیاز به مدیریت سرور یا محیط زمان اجرا، به CloudEvents پاسخ دهند. برای کسب اطلاعات بیشتر در مورد توابع Cloud Run به پست وبلاگ ما مراجعه کنید.

دو رویکرد اصلی برای کنترل فراخوانی توابع Cloud Run وجود دارد: ایمن‌سازی دسترسی بر اساس هویت و ایمن‌سازی دسترسی با استفاده از کنترل‌های دسترسی مبتنی بر شبکه . این آزمایشگاه کد بر رویکرد اول تمرکز دارد و شما را با ۳ سناریو برای ایمن‌سازی دسترسی بر اساس هویت برای فراخوانی یک تابع آشنا می‌کند:

1. از توکن هویت gcloud خود برای فراخوانی یک تابع برای اهداف توسعه و آزمایش محلی استفاده کنید
2. هنگام توسعه و آزمایش محلی، یک حساب کاربری سرویس را جعل هویت کنید تا از همان اعتبارنامه‌های موجود در محیط عملیاتی استفاده کنید.
3. از کتابخانه‌های کلاینت گوگل برای مدیریت احراز هویت در APIهای گوگل کلود استفاده کنید، مثلاً وقتی یک سرویس نیاز به فراخوانی یک تابع دارد

آنچه یاد خواهید گرفت

• نحوه پیکربندی احراز هویت در عملکرد Cloud Run و تأیید صحت پیکربندی احراز هویت
• با ارائه توکن برای هویت gcloud خود، یک تابع احراز هویت شده را از یک محیط توسعه محلی فراخوانی کنید.
• نحوه ایجاد یک حساب کاربری سرویس و اعطای نقش مناسب برای فراخوانی یک تابع به آن
• نحوه جعل هویت یک سرویس از یک محیط توسعه محلی که نقش‌های مناسبی برای فراخوانی یک تابع دارد

۲. تنظیمات و الزامات

پیش‌نیازها

• شما وارد کنسول ابری شده‌اید
• شما قبلاً یک تابع Cloud Run مبتنی بر HTTP را مستقر کرده‌اید. به مثال شروع سریع مراجعه کنید.
• (اختیاری) برای سناریوی سوم، این آزمایشگاه کد از Node.js و npm به عنوان مثال استفاده می‌کند، اما شما می‌توانید از هر محیط اجرایی که توسط کتابخانه‌های کلاینت Google Auth پشتیبانی می‌شود، استفاده کنید.

فعال کردن پوسته ابری

1. از کنسول ابری، روی فعال کردن پوسته ابری کلیک کنید .

اگر این اولین باری است که Cloud Shell را اجرا می‌کنید، یک صفحه میانی برای توضیح آن به شما نمایش داده می‌شود. اگر با یک صفحه میانی مواجه شدید، روی ادامه کلیک کنید.

آماده‌سازی و اتصال به Cloud Shell فقط چند لحظه طول می‌کشد.

این ماشین مجازی مجهز به تمام ابزارهای توسعه مورد نیاز است. این ماشین یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه می‌دهد و در فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی افزایش می‌دهد. بخش عمده‌ای از کار شما در این آزمایشگاه کد، اگر نگوییم همه، را می‌توان با یک مرورگر انجام داد.

پس از اتصال به Cloud Shell، باید ببینید که احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است.

2. برای تأیید احراز هویت، دستور زیر را در Cloud Shell اجرا کنید:

gcloud auth list

خروجی دستور

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

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

توجه: ابزار خط فرمان gcloud ، ابزار خط فرمان قدرتمند و یکپارچه در Google Cloud است. این ابزار به صورت پیش‌فرض در Cloud Shell نصب شده است. متوجه پشتیبانی آن از تکمیل تب خواهید شد. برای اطلاعات بیشتر، به نمای کلی ابزار خط فرمان gcloud مراجعه کنید.

3. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد:

gcloud config list project

خروجی دستور

[core]
project = <PROJECT_ID>

اگر اینطور نیست، می‌توانید با این دستور آن را تنظیم کنید:

gcloud config set project <PROJECT_ID>

خروجی دستور

Updated property [core/project].

توجه: اگر این آموزش را خارج از Cloud Shell انجام می‌دهید، بخش «تنظیم اعتبارنامه‌های پیش‌فرض برنامه» را دنبال کنید.

۳. یک تابع Cloud Run احراز هویت شده ایجاد و آزمایش کنید

نیاز به احراز هویت به این معنی است که اصلی که تابع را فراخوانی می‌کند باید نقش Cloud Run Invoker را داشته باشد؛ در غیر این صورت، تابع خطای ۴۰۳ Forbidden را برمی‌گرداند. این آزمایشگاه کد نحوه اعطای نقش‌های Invoker مناسب به یک اصل را نشان می‌دهد.

تنظیم متغیرهای محیطی محلی برای دستورات ساده gcloud

ابتدا، چند متغیر محیطی ایجاد خواهید کرد تا خوانایی دستورات gcloud مورد استفاده در این آزمایشگاه کد را بهبود بخشید.

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

کد منبع تابع را ایجاد کنید

اگرچه این آزمایشگاه کد از Node.js استفاده می‌کند، شما می‌توانید از هر محیط اجرایی که توسط کتابخانه‌های کلاینت Google Auth پشتیبانی می‌شود، استفاده کنید.

ابتدا یک دایرکتوری ایجاد کنید و با دستور cd به آن دایرکتوری بروید.

mkdir auth-function-codelab && cd $_

سپس، فایل package.json را ایجاد کنید.

touch package.json

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

در مرحله بعد، فایل منبع 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

تابع احراز هویت شده را ایجاد کنید

در اینجا مراحل ایجاد یک تابع احراز هویت شده برای محیط اجرایی nodejs20 آمده است. با این حال، می‌توانید از هر محیط اجرایی که توسط کتابخانه‌های کلاینت Google Auth پشتیبانی می‌شود، استفاده کنید.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

برای استقرار مستقیم یک تابع Cloud Run روی Cloud Run، دستور زیر را اجرا کنید:

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

و سپس می‌توانید URL تابع را به عنوان یک متغیر محیطی ذخیره کنید تا بعداً از آن استفاده کنید.

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

اگر ترجیح می‌دهید به عنوان یک Cloud Functions نسل دوم مستقر شوید، از دستور زیر استفاده کنید:

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

و سپس می‌توانید URL تابع را به عنوان یک متغیر محیطی ذخیره کنید تا بعداً از آن استفاده کنید.

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

با تلاش برای فراخوانی به عنوان یک فراخوانی‌کننده ناشناس، تأیید کنید که تابع نیاز به احراز هویت دارد

شما تابع را بدون احراز هویت فراخوانی خواهید کرد تا تأیید کنید که خطای ۴۰۳ مورد انتظار را دریافت می‌کنید.

از خط فرمان، دستور curl زیر را اجرا کنید:

curl -i $FUNCTION_URL

نتیجه زیر را مشاهده خواهید کرد:

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

اکنون آماده‌اید تا 3 سناریو را بررسی کنید که در آن‌ها می‌توانید با ارائه احراز هویت، تابع خود را فراخوانی کنید.

۴. سناریو ۱: از توکن هویت gcloud خود استفاده کنید

به عنوان یک توسعه‌دهنده، شما به روشی برای آزمایش تابع خود در حین توسعه محلی آن نیاز خواهید داشت. در این بخش، یک آزمایش سریع انجام خواهید داد تا تأیید کنید که تابع به درستی با استفاده از هویت خودتان تأیید شده است.

با اجرای دستور زیر، تأیید کنید که با استفاده از gcloud احراز هویت شده‌اید:

gcloud auth list

شما باید یک ستاره در کنار هویت فعال خود ببینید، برای مثال:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

می‌توانید اطلاعات بیشتری در مورد تنظیم gcloud init و gcloud auth login را در مستندات بیابید.

در مرحله بعد، تابع را فراخوانی کنید و توکن هویت خود را به آن ارسال کنید.

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

حالا نتیجه را خواهید دید:

Hello World!

عیب‌یابی

اگر خطای ۴۰۳ Forbidden دریافت کردید، مطمئن شوید که هویت شما نقش Cloud Run Invoker را دارد. می‌توانید از کنسول IAM برای تأیید نقش‌های داده شده به یک مدیر اصلی استفاده کنید.

اگرچه استفاده از توکن هویت خودتان راهی سریع برای آزمایش تابع شما در حین توسعه است، اما فراخوانی‌کننده تابع احراز هویت‌شده شما به نقش‌های مناسب نیاز دارد؛ در غیر این صورت، فراخوانی‌کننده خطای ۴۰۳ Forbidden را دریافت خواهد کرد.

شما باید با محدود کردن تعداد هویت‌ها و حساب‌های سرویس که نقش‌هایی برای فراخوانی تابع دارند ، از اصل حداقل امتیاز پیروی کنید. در سناریوی بعدی، یاد خواهید گرفت که چگونه یک حساب سرویس جدید ایجاد کنید و نقش‌های مناسب را برای فراخوانی تابع به آن اعطا کنید.

۵. سناریو ۲: جعل هویت یک حساب کاربری سرویس

در این سناریو، شما یک حساب کاربری سرویس را جعل هویت می‌کنید (یعنی مجوزهای آن را در نظر می‌گیرید) تا یک تابع را هنگام توسعه و آزمایش محلی فراخوانی کنید. با جعل هویت یک حساب کاربری سرویس، می‌توانید تابع خود را با همان اعتبارنامه‌هایی که در محیط عملیاتی وجود دارد، آزمایش کنید.

با انجام این کار، نه تنها نقش‌ها را تأیید می‌کنید، بلکه با عدم نیاز به اعطای نقش Cloud Function Invoker به سایر هویت‌ها صرفاً برای اهداف آزمایش محلی، از اصل حداقل امتیاز نیز پیروی خواهید کرد.

برای اهداف این آزمایشگاه کد، شما یک حساب کاربری سرویس جدید ایجاد خواهید کرد که فقط نقش‌هایی برای فراخوانی تابعی که در این آزمایشگاه کد ایجاد کرده‌اید، دارد.

ایجاد حساب کاربری سرویس جدید

ابتدا، چند متغیر محیطی اضافی برای نمایش حساب‌های سرویس مورد استفاده در دستورات gcloud ایجاد خواهید کرد.

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

در مرحله بعد، حساب کاربری سرویس را ایجاد خواهید کرد.

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

و به حساب سرویس Cloud Run نقش فراخوانی کننده (invoker) را اعطا کنید:

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

با جعل هویت حساب سرویس، تابع را فراخوانی کنید

برای این کار، با دریافت شناسه حساب کاربری سرویس تازه ایجاد شده، آن را جعل هویت خواهید کرد.

اضافه کردن نقش‌های مورد نیاز برای جعل هویت

برای جعل هویت یک حساب سرویس، حساب کاربری شما باید نقش Service Account Token Creator (roles/iam.serviceAccountTokenCreator) را داشته باشد تا بتواند یک شناسه توکن برای حساب سرویس ایجاد کند.

شما می‌توانید دستورات زیر را برای اعطای این نقش به حساب کاربری فعال خود اجرا کنید:

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'

از توکن شناسه حساب سرویس استفاده کنید

چند دقیقه صبر کنید تا مجوزها منتشر شوند. اکنون می‌توانید با ارسال شناسه‌ی حساب کاربری سرویس، تابع را فراخوانی کنید.

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

و موارد زیر را مشاهده خواهید کرد:

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!

۶. سناریو ۳: استفاده از کتابخانه‌های کلاینت گوگل

برای این بخش آخر از آزمایشگاه کد، شما یک سرویس کوچک را به صورت محلی اجرا خواهید کرد تا یک توکن شناسه برای یک حساب سرویس تولید کند و سپس با استفاده از کتابخانه‌های کلاینت Google Auth و Application Default Credentials (ADC) به صورت برنامه‌نویسی شده تابع را فراخوانی کنید. می‌توانید اطلاعات بیشتر در مورد کتابخانه‌های کلاینت گوگل را در بخش «توضیح کتابخانه‌های کلاینت» در مستندات مطالعه کنید.

استفاده از ADC به ویژه زمانی اهمیت دارد که می‌خواهید تابع خود را به صورت محلی (مثلاً روی لپ‌تاپ، در Cloud Shell و غیره) بنویسید و آزمایش کنید، در حالی که با سایر منابع Google Cloud (مثلاً Cloud Storage، Vision API و غیره) در تعامل هستید. در این مثال، خواهید دید که چگونه یک سرویس، تابع دیگری را که نیاز به احراز هویت دارد، فراخوانی کند. برای اطلاعات بیشتر در مورد ADC و توسعه محلی، به پست وبلاگ «چگونه توابع Cloud خود را به صورت محلی توسعه داده و آزمایش کنیم | وبلاگ Google Cloud» مراجعه کنید.

دستور gcloud را برای جعل هویت یک حساب سرویس اجرا کنید

ADC به طور خودکار اعتبارنامه‌ها را بر اساس محیط برنامه پیدا می‌کند و از آن اعتبارنامه‌ها برای احراز هویت در APIهای Google Cloud استفاده می‌کند. پرچم –impersonate-service-account به شما امکان می‌دهد تا با استفاده از هویت یک حساب کاربری سرویس، آن را برای احراز هویت در برابر APIهای Google Cloud جعل هویت کنید.

برای جعل هویت یک حساب کاربری سرویس، می‌توانید دستور زیر را اجرا کنید:

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

اکنون شما به جای هویت خود، دستورات gcloud را به عنوان آن حساب سرویس اجرا می‌کنید.

ایجاد و اجرای یک سرویس برای فراخوانی یک تابع احراز هویت شده

هر محیط اجرا، کتابخانه کلاینت Google Auth مخصوص به خود را دارد که می‌توانید آن را نصب کنید. این codelab شما را در ایجاد و اجرای یک برنامه Node.js به صورت محلی راهنمایی می‌کند.

مراحل Node.js به شرح زیر است:

1. ایجاد یک دایرکتوری جدید

mkdir local-dev && cd $_

2. یک برنامه Node.js جدید ایجاد کنید

npm init -y

3. کتابخانه کلاینت Google Auth را نصب کنید

npm install google-auth-library

4. یک فایل index.js ایجاد کنید
5. آدرس اینترنتی تابع Cloud Run خود را که در مرحله بعد به کد خود اضافه خواهید کرد، بازیابی کنید.

echo $FUNCTION_URL

6. کد زیر را به index.js اضافه کنید. مطمئن شوید که متغیر targetAudience را به آدرس تابع Cloud Run خود تغییر می‌دهید.

ایندکس.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. برنامه را اجرا کنید

node index.js

و شما باید نتیجه‌ی "Hello World!" را ببینید.

عیب‌یابی

اگر خطای Permission 'iam.serviceAccounts.getOpenIdToken' denied on resource (یا ممکن است وجود نداشته باشد) را مشاهده کردید، لطفاً چند دقیقه صبر کنید تا نقش Service Account Token Creator منتشر شود.

اگر خطای «نمی‌توانید شناسه توکن را در این محیط دریافت کنید، از GCE استفاده کنید یا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی یک فایل JSON مربوط به اعتبارنامه‌های حساب سرویس تنظیم کنید» دریافت کردید، ممکن است اجرای دستور را فراموش کرده باشید.

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

۷. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات مربوط به نحوه ایمن‌سازی عملکردهای Cloud Run را بررسی کنید.

ما همچنین این پست وبلاگ در مورد توسعه محلی با توابع Cloud Run را توصیه می‌کنیم تا یاد بگیرید چگونه تابع Cloud Run خود را در محیط توسعه محلی خود توسعه داده و آزمایش کنید.

آنچه ما پوشش داده‌ایم

• نحوه پیکربندی احراز هویت در عملکرد Cloud Run و تأیید صحت پیکربندی احراز هویت
• با ارائه توکن برای هویت gcloud خود، یک تابع احراز هویت شده را از یک محیط توسعه محلی فراخوانی کنید.
• نحوه ایجاد یک حساب کاربری سرویس و اعطای نقش مناسب برای فراخوانی یک تابع به آن
• نحوه جعل هویت یک سرویس از یک محیط توسعه محلی که نقش‌های مناسبی برای فراخوانی یک تابع دارد

۸. تمیز کردن

برای جلوگیری از هزینه‌های ناخواسته، (برای مثال، این تابع ابری ناخواسته بیشتر از تخصیص فراخوانی تابع Cloud Run ماهانه شما در سطح رایگان فراخوانی می‌شود)، می‌توانید تابع ابری یا پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید، حذف کنید.

برای متوقف کردن جعل هویت حساب سرویس، می‌توانید با استفاده از هویت خود دوباره وارد سیستم شوید:

gcloud auth application-default login

برای حذف عملکرد Cloud Run، به عملکرد Cloud Run در Cloud Console در آدرس https://console.cloud.google.com/functions/ بروید. مطمئن شوید پروژه‌ای که در مرحله ۲ ایجاد کرده‌اید، پروژه انتخاب شده فعلی است.

تابع my-authenticated-function که قبلاً پیاده‌سازی کردید را انتخاب کنید. سپس روی Delete کلیک کنید.

اگر تصمیم به حذف کل پروژه دارید، می‌توانید به آدرس https://console.cloud.google.com/cloud-resource-manager بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و گزینه Delete را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید.