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

۱. مقدمه

نمای کلی

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

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

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

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

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

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

پیش‌نیازها

• شما وارد کنسول ابری شده‌اید
• شما قبلاً یک تابع ابری نسل دوم مبتنی بر 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 انجام می‌دهید، بخش «تنظیم اعتبارنامه‌های پیش‌فرض برنامه» را دنبال کنید.

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

این آزمایشگاه کد از همان دستورالعمل‌های Console Quickstart برای توابع ابری پیروی می‌کند، با یک استثنای قابل توجه: تابع شما نیاز به احراز هویت دارد.

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

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

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

1. به صفحه مرور کلی توابع ابری بروید و روی ایجاد تابع کلیک کنید
2. در قسمت Environment ، نسل دوم (2nd gen) را انتخاب کنید.
3. نام تابع را my-authenticated-function بگذارید.
4. در فیلد احراز هویت، مقدار پیش‌فرض را روی «نیاز به احراز هویت» بگذارید.

5. روی بعدی کلیک کنید
6. برای این codelab، می‌توانید هر زبانی را انتخاب کنید
7. سپس روی Deploy کلیک کنید

تقریباً ۱ دقیقه طول می‌کشد تا تابع شما فعال شود.

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

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

شما باید ناحیه تابع خود را مشخص کنید. در این مثال us-central1 استفاده شده است.

REGION="us-central1"

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

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

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

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

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

curl $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`

پس از تأیید هویت صحیح، ایمیل حساب را در یک متغیر محیطی ذخیره خواهید کرد.

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

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

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

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

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

Hello World!

عیب‌یابی

اگر خطای ۴۰۳ Forbidden دریافت کردید، مطمئن شوید که هویت شما نقش Cloud Functions Invoker یا 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 Function Authentication codelab"

و به حساب سرویس، نقش فراخوانی‌کننده‌ی تابع ابری (Cloud Function invoker) را اعطا کنید.

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

از شما پرسیده می‌شود که آیا می‌خواهید به حساب سرویس، نقش اضافی برای Cloud Run Invoker بدهید یا خیر. برای افزودن نقش Cloud Run Invoker ، «y» را فشار دهید یا Enter را بزنید .

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

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

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

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

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

npm init

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

npm install google-auth-library

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

echo $FUNCTION_URL

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

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

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

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

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

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

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

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

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

۸. تمیز کردن

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

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

gcloud auth application-default login

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

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

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