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

1. مقدمه

نمای کلی

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

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

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

چیزی که یاد خواهید گرفت

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

2. راه اندازی و الزامات

پیش نیازها

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

Cloud Shell را فعال کنید

1. از Cloud Console، روی Activate Cloud Shell کلیک کنید .

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

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

این ماشین مجازی با تمام ابزارهای توسعه مورد نیاز بارگذاری شده است. این یک فهرست اصلی 5 گیگابایتی دائمی ارائه می‌کند و در Google Cloud اجرا می‌شود، که عملکرد و احراز هویت شبکه را بسیار افزایش می‌دهد. بسیاری از کارهای شما، اگر نه همه، در این کد لبه با مرورگر قابل انجام است.

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

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 هستید، Set up Application Default Credentials را دنبال کنید.

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

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

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

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

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

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

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

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

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)')"

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

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)')"

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

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

از یک خط فرمان، دستور 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 سناریو هستید که می توانید با ارائه احراز هویت، تابع خود را فراخوانی کنید.

4. سناریوی 1: از رمز هویت 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 در Docs بیابید.

سپس، Function را فراخوانی کرده و رمز هویت خود را به آن ارسال کنید.

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

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

Hello World!

عیب یابی

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

اگرچه استفاده از رمز هویت خود راهی سریع برای آزمایش عملکرد شما در طول توسعه است، تماس گیرنده تابع تأیید شده شما به نقش های مناسب نیاز دارد. در غیر این صورت، تماس گیرنده خطای 403 Forbidden را دریافت می کند.

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

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

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

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

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

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

ابتدا، چند متغیر محیطی اضافی برای نمایش حساب‌های سرویس مورد استفاده در دستورات 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 اعطا کنید:

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'

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

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

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!

6. سناریوی 3: از کتابخانه های سرویس گیرنده گوگل استفاده کنید

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

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

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

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

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

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

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

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

هر زمان اجرا کتابخانه مشتری Google Auth خود را دارد که می توانید نصب کنید. این کد لبه شما را در ایجاد و اجرای یک برنامه 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. URL تابع Cloud Run خود را که در مرحله زیر به کد خود اضافه خواهید کرد، بازیابی کنید.

echo $FUNCTION_URL

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

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

node index.js

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

عیب یابی

اگر خطایی مشاهده کردید که مجوز «iam.serviceAccounts.getOpenIdToken» در منبع رد شده است (یا ممکن است وجود نداشته باشد). لطفاً چند دقیقه صبر کنید تا نقش ایجاد کننده رمز حساب حساب سرویس منتشر شود.

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

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

7. تبریک می گویم!

برای تکمیل کد لبه تبریک می گویم!

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

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

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

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

8. پاکسازی کنید

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

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

gcloud auth application-default login

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

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

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