التعرُّف على كيفية استدعاء دوال السحابة الإلكترونية التي تمت مصادقتها

1. مقدمة

نظرة عامة

Cloud Functions هي حلّ حوسبة خفيف الوزن يتيح للمطوّرين إنشاء وظائف مستقلة ذات غرض واحد يمكن تشغيلها باستخدام HTTPS أو الاستجابة إلى CloudEvents بدون الحاجة إلى إدارة خادم أو بيئة وقت تشغيل.

هناك طريقتان رئيسيتان للتحكّم في عمليات استدعاء Cloud Functions: تأمين الوصول استنادًا إلى الهوية وتأمين الوصول باستخدام عناصر التحكّم في الوصول المستندة إلى الشبكة. يركّز هذا الدرس التطبيقي حول الترميز على الأسلوب الأول، ويشرح لك 3 سيناريوهات لتأمين الوصول استنادًا إلى الهوية من أجل استدعاء دالة:

استخدام رمز تعريف gcloud لاستدعاء دالة لأغراض التطوير والاختبار المحليَّين
انتحال هوية حساب خدمة عند التطوير والاختبار محليًا لاستخدام بيانات الاعتماد نفسها المستخدَمة في قناة الإصدار العلني
استخدِم مكتبات برامج Google للتعامل مع المصادقة على Cloud APIs، مثلاً عندما تحتاج إحدى الخدمات إلى استدعاء دالة.

ما ستتعلمه

كيفية ضبط المصادقة على إحدى "وظائف السحابة الإلكترونية" والتأكّد من ضبطها بشكلٍ سليم
استدعاء دالة مصادَق عليها من بيئة تطوير محلية من خلال تقديم الرمز المميز لهوية gcloud
كيفية إنشاء حساب خدمة ومنحه الدور المناسب لتنفيذ وظيفة
كيفية انتحال هوية خدمة من بيئة تطوير محلية تتضمّن الأدوار المناسبة لاستدعاء دالة

2. الإعداد والمتطلبات

المتطلبات الأساسية

تسجيل الدخول إلى Cloud Console
سبق لك نشر دالة Cloud Function من الجيل الثاني يتم تشغيلها عبر HTTP
(اختياري) بالنسبة إلى السيناريو الثالث، يستخدم هذا الدرس التطبيقي حول الترميز Node.js وnpm كمثال، ولكن يمكنك استخدام أي وقت تشغيل متوافق مع مكتبات برامج Google Auth.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهيتها. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات التطوير اللازمة. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم عملك في هذا الدرس العملي، إن لم يكن كله، باستخدام متصفح.

بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تم إثبات هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك.

نفِّذ الأمر التالي في 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`

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك:

gcloud config list project

ناتج الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

3- إنشاء وظيفة Cloud Functions مصادَق عليها واختبارها

يتّبع هذا الدرس التطبيقي حول الترميز التعليمات نفسها الواردة في دليل البدء السريع في Console لخدمة Cloud Functions، مع استثناء واحد مهم، وهو أنّ وظيفتك ستتطلّب المصادقة.

يعني اشتراط المصادقة أنّ الجهة الأساسية التي تستدعي الدالة يجب أن يكون لديها أدوار "مستدعي وظائف السحابة الإلكترونية" (و"مستدعي Cloud Run" للجيل الثاني)، وإلا ستعرض الدالة الخطأ "403: إجراء محظور". سيوضّح لك هذا الدرس التطبيقي حول الترميز كيفية منح أدوار المنفّذ المناسبة إلى كيان أساسي.

إنشاء الدالة التي تتطلّب المصادقة

في ما يلي خطوات استخدام Cloud Console:

انتقِل إلى صفحة نظرة عامة على Cloud Functions وانقر على إنشاء دالة.
ضمن خيار البيئة، اختَر الجيل الثاني.
أدخِل اسم الدالة my-authenticated-function
في حقل "المصادقة"، اترك القيمة التلقائية طلب المصادقة.

انقر على Next (التالي).
يمكنك اختيار أي لغة لهذا الدرس التطبيقي حول الترميز
ثم انقر على نشر.

يستغرق نشر الدالة دقيقة واحدة تقريبًا.

إعداد متغيرات البيئة المحلية لتبسيط أوامر gcloud

أولاً، عليك إنشاء بعض متغيرات البيئة لتحسين إمكانية قراءة أوامر gcloud المستخدَمة في هذا الدرس التطبيقي حول الترميز.

عليك تحديد المنطقة التي تريد أن تعمل فيها الدالة. يستخدم هذا المثال us-central1.

REGION="us-central1"

بعد ذلك، يمكنك حفظ عنوان URL للدالة كمتغير بيئة لاستخدامه لاحقًا.

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

تأكَّد من أنّ الدالة تتطلّب المصادقة من خلال محاولة استدعائها كمستخدم مجهول

ستستدعي الدالة بدون مصادقة للتحقّق من تلقّي الخطأ المتوقّع 403.

من سطر الأوامر، شغِّل الأمر 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 سيناريوهات يمكنك فيها استدعاء الدالة من خلال تقديم المصادقة.

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`

