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

يتيح نظام Google OAuth 2.0 التفاعلات بين الخوادم، مثل التفاعلات بين تطبيق ويب وإحدى خدمات Google. في هذا السيناريو، تحتاج إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من مستخدم نهائي فردي. يُطلِب تطبيقك واجهات برمجة تطبيقات Google بالنيابة عن حساب الخدمة، لذلك لا يشترك المستخدمون بشكل مباشر. يُعرف هذا السيناريو أحيانًا باسم "بروتوكول OAuth المكوّن من خطوتَين" أو "2LO". (يشير المصطلح verwandt "بروتوكول 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. لإنشاء بيانات اعتماد حساب الخدمة، أو لعرض بيانات الاعتماد العامة التي سبق أن أنشأتها، اتّبِع الخطوات التالية:

First, create a service account:

1. Open the Service accounts page.
2. If prompted, select a project, or create a new one.
3. Click add Create service account.
4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
6. Click Continue.
7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
8. Click Done.

Next, create a service account key:

1. Click the email address for the service account you created.
2. Click the Keys tab.
3. In the Add key drop-down list, select Create new key.
4. Click Create.

Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.

يمكنك الرجوع إلى 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

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