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

1. مقدمة

نظرة عامة

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

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

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

المعلومات التي ستطّلع عليها

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

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

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

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

تفعيل Cloud Shell

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

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

من المفترَض أن تستغرق عملية توفير المتطلبات اللازمة والاتصال بخدمة Cloud Shell بضع دقائق فقط.

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

بعد الربط بخدمة 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، يُرجى اتّباع الخطوات الموضّحة في مقالة إعداد بيانات الاعتماد التلقائية للتطبيق.

3- إنشاء دالة سحابية تمت مصادقتها واختبارها

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

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

إنشاء الدالة التي تمت مصادقتها

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

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

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

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

إعداد متغيّرات البيئة المحلية لأوامر 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 ضمن المستندات.

بعد ذلك، استدعِ الدالة وقم بتمريرها إلى رمز هويتك.

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

الآن سترى النتيجة:

Hello World!

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

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

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

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

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

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

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

ومن خلال إجراء ذلك، لن تثبت ملكية الأدوار فحسب، بل ستتّبع أيضًا مبدأ الحدّ الأدنى من الأذونات المميّزة، وذلك من خلال عدم منح دور "مُستدعي دالة 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 Function Authentication codelab"

ومنح حساب الخدمة دور مرسِل وظيفة Cloud Function.

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

وستُطلَب منك ما إذا كنت تمنح حساب الخدمة دورًا إضافيًا في استدعاء تشغيل السحابة الإلكترونية. النقر على "y" أو اضغط على Enter لإضافة دور Cloud Run 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 وبيانات الاعتماد التلقائية للتطبيق (ADC). يمكنك الاطّلاع على المزيد من المعلومات حول مكتبات برامج Google في القسم شرح لمكتبات العملاء في المستندات.

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

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

يعثر ADC تلقائيًا على بيانات الاعتماد استنادًا إلى بيئة التطبيق ويستخدم بيانات الاعتماد هذه للمصادقة على واجهات برمجة تطبيقات Google Cloud. تتيح لك علامة "انتحال هوية حساب الخدمة" انتحال هوية حساب خدمة باستخدام هويته للمصادقة على Google Cloud APIs.

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

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

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

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

تتضمّن كل بيئة تشغيل مكتبة برامج "مصادقة Google" خاصة بها يمكنك تثبيتها. يرشدك هذا الدرس التطبيقي خلال عملية إنشاء تطبيق Node.js وتشغيله على الجهاز.

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

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

npm init

2. تثبيت مكتبة برامج مصادقة Google

npm install google-auth-library

3. إنشاء ملف index.js
4. استرجع عنوان URL لدالة Cloud، الذي ستضيفه إلى الرمز في الخطوة التالية.

echo $FUNCTION_URL

5. أضِف الرمز التالي إلى index.js. احرص على تغيير متغيّر targetالجمهور إلى عنوان URL لدالة Cloud Function.

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

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

node index.js

وينبغي أن ترى "مرحبًا أيها العالم!"

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

إذا ظهرت لك رسالة الخطأ الخاصة بالإذن "iam.serviceAccounts.getOpenIdToken" تم رفضه على المورد (أو قد لا يكون موجودًا). يُرجى الانتظار بضع دقائق حتى يتم نشر دور "منشئ الرموز المميزة لحساب الخدمة".

إذا تلقيت رسالة الخطأ "لا يمكن استرجاع الرمز المميّز للمعرّف في هذه البيئة"، استخدِم GCE أو اضبط متغيّر بيئة GOOGLE_APPLICATION_CREDENTIALS على ملف JSON لبيانات اعتماد حساب الخدمة، ومن المحتمل أنّك نسيت تشغيل الأمر

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

7. تهانينا!

تهانينا على إكمال الدرس التطبيقي حول الترميز.

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

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

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

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

8. تَنظيم

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

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

gcloud auth application-default login

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

اختَر الوظيفة التي تمت المصادقة عليها التي نشرتها سابقًا. بعد ذلك، انقر على حذف.

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