استخدام OAuth 2.0 لخادم في تطبيقات الخادم

يتيح نظام Google OAuth 2.0 التفاعلات بين الخوادم، مثل التفاعلات بين تطبيق ويب وإحدى خدمات Google. في هذا السيناريو، تحتاج إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من مستخدم نهائي فردي. يُطلِب تطبيقك واجهات برمجة تطبيقات Google بالنيابة عن حساب الخدمة، لذلك لا يشترك المستخدمون بشكل مباشر. يُعرف هذا السيناريو أحيانًا باسم "بروتوكول OAuth المكوّن من خطوتَين" أو "2LO". (يشير المصطلح بروتوكول OAuth الثلاثي إلى السيناريوهات التي يستدعي فيها تطبيقك Google APIs بالنيابة عن المستخدمين النهائيين، والتي تتطلّب أحيانًا موافقة المستخدم.)

يستخدم التطبيق عادةً حساب خدمة عندما يستخدم واجهات برمجة تطبيقات Google للعمل مع بياناته الخاصة بدلاً من بيانات المستخدم. على سبيل المثال، سيستخدم تطبيق يستخدم Google Cloud Datastore للحفاظ على ثبات البيانات حساب خدمة لمصادقة طلبات البيانات المرسَلة إلى Google Cloud Datastore API.

يمكن أيضًا لمشرفي نطاق Google Workspace منح حسابات الخدمة إذنًا على مستوى النطاق للوصول إلى data المستخدمين نيابةً عن المستخدمين في النطاق.

يوضّح هذا المستند كيفية إكمال تطبيق لعملية OAuth 2.0 من خادم إلى خادم من خلال استخدام مكتبة عملاء Google APIs (إجراء يُنصح به) أو HTTP.

نظرة عامة

لتفعيل التفاعلات بين الخوادم، عليك أولاً إنشاء حساب خدمة لمشروعك في API Console. إذا كنت تريد الوصول إلى بيانات المستخدمين في حسابك على Google Workspace، يمكنك تفويض الوصول على مستوى النطاق إلى حساب الخدمة.

بعد ذلك، يستعد تطبيقك لإجراء طلبات مفوَّضة لواجهة برمجة التطبيقات باستخدام بيانات اعتماد حساب الخدمة لطلب رمز وصول من خادم مصادقة OAuth 2.0.

أخيرًا، يمكن لتطبيقك استخدام الرمز المميّز للوصول إلى واجهات برمجة تطبيقات Google.

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

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

إذا كان تطبيقك يعمل على Google App Engine، يتم إعداد حساب خدمة تلقائيًا عند إنشاء مشروعك.

إذا كان تطبيقك يعمل على Google Compute Engine، سيتم أيضًا إعداد حساب خدمة تلقائيًا عند إنشاء مشروعك، ولكن عليك تحديد النطاقات التي يحتاج تطبيقك إلى الوصول إليها عند إنشاء مثيل Google Compute Engine. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد مثيل لاستخدام حسابات الخدمة.

إذا لم يكن تطبيقك يعمل على Google App Engine أو Google Compute Engine، يجب الحصول على هذه بيانات الاعتماد في Google API Console. لإنشاء بيانات اعتماد حساب الخدمة ، أو لعرض بيانات الاعتماد العامة التي سبق أن أنشأتها، اتّبِع الخطوات التالية:

أولاً ، قم بإنشاء حساب خدمة:

1. افتح Service accounts page.
2. If prompted, select a project, or create a new one.
3. انقر فوق add إنشاء حساب الخدمة .
4. ضمن تفاصيل حساب الخدمة ، اكتب اسمًا ومعرفًا ووصفًا لحساب الخدمة ، ثم انقر فوق إنشاء ومتابعة .
5. اختياري: ضمن منح حق الوصول إلى حساب الخدمة هذا للمشروع ، حدد أدوار IAM لمنح حساب الخدمة.
6. انقر فوق متابعة .
7. اختياري: ضمن منح المستخدمين حق الوصول إلى حساب الخدمة هذا ، أضف المستخدمين أو المجموعات المسموح لها باستخدام حساب الخدمة وإدارته.
8. انقر فوق تم .

بعد ذلك ، قم بإنشاء مفتاح حساب الخدمة:

1. انقر فوق عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته.
2. انقر فوق علامة التبويب المفاتيح .
3. في القائمة المنسدلة إضافة مفتاح ، حدد إنشاء مفتاح جديد .
4. انقر فوق إنشاء .

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