بعد إثبات هويتك الصحيحة، عليك حفظ عنوان البريد الإلكتروني للحساب في متغيّر بيئة.

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!

تحديد المشاكل وحلّها

إذا تلقّيت الخطأ "403 Forbidden"، تأكَّد من أنّ هويتك لديها دور "منفّذ Cloud Functions" أو دور "منفّذ Cloud Run" للجيل الثاني من الدوال. يمكنك استخدام وحدة تحكّم إدارة الهوية وإمكانية الوصول للتحقّق من الأدوار الممنوحة لجهة رئيسية.

على الرغم من أنّ استخدام رمز مميّز خاص بهويتك هو طريقة سريعة لاختبار وظيفتك أثناء التطوير، يجب أن يحصل مستدعي الدالة التي تمت مصادقتها على الأدوار المناسبة، وإلا سيتلقّى المستدعي الخطأ 403 Forbidden.

عليك اتّباع مبدأ الحدّ الأدنى من الامتيازات من خلال الحدّ من عدد الهويات وحسابات الخدمة التي لديها أدوار لتنفيذ الوظيفة.

إنشاء حساب خدمة جديد ومنحه الأدوار اللازمة،

5- السيناريو 2: انتحال هوية حساب خدمة

في هذا السيناريو، عليك انتحال هوية حساب خدمة (أي الحصول على أذوناته) لاستدعاء إحدى الدوال عند التطوير والاختبار محليًا. من خلال انتحال هوية حساب خدمة، يمكنك اختبار وظيفتك باستخدام بيانات الاعتماد نفسها المستخدَمة في مرحلة الإنتاج.

من خلال إجراء ذلك، لن تتمكّن من إثبات صحة الأدوار فحسب، بل ستتّبع أيضًا مبدأ الحدّ الأدنى من الامتيازات من خلال عدم الحاجة إلى منح دور "مستدعي وظائف السحابة الإلكترونية" لهويات أخرى لأغراض الاختبار المحلي فقط.

لأغراض هذا الدرس التطبيقي حول الترميز، عليك إنشاء حساب خدمة جديد يتضمّن أدوارًا فقط لاستدعاء الدالة التي أنشأتها في هذا الدرس التطبيقي حول الترميز.

إنشاء حساب خدمة جديد

أولاً، عليك إنشاء متغيّري بيئة إضافيين لتمثيل حسابات الخدمة المستخدَمة في أوامر 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 Functions"

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

استدعاء الدالة من خلال انتحال هوية حساب الخدمة

لإجراء ذلك، عليك انتحال هوية حساب الخدمة الذي تم إنشاؤه حديثًا من خلال الحصول على رمز التعريف المميز الخاص به.

إضافة الأدوار المطلوبة لانتحال الهوية

