يتيح نظام OAuth 2.0 من Google استخدام التفاعلات من خادم إلى خادم مثل تلك بين الويب. أحد التطبيقات وخدمة Google. بالنسبة إلى هذا السيناريو، تحتاج إلى حساب خدمة، والذي هو حساب ينتمي إلى تطبيقك بدلاً من مستخدم فردي. يستدعي التطبيق واجهات Google APIs نيابةً عن حساب الخدمة، لذلك لا المشاركة. يُسمى هذا السيناريو أحيانًا "بروتوكول OAuth الثنائي"، أو "2LO." (المصطلح ذي الصلة "بروتوكول OAuth الثلاثي" يشير إلى السيناريوهات التي يستدعي فيها تطبيقك واجهات Google APIs نيابةً عنك من المستخدمين، والتي تتطلب أحيانًا موافقة المستخدم).
عادةً ما يستخدم التطبيق حساب خدمة عند استخدام التطبيق لواجهات Google APIs للعمل ببياناته الخاصة بدلاً من بيانات المستخدم. على سبيل المثال، أحد التطبيقات التي تستخدم Google Cloud قد يستخدم مخزن البيانات للحفاظ على البيانات حساب خدمة لمصادقة عمليات الاتصال به واجهة برمجة تطبيقات تخزين البيانات في Google Cloud.
يمكن لمشرفي نطاقات Google Workspace أيضًا منح حسابات الخدمة تفويضًا على مستوى النطاق للوصول إلى المستخدم نيابةً عن المستخدمين في النطاق.
يشرح هذا المستند كيف يمكن لأحد التطبيقات إكمال تدفق 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. لإنشاء حساب الخدمة أو لعرض بيانات الاعتماد العامة التي قمت بإنشائها بالفعل، قم بما يلي:
أولاً ، قم بإنشاء حساب خدمة:
- افتح Service accounts page.
- If prompted, select a project, or create a new one.
- انقر فوق إنشاء حساب الخدمة .
- ضمن تفاصيل حساب الخدمة ، اكتب اسمًا ومعرفًا ووصفًا لحساب الخدمة ، ثم انقر فوق إنشاء ومتابعة .
- اختياري: ضمن منح حق الوصول إلى حساب الخدمة هذا للمشروع ، حدد أدوار IAM لمنح حساب الخدمة.
- انقر فوق متابعة .
- اختياري: ضمن منح المستخدمين حق الوصول إلى حساب الخدمة هذا ، أضف المستخدمين أو المجموعات المسموح لها باستخدام حساب الخدمة وإدارته.
- انقر فوق تم .
بعد ذلك ، قم بإنشاء مفتاح حساب الخدمة:
- انقر فوق عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته.
- انقر فوق علامة التبويب المفاتيح .
- في القائمة المنسدلة إضافة مفتاح ، حدد إنشاء مفتاح جديد .
- انقر فوق إنشاء .
يتم إنشاء زوج المفاتيح العام / الخاص الجديد وتنزيله على جهازك ؛ إنه بمثابة النسخة الوحيدة من المفتاح الخاص. أنت مسؤول عن تخزينه بشكل آمن. إذا فقدت زوج المفاتيح هذا ، فستحتاج إلى إنشاء زوج جديد.
يمكنك الرجوع إلى API Console في أي وقت لعرض عنوان البريد الإلكتروني العلني البصمات المرجعية الرئيسية والمعلومات الأخرى، أو إنشاء أزواج مفاتيح عامة/خاصة إضافية. بالنسبة مزيد من التفاصيل حول بيانات اعتماد حساب الخدمة في API Console، عرض حسابات الخدمة في API Console ملف المساعدة.
عليك تدوين عنوان البريد الإلكتروني لحساب الخدمة وتخزين المفتاح الخاص لحساب الخدمة. في مكان يمكن لتطبيقك الوصول إليه. يحتاج تطبيقك إليها لإجراء طلبات البيانات من واجهة برمجة التطبيقات المعتمدة.
تفويض صلاحية على مستوى النطاق لحساب الخدمة
باستخدام حساب Google Workspace، يمكن لمشرف Workspace في المؤسسة تفويض تطبيق للوصول إلى بيانات مستخدمي Workspace نيابةً عن المستخدمين في نطاق Google Workspace. على سبيل المثال: تطبيق يستخدم Google Calendar API لإضافة الأحداث إلى تقاويم جميع المستخدمين في نطاق Google Workspace قد يستخدم حساب خدمة للوصول إلى Google Calendar API على بالنيابة عن المستخدمين. تفويض حساب خدمة للوصول إلى البيانات نيابةً عن المستخدمين في أحد النطاقات هو يُشار إليه أحيانًا باسم "تفويض المرجع على مستوى النطاق" بحساب خدمة.
لتفويض السلطة على مستوى النطاق لحساب خدمة، يكون المشرف المتميّز في Google على نطاق Workspace إكمال الخطوات التالية:
- من نطاق Google Workspace الخاص بك: وحدة تحكّم المشرف، انتقِل إلى القائمة الرئيسية > الأمان > التحكّم بالبيانات والوصول > عناصر تحكُّم واجهة برمجة التطبيقات:
- في لوحة التفويض على مستوى النطاق، اختَر إدارة التفويض على مستوى النطاق.
- انقر على إضافة فلتر جديد.
- في الحقل معرّف العميل، أدخِل رقم تعريف العميل لحساب الخدمة. يمكنك الاطّلاع على معرِّف العميل لحساب الخدمة لديك في Service accounts page
- في حقل نطاقات OAuth (مفصولة بفواصل)، أدخِل قائمة النطاقات التي حق الوصول إليها. على سبيل المثال، إذا كان التطبيق يحتاج إلى إجراءات على مستوى النطاق حق الوصول الكامل إلى واجهة برمجة تطبيقات Google Drive وواجهة برمجة تطبيقات تقويم Google، أدخل: https://www.googleapis.com/auth/drive أو https://www.googleapis.com/auth/calendar.
- انقر على تفويض.
لدى تطبيقك الآن الصلاحية لإجراء طلبات البيانات من واجهة برمجة التطبيقات كمستخدمين في نطاق Workspace (من أجل "انتحال الهوية" المستخدمين). عندما تستعد لإجراء طلبات البيانات المفوَّضة من واجهة برمجة التطبيقات هذه، عليك تحديد ما يلي للمستخدم انتحال الهوية.
التحضير لإجراء طلب مفوَّض لواجهة برمجة التطبيقات
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()
مستخدمًا ينتمي إلى
Google Workspace. سيستخدم الرمز الذي يرسل الطلب بيانات الاعتماد هذه للاتصال بـ Google.
واجهات برمجة التطبيقات باستخدام حساب الخدمة الخاص بك
Python
بعد الحصول على عنوان البريد الإلكتروني للعميل والمفتاح الخاص من ملف API Console، يمكنك استخدام مكتبة برامج Google APIs للغة Python لإكمال الخطوات التالية:
- أنشئ عنصر
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، يمكنك استخدام بيانات الاعتماد التلقائية للتطبيق بدلاً من ذلك، مما قد يؤدي إلى تبسيط العملية.
- تفويض التفويض على مستوى النطاق
إذا كان لديك إذن وصول مفوَّض على مستوى النطاق إلى حساب الخدمة وأردت انتحال هوية حساب مستخدم، واستخدام طريقة
with_subject
لحساب حالي كائنServiceAccountCredentials
. على سبيل المثال:delegated_credentials = credentials.with_subject('user@example.org')
استخدِم كائن Credentials لطلب Google APIs في تطبيقك.
HTTP/REST
بعد الحصول على معرِّف العميل والمفتاح الخاص من ملف API Console، يجب على طلبك إكمال الخطوات التالية:
- أنشئ رمز JSON المميّز للويب (JWT، يُلفظ "jot")، والذي يتضمّن عنوانًا ومجموعة مطالبات والتوقيع.
- اطلب رمز الدخول من خادم تفويض OAuth 2.0 في Google.
- تعامل مع استجابة JSON التي يعرضها خادم التفويض.
توضح الأقسام التالية كيفية إكمال هذه الخطوات.
إذا كان الردّ يتضمن رمز دخول، يمكنك استخدام رمز الدخول لإجراء ما يلي: طلب بيانات من واجهة Google API (إذا كان الرد لا يتضمن إمكانية الوصول الرمز المميز، فقد لا يكون طلب JWT والرمز المميز مكتوبًا بشكل صحيح، أو ربما ليس لديهم إذن بالوصول إلى النطاقات المطلوبة).
عند انتهاء صلاحية رمز الدخول، ينشئ تطبيقك رمز دخول آخر يقوم JWT بتوقيعه وطلب رمز دخول آخر.
![يستخدم تطبيق الخادم JWT لطلب رمز مميز من Google
خادم التفويض، يستخدم بعد ذلك الرمز المميز لاستدعاء نقطة نهاية واجهة برمجة تطبيقات Google. لا
مشاركة المستخدم النهائي.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/oauth2/images/flows/jwt.png?authuser=6&hl=ar)
يصف باقي هذا القسم تفاصيل إنشاء 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
يتكون العنوان من ثلاثة حقول تشير إلى خوارزمية التوقيع، وتنسيق والتأكيد و[key ID of the service account key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) الذي تم استخدامه للتوقيع على JWT. تعد الخوارزمية والتنسيق إلزاميين، ويحتوي كل حقل على قيمة واحدة. عند تقديم خوارزميات وتنسيقات إضافية، سيتغير هذا العنوان وفقًا لذلك. رقم تعريف المفتاح اختياري، وفي حال تحديد رقم تعريف مفتاح غير صحيح، سيحاول GCP. جميع المفاتيح المرتبطة بحساب الخدمة للتحقّق من الرمز المميّز ورفضه في حال لم يتم العثور على مفتاح صالح. تحتفظ 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 بالتوقيت العالمي المنسق (UTC) 1 يناير 1970 تستغرق هذه القيمة ساعة واحدة كحد أقصى بعد وقت الإصدار. |
iat |
وقت إصدار التأكيد، والمحدد بالثواني منذ 00:00:00 بالتوقيت العالمي المنسق (UTC)، 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-safe. مشفّرة. في ما يلي مثال على تمثيل 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 الموقَّع، يمكن للتطبيق استخدامه لطلب رمز الدخول.
طلب رمز الدخول هذا هو طلب HTTPS POST
، والنص الأساسي هو عنوان 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 APIs
Java
استخدِم الكائن GoogleCredential
لاستدعاء Google APIs من خلال إكمال
الخطوات التالية:
- أنشِئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد طلبها باستخدام
عنصر
GoogleCredential
. مثلاً:SQLAdmin sqladmin = new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
- يمكنك تقديم طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام
الواجهة التي يوفّرها عنصر الخدمة
على سبيل المثال، لإدراج مثيلات قواعد بيانات Cloud SQL في النموذج المثير-example-123
المشروع:
SQLAdmin.Instances.List instances = sqladmin.instances().list("exciting-example-123").execute();
Python
يمكنك استخدام الكائن Credentials
المفوّض لاستدعاء Google APIs من خلال إكمال
الخطوات التالية:
- أنشِئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد طلبها. تُنشئ عنصر خدمة
من خلال استدعاء الدالة
build
باسم واجهة برمجة التطبيقات وإصدارها عنصرCredentials
معتمد. على سبيل المثال، لطلب الإصدار 1beta3 من واجهة برمجة التطبيقات لإدارة Cloud SQL:import googleapiclient.discovery sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
- يمكنك تقديم طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام
الواجهة التي يوفّرها عنصر الخدمة
على سبيل المثال، لإدراج مثيلات قواعد بيانات Cloud SQL في النموذج المثير-example-123
المشروع:
response = sqladmin.instances().list(project='exciting-example-123').execute()
HTTP/REST
بعد حصول تطبيقك على رمز الدخول، يمكنك استخدام الرمز لإجراء اتصالات
واجهة برمجة التطبيقات نيابةً عن حساب خدمة معيّن أو
حساب مستخدم في حال منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. للقيام بذلك، قم بتضمين
رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين طلب بحث access_token
مَعلمة أو قيمة Bearer
لعنوان HTTP يتضمّن Authorization
. عندما يكون ذلك ممكنًا،
ويُفضل استخدام عنوان HTTP، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم
يمكنك استخدام مكتبة برامج لإعداد الطلبات إلى Google APIs (على سبيل المثال، عند
طلب واجهة برمجة تطبيقات ملفات Drive).
يمكنك تجربة جميع واجهات Google APIs وعرض نطاقاتها من خلال ملعب OAuth 2.0.
أمثلة على الحصول على HTTP
اتصال
drive.files
نقطة النهاية (واجهة برمجة تطبيقات ملفات Drive) باستخدام Authorization: Bearer
HTTP
على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
إليك طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمت مصادقته باستخدام access_token
مَعلمة سلسلة طلب البحث:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
أمثلة على curl
يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl
. إليك
مثال يستخدم خيار عنوان HTTP (مفضّل):
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
عند انتهاء صلاحية رموز الدخول
تنتهي صلاحية رموز الدخول الصادرة عن خادم تفويض OAuth 2.0 في Google بعد المدة
التي تقدمها القيمة expires_in
. عند انتهاء صلاحية رمز الدخول، فعندئذٍ
إنشاء ملف JWT آخر وتوقيعه وطلب رمز دخول آخر.
رموز خطأ JWT
حقل واحد (error ) |
حقل واحد (error_description ) |
المعنى | كيفية الحل |
---|---|---|---|
unauthorized_client |
Unauthorized client or scope in request. |
إذا كنت تحاول استخدام تفويض على مستوى النطاق، فإن حساب الخدمة غير مصرح به في وحدة تحكم المشرف لنطاق المستخدم. |
تأكَّد من أنّ حساب الخدمة مُصرَّح به في
التفويض على مستوى النطاق في "وحدة تحكُّم المشرف" للمستخدم في
مطالبة واحدة ( على الرغم من أن الأمر يستغرق عادةً بضع دقائق، إلا أنه قد يستغرق الأمر ما يصل إلى 24 ساعة للتفويض نشرها لجميع المستخدمين في حسابك على Google. |
unauthorized_client |
Client is unauthorized to retrieve access tokens using this method, or client not
authorized for any of the scopes requested. |
تم تفويض حساب الخدمة باستخدام عنوان البريد الإلكتروني للعميل بدلاً من معرِّف العميل. (رقمية) في "وحدة تحكّم المشرف". | في قسم التفويض على مستوى النطاق في "وحدة تحكُّم المشرف"، أزِل العميل وأعِد إضافته بالمعرف الرقمي. |
access_denied |
(أي قيمة) | في حال كنت تستخدم التفويض على مستوى النطاق، لا يتم تفويض نطاق واحد أو أكثر من النطاقات المطلوبة. في وحدة تحكم المشرف. |
تأكَّد من أنّ حساب الخدمة مُصرَّح به في
التفويض على مستوى النطاق في "وحدة تحكُّم المشرف" للمستخدم في
على الرغم من أن الأمر يستغرق عادةً بضع دقائق، إلا أنه قد يستغرق الأمر ما يصل إلى 24 ساعة للتفويض نشرها لجميع المستخدمين في حسابك على Google. |
admin_policy_enforced |
(أي قيمة) | يتعذّر على حساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. |
الاطّلاع على مقالة المساعدة "مشرف Google Workspace" التحكم في الجهات الخارجية وصول التطبيقات الداخلية إلى بيانات Google Workspace لمزيد من المعلومات حول كيفية المشرف على الوصول إلى جميع النطاقات أو النطاقات الحساسة والمحظورة حتى تم منح إذن الوصول بشكل صريح إلى معرِّف عميل OAuth. |
invalid_client |
(أي قيمة) |
عميل OAuth أو الرمز المميّز JWT غير صالح أو تم ضبطه بشكلٍ غير صحيح. يُرجى الاطّلاع على وصف الخطأ لمعرفة التفاصيل. |
تأكد من أن رمز JWT المميز صالح ويحتوي على مطالبات صحيحة. التحقُّق من صحة برنامج OAuth وحساب الخدمة بشكل صحيح، وأنك تستخدم عنوان البريد الإلكتروني الصحيح. يُرجى التحقق من صحة رمز JWT المميز وإصداره لمعرِّف العميل في طلبك. |
invalid_grant |
Not a valid email. |
المستخدم غير موجود. | تأكَّد من صحة عنوان البريد الإلكتروني الوارد في المطالبة (الحقل) في sub . |
invalid_grant |
|
وعادةً ما يعني ذلك أن وقت النظام المحلي غير صحيح. يمكن أن يحدث أيضًا إذا تم
تزيد قيمة exp عن 65 دقيقة في المستقبل من قيمة iat ،
أو قيمة exp أقل من قيمة iat . |
تأكد من صحة ساعة النظام التي يتم فيها إنشاء JWT. في حال حذف قم بمزامنة وقتك مع Google NTP. |
invalid_grant |
Invalid JWT Signature. |
تم توقيع تأكيد JWT باستخدام مفتاح خاص غير مرتبط بحساب الخدمة. التي حدّدها البريد الإلكتروني للعميل أو أنّ المفتاح الذي تم استخدامه قد تم حذفه أو إيقافه أو منتهي الصلاحية. بدلاً من ذلك، قد يتم ترميز تأكيد JWT بشكل غير صحيح - يجب أن يكون بترميز Base64، بدون أسطر جديدة أو علامات يساوي المساحة المتروكة |
فك ترميز مجموعة مطالبات JWT والتحقّق من ارتباط المفتاح الذي تم توقيع التأكيد عليه باستخدام حساب الخدمة. جرِّب استخدام مكتبة OAuth التي توفّرها Google للتأكّد من إنشاء JWT بشكل صحيح. |
invalid_scope |
Invalid OAuth scope or ID token audience provided. |
لم يتم طلب أي نطاقات (قائمة فارغة للنطاقات)، أو لم يتم طلب أي من النطاقات المطلوبة موجودة (أي أنها غير صالحة). |
تأكَّد من تعبئة المطالبة (الحقل) يجب فصل قائمة النطاقات في مطالبة |
disabled_client |
The OAuth client was disabled. |
تم إيقاف المفتاح المستخدم للتوقيع على تأكيد JWT. |
انتقِل إلى Google API Console، وضمن إدارة الهوية وإمكانية الوصول وحدة تحكّم المشرف > حسابات الخدمة: فعِّل حساب الخدمة الذي يحتوي على "رقم تعريف المفتاح". مستخدَمة للتوقيع على التأكيد. |
org_internal |
This client is restricted to users within its organization. |
معرِّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من إمكانية الوصول إلى Google الحسابات في حساب مؤسسة Google Cloud: |
استخدام حساب خدمة من المؤسسة للمصادقة. أكِّد نوع المستخدم لضبط تطبيق OAuth. |
ملحق: تفويض حساب الخدمة بدون بروتوكول OAuth
يمكنك من خلال بعض واجهات برمجة تطبيقات Google إجراء طلبات بيانات معتمَدة من واجهة برمجة التطبيقات باستخدام ملف JWT موقَّع بشكل مباشر. الحامل بدلاً من رمز الدخول عبر OAuth 2.0. وعندما يكون ذلك ممكنًا، يمكنك تجنب طلب الشبكة إلى خادم تفويض Google قبل إجراء طلب بيانات من واجهة برمجة التطبيقات.
إذا كان لواجهة برمجة التطبيقات التي تريد طلبها تعريف خدمة منشور في مستودع Google APIs في GitHub، يمكنك إجراء اتصالات واجهة برمجة التطبيقات المعتمدة باستخدام JWT بدلاً من رمز الدخول. ولإجراء ذلك، يُرجى اتّباع الخطوات التالية:
- أنشئ حساب خدمة كما هو موضّح أعلاه. تأكد من ملف JSON الذي تحصل عليه عند إنشاء الحساب.
- استخدام أي مكتبة 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 باستخدام RSA-256 باستخدام المفتاح الخاص في ملف JSON لحساب الخدمة.
على سبيل المثال:
Java
استخدام google-api-java-client و java-jwt:
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 ...
Python
باستخدام PyJWT:
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')
- يمكنك طلب واجهة برمجة التطبيقات، باستخدام 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
يمكنك الاطّلاع على حماية حسابات المستخدمين باستخدام صفحة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات حول كيفية تفعيل ميزة "الحماية العابرة للحساب" والاطّلاع على قائمة كاملة بالأحداث المتاحة.