يمكنك الرجوع إلى API Console في أي وقت للاطّلاع على عنوان البريد الإلكتروني وملفات تعريف المفتاح العام ومعلومات أخرى، أو لإنشاء أزواج إضافية من المفاتيح العامة/الخاصة. للحصول على المزيد من التفاصيل عن بيانات اعتماد حساب الخدمة في API Console، يُرجى الاطّلاع على حسابات الخدمة في API Console ملف المساعدة.

دوِّن عنوان البريد الإلكتروني لحساب الخدمة واحفظ ملف المفتاح الخاص لحساب الخدمة في مكان يمكن لتطبيقك الوصول إليه. يحتاج تطبيقك إلى هذه الأذونات لإجراء طلبات بيانات من واجهة برمجة التطبيقات مُفوَّضة.

تفويض السلطة على مستوى النطاق لحساب الخدمة

باستخدام حساب Google Workspace، يمكن لمشرف Workspace في المؤسسة تفويض تطبيق بالوصول إلى بيانات مستخدمي Workspace نيابةً عن المستخدمين في نطاق Google Workspace. على سبيل المثال، يستخدم تطبيق يستخدم واجهة برمجة التطبيقات Google Calendar API لإضافة أحداث إلى تقويمات جميع المستخدمين في نطاق Google Workspace حساب خدمة للوصول إلى واجهة برمجة التطبيقات Google Calendar API بالنيابة عن المستخدمين. يُشار أحيانًا إلى تفويض حساب خدمة للوصول إلى البيانات نيابةً عن المستخدمين في نطاق باسم "تفويض السلطة على مستوى النطاق" لحساب الخدمة.

لتفويض صلاحية على مستوى النطاق لحساب خدمة، على المشرف المتميّز لنطاق Google Workspace إكمال الخطوات التالية:

1. من وحدة تحكّم المشرف لنطاق Google Workspace، انتقِل إلى القائمة الرئيسية menu > الأمان > التحكّم في الوصول والبيانات > عناصر تحكّم واجهة برمجة التطبيقات.
2. في لوحة التفويض على مستوى النطاق، اختَر إدارة التفويض على مستوى النطاق.
3. انقر على إضافة نطاق جديد.
4. في الحقل معرِّف العميل، أدخِل معرِّف العميل لحساب الخدمة. يمكنك العثور على معرِّف عميل حساب الخدمة في Service accounts page.
5. في حقل نطاقات OAuth (مفصولة بفواصل)، أدخِل قائمة النطاقات التي يجب منح تطبيقك إذن الوصول إليها. على سبيل المثال، إذا كان تطبيقك يحتاج إلى إذن بالوصول الكامل على مستوى النطاق إلى Google Drive API وGoogle Calendar API، أدخِل: https://www.googleapis.com/auth/drive، https://www.googleapis.com/auth/calendar.
6. انقر على تفويض.

أصبح تطبيقك يملك الآن الإذن بإجراء طلبات بيانات من واجهة برمجة التطبيقات باسم مستخدمين في نطاق Workspace (لشدّد على "انتحال هوية" المستخدمين). عند الاستعداد لإجراء هذه الطلبات المفوَّضة لواجهات برمجة التطبيقات، عليك تحديد المستخدم الذي تريد impersonatingه بشكل صريح.

التحضير لإجراء طلب بيانات من واجهة برمجة تطبيقات مفوَّض

Java

بعد الحصول على عنوان البريد الإلكتروني للعميل والمفتاح الخاص من API Console، استخدِم مكتبة برامج Google APIs للغة Java لإنشاء عنصر GoogleCredential من بيانات اعتماد حساب الخدمة والنطاقات التي يحتاج تطبيقك إلى الوصول إليها. على سبيل المثال:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

إذا كنت تُطوّر تطبيقًا على Google Cloud Platform، يمكنك استخدام بيانات الاعتماد التلقائية للتطبيق بدلاً من ذلك، ما قد يسهّل العملية.

تفويض السلطة على مستوى النطاق

إذا كنت قد فوّضت الوصول إلى حساب الخدمة على مستوى النطاق وأردت انتحال هوية حساب مستخدم، حدِّد عنوان البريد الإلكتروني لحساب المستخدم باستخدام الأسلوب createDelegated لعنصر GoogleCredential. على سبيل المثال:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

