التفويض

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

البدء السريع للتفويض

• لإعداد مشروع Google Cloud Platform باستخدام واجهة برمجة التطبيقات لبرنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" وأسرار عميل OAuth، شغِّل هذا المعالج.
• أنشِئ رمز البدء السريع لـ Java أو .NET أو Python. استخدم مكتبات عملاء واجهة برمجة التطبيقات في Google لدعم اللغات الأخرى.

نظرة عامة

1. مشرف تكنولوجيا المعلومات واحد أو أكثر هم مستخدمون في حساب عميل ضمن برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة".
2. يستخدم مشرفو تكنولوجيا المعلومات حساب Google لمصادقة أنفسهم.
3. تمرر طلبات واجهة برمجة التطبيقات رمز OAuth2 مميزًا لمصادقة طلبات واجهة برمجة التطبيقات نيابةً عن مشرف تكنولوجيا المعلومات.

حسابات العملاء

ينتمي مستخدمو (مشرفي تكنولوجيا المعلومات) وعمليات ضبط المؤسسة وأجهزتها إلى حساب عميل. حساب العميل يشبه مجموعة وليس مستخدمًا فرديًا. يقوم المورّد بإعداد العميل عندما تشتري المؤسسة أولاً أجهزة لبرنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة". يدير مشرفو تكنولوجيا المعلومات المستخدمين الآخرين في مؤسستهم باستخدام بوابة "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة".

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

يوضح المثال أدناه كيفية الحصول على حسابات العملاء للمستخدم الذي يفوّض طلب بيانات من واجهة برمجة التطبيقات:

Java

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

NET.

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

في تطبيقك، ستحتاج إلى التنقل بين صفحات نتائج الحسابات لأن المثال أعلاه يطبع أول 100 حساب فقط. لمعرفة كيفية إجراء ذلك، اطّلِع على النتائج المقسّمة على صفحات.

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

المستخدِمون

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

1. ربط حساب Google بعنوان البريد الإلكتروني:
2. الانضمام إلى حساب عميل باستخدام عنوان البريد الإلكتروني نفسه
3. يجب قبول بنود خدمة العميل في برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة".

لمساعدة مستخدمي تطبيقك في الإعداد، يمكنك إعادة استخدام إرشاداتنا لمشرفي تكنولوجيا المعلومات في البدء وربط حساب Google في مستنداتك الخاصة.

إدارة المستخدمين

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

قبول بنود الخدمة

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

تطلب البوابة تلقائيًا من المستخدمين قبول أحدث بنود خدمة عند تسجيل الدخول. لمعرفة الطُرق المقترَحة التي يمكن أن يتضمّنها تطبيقك، يُرجى الاطّلاع على بنود الخدمة المرتبطة بالاسم المعرِّف في دليل دمج "إدارة الخدمات الجوّالة للمؤسسات".

إضافة تفويض إلى تطبيقك

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

نقطة رئيسية: لتبسيط عملية إعداد التفويض والمصادقة، توفّر Google مكتبات للعملاء يمكنها تقليل مقدار الرموز البرمجية اللازمة لكتابتها وجعل رمزك أكثر فعالية. نقترح استخدام مكتبة عملاء لطلب واجهة برمجة تطبيقات العميل، ويمكنك الاطّلاع على دلائل البدء السريع لـ Java، و.NET، وPython.

التعليمات

نوفّر أدلة البدء السريع لتطبيقات Java و.NET وPython. إذا كنت تستخدم لغة مختلفة، اتّبِع الخطوتَين التاليتَين لإعداد التفويض لتطبيقك.

الخطوة 1: تفعيل واجهة برمجة التطبيقات لبرنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة"