لانتحال هوية حساب خدمة، يجب أن يتضمّن حساب المستخدم دور "منشئ الرموز المميزة لحساب الخدمة" (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!

6. السيناريو 3: استخدام مكتبات برامج Google

في الجزء الأخير من هذا الدرس التطبيقي حول الترميز، ستشغّل خدمة صغيرة محليًا لإنشاء رمز مميّز لتعريف حساب خدمة، ثم ستطلب الدالة آليًا باستخدام مكتبات عميل Google Auth وبيانات الاعتماد التلقائية للتطبيق (ADC). يمكنك الاطّلاع على مزيد من المعلومات حول مكتبات العملاء في Google في قسم "شرح مكتبات العملاء" ضمن المستندات.

يُعدّ استخدام ADC مهمًا بشكل خاص عندما تريد كتابة دالتك واختبارها محليًا (على سبيل المثال، على الكمبيوتر المحمول أو في Cloud Shell أو غير ذلك) أثناء التفاعل مع موارد Google Cloud الأخرى (مثل Cloud Storage وVision API وغير ذلك). في هذا المثال، ستتعرّف على كيفية جعل إحدى الخدمات تستدعي وظيفة أخرى تتطلّب المصادقة. لمزيد من المعلومات عن ADC والتطوير المحلي، يُرجى الاطّلاع على مشاركة المدونة كيفية تطوير واختبار Cloud Functions محليًا | مدونة Google Cloud

تنفيذ أمر gcloud لانتحال هوية حساب خدمة

تعثر بيانات الاعتماد التلقائية للتطبيق تلقائيًا على بيانات الاعتماد استنادًا إلى بيئة التطبيق، وتستخدم هذه البيانات للمصادقة على Google Cloud APIs. يتيح لك الخيار ‎–impersonate-service-account انتحال هوية حساب خدمة من خلال استخدام هويته للمصادقة على واجهات برمجة تطبيقات Google Cloud.

لانتحال هوية حساب خدمة، يمكنك تنفيذ الأمر التالي:

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

أنت الآن تنفّذ أوامر gcloud بصفتك حساب الخدمة هذا، بدلاً من هويتك.

إنشاء خدمة وتشغيلها لاستدعاء دالة تمت المصادقة عليها

يتضمّن كل وقت تشغيل مكتبة برامج Google Auth يمكنك تثبيتها. يوضّح لك هذا الدرس التطبيقي حول الترميز كيفية إنشاء تطبيق Node.js وتشغيله محليًا.

في ما يلي خطوات استخدام Node.js:

إنشاء تطبيق Node.js جديد

npm init

تثبيت مكتبة برامج Google Auth

npm install google-auth-library

إنشاء ملف index.js
استرجِع عنوان URL الخاص بـ Cloud Function، والذي ستضيفه إلى الرمز في الخطوة التالية.

echo $FUNCTION_URL

أضِف الرمز التالي إلى index.js. تأكَّد من تغيير المتغيّر targetAudience إلى عنوان URL الخاص بـ "وظيفة السحابة الإلكترونية".

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;
});

تشغيل التطبيق

node index.js

من المفترض أن يظهر لك النص "Hello World!‎" الناتج.

تحديد المشاكل وحلّها

إذا ظهرت لك رسالة الخطأ Permission ‘iam.serviceAccounts.getOpenIdToken' denied on resource (or it may not exist).‎، يُرجى الانتظار بضع دقائق إلى أن يتم نشر دور "منشئ رموز حساب الخدمة".

إذا تلقّيت الخطأ Cannot fetch ID token in this environment, use GCE or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account credentials JSON file، قد تكون نسيت تنفيذ الأمر

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

7. تهانينا!

تهانينا على إكمال هذا الدرس العملي.

ننصحك بمراجعة المستندات حول كيفية تأمين Cloud Functions.

ننصحك أيضًا بقراءة مشاركة المدونة هذه حول التطوير المحلي باستخدام Cloud Functions للتعرّف على كيفية تطوير وظيفة Cloud Function واختبارها في بيئة التطوير المحلية.

المواضيع التي تناولناها

كيفية ضبط المصادقة على إحدى "وظائف السحابة الإلكترونية" والتأكّد من ضبطها بشكلٍ سليم
استدعاء دالة مصادَق عليها من بيئة تطوير محلية من خلال تقديم الرمز المميز لهوية gcloud
كيفية إنشاء حساب خدمة ومنحه الدور المناسب لتنفيذ وظيفة
كيفية انتحال هوية خدمة من بيئة تطوير محلية تتضمّن الأدوار المناسبة لاستدعاء دالة

8. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تم استدعاء Cloud Function بدون قصد مرات أكثر من عدد مرات استدعاء Cloud Function المخصّصة لك في المستوى المجاني)، يمكنك إما حذف Cloud Function أو حذف المشروع الذي أنشأته في الخطوة 2.

لإيقاف انتحال هوية حساب الخدمة، يمكنك إعادة تسجيل الدخول باستخدام هويتك:

gcloud auth application-default login

لحذف Cloud Function، انتقِل إلى Cloud Function Cloud Console على https://console.cloud.google.com/functions/ وتأكَّد من أنّ المشروع الذي أنشأته في الخطوة 2 هو المشروع المحدّد حاليًا.

اختَر الدالة my-authenticated-function التي نشرتها سابقًا. بعد ذلك، انقر على حذف.

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة 2، ثم النقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تنفيذ gcloud projects list.