يستخدم الرمز البرمجي أعلاه عنصر GoogleCredential لاستدعاء طريقة createDelegated(). يجب أن تكون الوسيطة لطريقة createDelegated() مستخدمًا ينتمي إلى حسابك على Workspace. سيستخدم الرمز البرمجي الذي يقدّم الطلب بيانات الاعتماد هذه لاستدعاء واجهات برمجة تطبيقات Google باستخدام حساب الخدمة.

Python

بعد الحصول على عنوان البريد الإلكتروني للعميل والمفتاح الخاص من API Console، استخدِم مكتبة عملاء Google APIs للغة Python لإكمال الخطوات التالية:

1. أنشئ عنصر Credentials من بيانات اعتماد حساب الخدمة وال النطاقات التي يحتاج تطبيقك إلى الوصول إليها. على سبيل المثال:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   إذا كنت تُطوّر تطبيقًا على Google Cloud Platform، يمكنك استخدام بيانات الاعتماد التلقائية للتطبيق بدلاً من ذلك، ما قد يسهّل العملية.

2. تفويض السلطة على مستوى النطاق

   إذا كان لديك إذن وصول مفوَّض على مستوى النطاق إلى حساب الخدمة وأردت انتحال هوية حساب مستخدم، استخدِم طريقة with_subject لعنصر ServiceAccountCredentials حالي. على سبيل المثال:

   delegated_credentials = credentials.with_subject('user@example.org')

استخدِم عنصر Credentials لطلب بيانات من Google APIs في تطبيقك.

HTTP/REST

بعد الحصول على معرّف العميل والمفتاح الخاص من API Console، يجب أن يُكمل تطبيقك الخطوات التالية:

1. أنشئ رمزًا مميزًا على JSON للويب (JWT) يتضمّن عنوانًا ومجموعة مطالبات وتوقيعًا.
2. اطلب الحصول على رمز دخول من خادم مصادقة Google OAuth 2.0.
3. عالج استجابة JSON التي يعرضها "خادم التفويض".

توضّح الأقسام التالية كيفية إكمال هذه الخطوات.

إذا كان الردّ يتضمّن رمز وصول، يمكنك استخدام رمز الوصول للقيام بما يلي: استدعاء واجهة برمجة تطبيقات Google. (إذا لم يتضمّن الردّ رمز دخول إلى الخدمة، قد لا يكون تنسيق طلب JWT ورمز الرمز صحيحًا، أو قد لا يملك حساب الخدمة الإذن بالوصول إلى النطاقات المطلوبة).

عند انتهاء صلاحية رمز الوصول، ينشئ تطبيقك رمز JWT آخر ويوقّعه ويطلب رمز وصول آخر.

يصف الجزء المتبقّي من هذا القسم تفاصيل إنشاء ملف JWT وتوقيعه، وإنشاء طلب رمز الوصول ومعالجة الاستجابة.

إنشاء رمز JWT

يتألّف رمز JWT من ثلاثة أجزاء: العنوان ومجموعة المطالب والتوقيع. العنوان ومجموعة المطالب هما كائنان من JSON. ويتم ترتيب كائنات JSON هذه على شكل تسلسل إلى UTF-8 بايت، ثم تشفيرها باستخدام ترميز Base64url. يوفر هذا الترميز مقاومة للتغييرات في الترميز بسبب عمليات الترميز المتكررة. يتم تسلسل العنوان ومجموعة المطالبات والتوقيع معًا باستخدام حرف النقطة (.).

يتم إنشاء رمز JWT على النحو التالي:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

في ما يلي السلسلة الأساسية للتوقيع:

{Base64url encoded header}.{Base64url encoded claim set}

إنشاء رأس JWT

يتألّف العنوان من ثلاثة حقول تشير إلى خوارزمية التوقيع وتنسيق العبارة و[رقم تعريف مفتاح حساب الخدمة](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) الذي تم استخدامه لتوقيع ملف JWT. يجب إدخال الخوارزمية والتنسيق، ولا يحتوي كل حقل إلا على قيمة واحدة. مع طرح خوارزميات وتنسيقات إضافية، سيتغيّر هذا العنوان وفقًا لذلك. معرّف المفتاح اختياري، وإذا تم تحديد معرّف مفتاح غير صحيح، ستحاول Google Cloud Platform جميع المفاتيح المرتبطة بحساب الخدمة للتحقّق من الرمز المميّز ورفضه في حال عدم العثور على مفتاح صالح. تحتفظ Google بالحق في رفض الرموز المميّزة التي تحتوي على معرّفات مفاتيح غير صحيحة في المستقبل.