1. يمكنك استخدام هذا المعالج لإنشاء مشروع أو اختياره في Google Developers Console وتفعيل واجهة برمجة التطبيقات تلقائيًا. انقر على متابعة، ثم الانتقال إلى بيانات الاعتماد .
2. انقر على إلغاء في صفحة "إنشاء بيانات اعتماد".
3. في أعلى الصفحة، اختَر علامة التبويب شاشة موافقة OAuth. اختَر عنوان بريد إلكتروني، وأدخِل اسم المنتج إذا لم يكن قد سبق ضبطه، ثم انقر على الزر حفظ.
4. اختَر علامة التبويب بيانات الاعتماد، وانقر على الزر إنشاء بيانات اعتماد، ثم اختَر معرِّف عميل OAuth.
5. اختَر نوع التطبيق استنادًا إلى نوع التطبيق الذي تنشئه.
6. اضبط الاسم على اسم تطبيقك.
7. انقر على إنشاء.
8. انقر على تنزيل JSON.
9. انقل الملف إلى دليل العمل وأعِد تسميته client_secret.json.

الخطوة 2: تثبيت مكتبة البرامج

لتثبيت مكتبة العملاء بلغتك:

1. انتقِل إلى Google API Client Libraries واختَر لغتك من قائمة اللغات المتوافقة.
2. اتّبِع الإرشادات لتثبيت مكتبة البرامج.

لمعرفة المزيد حول التفويض، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

نطاقات التفويض

استخدِم نطاق تفويض واجهة برمجة التطبيقات https://www.googleapis.com/auth/androidworkzerotouchemm في تطبيقك لطلب رمز دخول OAuth 2.0.

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

للاطّلاع على مثال على نطاق برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" المُستخدَم مع مكتبة برامج Google API، يمكنك الاطّلاع على دليل التشغيل السريع لـ Java و.NET وPython. لمعرفة المزيد من المعلومات عن استخدام نطاقات واجهة برمجة تطبيقات Google، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

أفضل الممارسات المتعلّقة بمفاتيح واجهة برمجة التطبيقات

عند استخدام مفاتيح واجهة برمجة التطبيقات في تطبيقاتك، احرِص على إبقائها آمنة. قد يؤدي الكشف عن بيانات الاعتماد علنًا إلى اختراق حسابك، ما قد يؤدي إلى فرض رسوم غير متوقعة على حسابك. للحفاظ على أمان مفاتيح واجهة برمجة التطبيقات، يُرجى اتّباع أفضل الممارسات التالية:

لا تضمِّن مفاتيح واجهة برمجة التطبيقات مباشرةً في الرمز

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

يجب عدم تخزين مفاتيح واجهة برمجة التطبيقات في الملفات داخل الشجرة المصدر لتطبيقك.

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

حصر إمكانية استخدام مفاتيح واجهة برمجة التطبيقات في عناوين IP وعناوين URL المُحيلة والتطبيقات المتوافقة مع الأجهزة الجوّالة التي تحتاج إليها فقط

يمكنك تقليل تأثير مفتاح واجهة برمجة التطبيقات المُخترَق من خلال حظر الوصول إلى عناوين IP وعناوين URL المُحيلة والتطبيقات المتوافقة مع الأجهزة الجوّالة التي يمكنها استخدام كل مفتاح. يمكنك تحديد المضيفين والتطبيقات التي يمكنها استخدام كل مفتاح من وحدة التحكم في واجهة Google API عن طريق فتح صفحة "بيانات الاعتماد" ثم إنشاء مفتاح جديد لواجهة برمجة التطبيقات بالإعدادات التي تريدها، أو تعديل إعدادات مفتاح واجهة برمجة التطبيقات.

حذف المفاتيح غير اللازمة لواجهة برمجة التطبيقات

للحدّ من التعرض للهجوم، احذف أي مفاتيح واجهة برمجة تطبيقات لم تعد بحاجة إليها.

إعادة إنشاء مفاتيح واجهة برمجة التطبيقات بشكل دوري

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

مراجعة الرمز قبل إصداره للجميع

تأكَّد من أنّ رمزك لا يحتوي على مفاتيح واجهة برمجة التطبيقات أو أي معلومات خاصة أخرى قبل إتاحته للجميع.