تعتمد حسابات الخدمة على خوارزمية RSA SHA-256 وتنسيق الرمز المميّز JWT. نتيجةً لذلك، يكون تمثيل JSON للعنوان على النحو التالي:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

في ما يلي تمثيل Base64url لهذا الإجراء:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

تشكيل مجموعة مطالبات JWT

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

المطالبات المطلوبة

في ما يلي المطالب المطلوبة في مجموعة مطالب JWT. ويمكن أن تظهر بأي ترتيب في مجموعة المطالبات.

الاسم	الوصف
iss	عنوان البريد الإلكتروني لحساب الخدمة
scope	قائمة بالأذونات التي يطلبها التطبيق مع الفصل بينها بمسافات
aud	وصف للهدف المقصود للبيان عند إنشاء طلب رمز دخول ، تكون هذه القيمة دائمًا https://oauth2.googleapis.com/token.
exp	وقت انتهاء صلاحية العبارة، المحدّد بالثواني منذ 00:00:00 بالتوقيت العالمي المنسق، 1 كانون الثاني (يناير) 1970 تبلغ هذه القيمة ساعة واحدة كحد أقصى بعد وقت الإصدار.
iat	وقت إصدار العبارة، المحدّد بالثواني منذ 00:00:00 بالتوقيت العالمي المنسق، في 1 كانون الثاني (يناير) 1970

في ما يلي تمثيل JSON للحقول المطلوبة في مجموعة مطالبات JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

المطالبات الإضافية

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

للحصول على رمز مميّز للوصول يمنح تطبيقًا إذن وصول مفوَّضًا إلى مورد، أدرِج عنوان البريد الإلكتروني للمستخدم في مجموعة مطالبات JWT كقيمة الحقل sub.

الاسم	الوصف
sub	عنوان البريد الإلكتروني للمستخدم الذي يطلب التطبيق منح إذن بالوصول المفوَّض له

إذا لم يكن لدى التطبيق إذن بانتحال هوية مستخدم، سيكون الردّ على طلب الحصول على رمز دخول يتضمّن الحقل sub هو خطأ.

في ما يلي مثال على مجموعة مطالبات JWT تتضمّن الحقل sub:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

ترميز مجموعة مطالبات JWT

مثل رأس JWT، يجب تسلسل مجموعة مطالبات JWT إلى UTF-8 ويجب ترميزها باستخدام Base64url الآمن. في ما يلي مثال على تمثيل JSON لمجموعة مطالبات JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

احتساب التوقيع

توقيع JSON على الويب (JWS) هو المواصفة التي توجّه آليات إنشاء توقيع رمز JWT. الإدخال للتوقيع هو صفيف البايتات للمحتوى التالي:

{Base64url encoded header}.{Base64url encoded claim set}

يجب استخدام خوارزمية التوقيع في عنوان JWT عند احتساب التوقيع. خوارزمية التوقيع الوحيدة المتوافقة مع خادم التفويض OAuth 2.0 من Google هي RSA باستخدام خوارزمية تجزئة SHA-256. يتم التعبير عن ذلك على النحو التالي: RS256 في حقل alg في رأس JWT.

وقِّع تمثيل UTF-8 للبيانات المُدخلة باستخدام SHA256withRSA (المعروفة أيضًا باسم RSASSA-PKCS1-V1_5-SIGN مع دالة التجزئة SHA-256) باستخدام المفتاح الخاص الذي تم الحصول عليه من Google API Console. سيكون الناتج صفيفًا من البايتات.

بعد ذلك، يجب ترميز التوقيع باستخدام Base64url. يتم تسلسل العنوان ومجموعة المطالبات والتوقيع معًا باستخدام حرف النقطة (.). والنتيجة هي رمز JWT. يجب أن يكون على النحو التالي (تمّت إضافة فواصل أسطر للوضوح):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

في ما يلي مثال على رمز JWT قبل ترميز Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

في ما يلي مثال على رمز JWT تم توقيعه وأصبح جاهزًا للإرسال:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

تقديم طلب الحصول على رمز الدخول

بعد إنشاء رمز JWT موقَّع، يمكن للتطبيق استخدامه لطلب الحصول على رمز مميَّز للوصول. طلب الرمز المميّز للوصول هذا هو طلب POST بروتوكول HTTPS، والنص هو عنوان URL مُرمَّز. يظهر عنوان URL أدناه:

https://oauth2.googleapis.com/token

يجب إدخال المَعلمات التالية في طلب HTTPS POST:

الاسم	الوصف
grant_type	استخدِم السلسلة التالية، التي تم تشفيرها باستخدام عنوان URL حسب الحاجة: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	رمز JWT، بما في ذلك التوقيع

في ما يلي نسخة أولية من طلب HTTPS POST المستخدَم في طلب رمز مميّز للوصول

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

في ما يلي الطلب نفسه باستخدام curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

التعامل مع الردّ

إذا تم تنسيق رمز JWT ورمز الوصول بشكل صحيح وكان لدى حساب الخدمة إذن لتنفيذ العملية، سيتضمّن الردّ بتنسيق JSON من "خادم التفويض" رمز دخول. في ما يلي مثال على ردّ:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

يمكن إعادة استخدام الرموز المميّزة للوصول خلال فترة المدة المحدّدة من خلال قيمة expires_in.

استدعاء واجهات برمجة تطبيقات Google

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

رموز خطأ رمز JSON المميّز على الويب

ملحق: تفويض حساب الخدمة بدون بروتوكول OAuth

باستخدام بعض واجهات برمجة تطبيقات Google، يمكنك إجراء طلبات مفوَّضة لواجهات برمجة التطبيقات باستخدام ملف JWT موقَّع مباشرةً كرمز مميّز حامل، بدلاً من رمز دخول OAuth 2.0. عندما يكون ذلك ممكنًا، يمكنك تجنُّب تقديم طلب شبكة إلى خادم التفويض في Google قبل إجراء طلب واجهة برمجة التطبيقات.

إذا كانت واجهة برمجة التطبيقات التي تريد الاتصال بها تحتوي على تعريف خدمة منشور في مستودع Google APIs على GitHub، يمكنك إجراء طلبات بيانات مفوَّضة من واجهة برمجة التطبيقات باستخدام ملف JWT بدلاً من رمز مميّز للوصول. ولإجراء ذلك، يُرجى اتّباع الخطوات التالية:

1. أنشئ حساب خدمة كما هو موضّح أعلاه. احرص على الاحتفاظ بملف JSON الذي تحصل عليه عند إنشاء الحساب.
2. باستخدام أي مكتبة JWT عادية، مثل المكتبة المتوفّرة على الرابط jwt.io، أنشئ رمز JWT يتضمّن عنوانًا وحمولة مثل المثال التالي:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "123456-compute@developer.gserviceaccount.com",
     "sub": "123456-compute@developer.gserviceaccount.com",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• بالنسبة إلى الحقل kid في العنوان، حدِّد معرّف المفتاح الخاص لحساب الخدمة. يمكنك العثور على هذه القيمة في حقل private_key_id في ملف JSON لحساب الخدمة.
• بالنسبة إلى الحقلين iss وsub، حدِّد عنوان البريد الإلكتروني لحساب الخدمة. يمكنك العثور على هذه القيمة في حقل client_email في ملف JSON لحساب الخدمة.
• بالنسبة إلى الحقل aud، حدِّد نقطة نهاية واجهة برمجة التطبيقات. على سبيل المثال: https://SERVICE.googleapis.com/.
• في الحقل iat، حدِّد الوقت الحالي لنظام التشغيل Unix، وفي الحقل exp، حدِّد الوقت بعد 3600 ثانية بالضبط، عندما تنتهي صلاحية ملف JWT.

وقِّع رمز JWT باستخدام RSA-256 باستخدام المفتاح الخاص المتوفّر في ملف JSON الخاص بحساب الخدمة.

على سبيل المثال:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. اطلب بيانات من واجهة برمجة التطبيقات باستخدام رمز JWT الموقَّع كرمز مميّز للمستخدم:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com

تنفيذ ميزة "الحماية العابرة للحساب"

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

في ما يلي بعض الأمثلة على أنواع الأحداث التي ترسلها خدمة "الحماية بين الحسابات" من Google إلى تطبيقك:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

اطّلِع على صفحة "حماية حسابات المستخدمين من خلال ميزة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات عن كيفية تنفيذ ميزة "الحماية العابرة للحساب" والاطّلاع على القائمة الكاملة للأحداث المتاحة.