توضح هذه الوثيقة كيف يتم تثبيت التطبيقات على الأجهزة مثل الهواتف والأجهزة اللوحية أجهزة الكمبيوتر نقاط نهاية OAuth 2.0 من Google للسماح بالوصول إلى YouTube Data API.
يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محددة مع أحد التطبيقات مع الاحتفاظ أسماء المستخدمين وكلمات المرور وغيرها من المعلومات بخصوصية تامّة. على سبيل المثال، يمكن لأحد التطبيقات استخدام OAuth 2.0 للحصول على إذن تحميل فيديوهات إلى قناة المستخدم على YouTube
يتم توزيع التطبيقات المثبّتة على أجهزة فردية، ومن المفترض أن تكون هذه التطبيقات لا يمكنه الاحتفاظ بالأسرار. يمكنهم الوصول إلى واجهات Google APIs أثناء استخدام التطبيق أو عمل التطبيق في الخلفية.
يشبه تدفق التفويض هذا التدفق المستخدم تطبيقات خادم الويب. يتمثل الاختلاف الرئيسي في أن التطبيقات المثبّتة يجب أن تفتح متصفّح النظام وتوفِّر معرّف موارد منتظم (URI) لإعادة التوجيه على الجهاز لمعالجته الردود من خادم تفويض Google.
البدائل
بالنسبة إلى تطبيقات الأجهزة الجوّالة، قد تفضّل استخدام تسجيل الدخول بحساب Google Android أو iOS: تسجيل الدخول باستخدام حساب Google تتعامل مكتبات العملاء مع المصادقة وتفويض المستخدم، وقد يكون من الأسهل أكثر من البروتوكول الأدنى الموضح هنا.
التطبيقات التي تعمل على أجهزة لا تتيح استخدام متصفّح نظام أو ذات مصادر بيانات محدودة مثل أجهزة التلفزيون ووحدات تحكم الألعاب والكاميرات والطابعات، OAuth 2.0 لأجهزة التلفزيون الأجهزة أو تسجيل الدخول على أجهزة التلفزيون وأجهزة الإدخال المحدودة
المكتبات والنماذج
نقترح استخدام المكتبات والنماذج التالية لمساعدتك في تنفيذ مسار OAuth 2.0. الموضحة في هذا المستند:
- مكتبة AppAuth لنظام Android
- مكتبة AppAuth لنظام التشغيل iOS
- بروتوكول OAuth للتطبيقات: نظام التشغيل Windows عيّنات
المتطلبات الأساسية
تمكين واجهات برمجة التطبيقات لمشروعك
يحتاج أي تطبيق يستدعي واجهات Google APIs إلى تفعيل واجهات برمجة التطبيقات هذه في API Console
لتفعيل واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console
- If prompted, select a project, or create a new one.
- استخدِم صفحة المكتبة للعثور على YouTube Data API وتفعيلها. البحث عن أي تطبيق آخر هي واجهات برمجة التطبيقات التي سيستخدمها تطبيقك وتفعيلها أيضًا.
إنشاء بيانات اعتماد التفويض
يجب أن تكون بيانات اعتماد التفويض متاحة لأي تطبيق يستخدم OAuth 2.0 للوصول إلى واجهات Google APIs. التي تعرّف التطبيق على خادم OAuth 2.0 من Google. توضّح الخطوات التالية كيفية وإنشاء أوراق اعتماد لمشروعك. ويمكن لتطبيقاتك بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات. التي قمت بتمكينها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- تصف الأقسام أدناه أنواع البرامج وأساليب إعادة التوجيه التي يستخدمها محرّك بحث Google التي يدعمها خادم التفويض. اختر نوع العميل الموصى به ثم أدخِل اسمًا لعميل OAuth، واضبط الحقول الأخرى في النموذج على مناسبًا.
Android
- اختَر نوع تطبيق Android.
- أدخِل اسمًا لعميل OAuth. يظهر هذا الاسم على صفحات مشروعك Credentials page لتحديد هوية العميل.
- أدخل اسم حزمة تطبيق Android. يتم تحديد هذه القيمة في
السمة
package
للعنصر<manifest>
في ملف بيان التطبيق. - أدخِل الملف المرجعي لشهادة توقيع SHA-1 لتوزيع التطبيق.
- إذا كان تطبيقك يستخدم ميزة "توقيع التطبيق" من Google Play، انسخ SHA-1 بصمة رقمية من صفحة توقيع التطبيق في Play Console.
- إذا كنت تدير ملف تخزين المفاتيح ومفاتيح التوقيع الخاصة بك، استخدِم أداة keytool
تضمينها مع Java لطباعة معلومات الشهادة بتنسيق يمكن لشخص عادي قراءته. انسخ
SHA1
في القسمCertificate fingerprints
من الأمر keytool. عرض مصادقة العميل في وثائق Google APIs لنظام التشغيل Android لمزيد من المعلومات.
- (اختياري) يمكنك إثبات ملكية جهاز Android. التطبيق.
- انقر على إنشاء.
iOS
- اختَر نوع تطبيق iOS.
- أدخِل اسمًا لعميل OAuth. يظهر هذا الاسم على صفحات مشروعك Credentials page لتحديد هوية العميل.
- أدخِل معرِّف حزمة تطبيقك. معرِّف الحزمة هو قيمة CFBundleIdentifier في ملف موارد قائمة خصائص معلومات التطبيق (info.plist). القيمة أكثر شيوعًا في الجزء "عام" أو جزء التوقيع جزء الإمكانات في محرر مشروع Xcode. يتم عرض معرّف الحزمة أيضًا في قسم "المعلومات العامة" في صفحة "معلومات التطبيق" للتطبيق على موقع App Store Connect الإلكتروني من Apple.
- (اختياري)
أدخِل رقم تعريف تطبيقك على App Store إذا تم نشر التطبيق في App Store من Apple. رقم تعريف المتجر هو سلسلة رقمية مضمّنة في كل عنوان URL لـ Apple App Store.
- افتح تطبيق Apple App Store على جهاز iOS أو iPadOS
- ابحث عن تطبيقك.
- حدد زر "Share" (مشاركة) (مربع ورمز سهم لأعلى).
- اختَر نسخ الرابط.
- الصق الرابط في محرِّر نصوص. رقم تعريف App Store هو الجزء الأخير من عنوان URL.
مثلاً:
https://apps.apple.com/app/google/id284815942
- (اختياري)
أدخِل رقم تعريف الفريق. عرض العثور على رقم تعريف الفريق في مستندات حساب المطوِّر على Apple للحصول على مزيد من المعلومات.
- انقر على إنشاء.
UWP
- اختَر نوع تطبيق Universal Windows Platform.
- أدخِل اسمًا لعميل OAuth. يظهر هذا الاسم على صفحات مشروعك Credentials page لتحديد هوية العميل.
- أدخِل رقم تعريف تطبيقك المؤلّف من 12 حرفًا على Microsoft Store. يمكنك العثور على هذه القيمة في مركز شركاء Microsoft في صفحة هوية التطبيق في قسم "إدارة التطبيقات".
- انقر على إنشاء.
بالنسبة إلى تطبيقات UWP، لا يمكن أن يزيد طول مخطط URI المخصَّص عن 39 حرفًا.
مخطط معرِّف الموارد المنتظم (URI) المخصّص (Android وiOS وUWP)
مخططات معرف الموارد المنتظم (URI) المخصصة هي شكل من أشكال الروابط لمواضع معيّنة التي تستخدم مخططًا محددًا مخصصًا لفتح تطبيقك.
بديل لاستخدام مخططات معرف الموارد المنتظم (URI) المخصصة على Androidيمكنك استخدام حزمة تطوير البرامج (SDK) الخاصة بميزة "تسجيل الدخول بحساب Google" لنظام التشغيل Android التي توفر استجابة OAuth 2.0 مباشرة لتطبيقك، مما يغنيك عن الحاجة إلى معرّف الموارد المنتظم (URI) لإعادة التوجيه.
كيفية نقل البيانات إلى حزمة تطوير البرامج (SDK) الخاصة بميزة "تسجيل الدخول بحساب Google" لنظام التشغيل Android
إذا كنت تستخدم حاليًا مخططًا مخصّصًا لدمج OAuth على Android، عليك إجراء ما يلي: عليك إكمال الإجراءات أدناه للانتقال بشكل كامل إلى طريقة تسجيل الدخول الموصى بها في Google حزمة تطوير البرامج (SDK) لنظام التشغيل Android:
- عدِّل الرمز الخاص بك لاستخدام حزمة تطوير البرامج (SDK) الخاصة بتسجيل الدخول بحساب Google.
- إيقاف دعم المخطط المخصص في وحدة التحكم في واجهة Google API.
اتّبِع الخطوات التالية لنقل البيانات إلى حزمة تطوير البرامج (SDK) الخاصة بميزة "تسجيل الدخول بحساب Google" على أجهزة Android:
-
حدِّث الرمز الخاص بك لاستخدام حزمة تطوير البرامج (SDK) الخاصة بميزة "تسجيل الدخول بحساب Google" على أجهزة Android:
-
فحص التعليمات البرمجية لتحديد مكانك
إرسال طلب إلى خادم OAuth 2.0 في Google في حال استخدام مخطط مخصّص، سيظهر طلبك على النحو التالي:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
هو عنوان URL لإعادة توجيه المخطط المخصص في المثال أعلاه. يمكنك الاطّلاع على تعريف المَعلمةredirect_uri
للاطّلاع على مزيد من التفاصيل عن التنسيق لقيمة مخطط URI المخصص. -
دوِّن مَعلمتَي الطلب
scope
وclient_id
اللتين ستحتاج إلى ضبط حزمة تطوير البرامج (SDK) لتسجيل الدخول باستخدام حساب Google. -
اتّبِع
بدء دمج بيانات "تسجيل الدخول بحساب Google" في تطبيق Android
تعليمات لإعداد حزمة SDK. يمكنك تخطي
يمكنك الحصول على خطوة معرِّف عميل OAuth 2.0 لخادم الخلفية كما لو كنت تعيد استخدامها.
client_id
التي حصلت عليها من الخطوة السابقة. -
اتّبِع
تفعيل الوصول إلى واجهة برمجة التطبيقات من جهة الخادم
على التعليمات ويتضمن ذلك الخطوات التالية:
-
يمكنك استخدام طريقة
getServerAuthCode
لاسترداد رمز مصادقة للنطاقات التي تطلب إذنًا لها. - أرسِل رمز المصادقة إلى خلفية تطبيقك لاستبداله بإذن الوصول. إعادة التحميل الرمز المميز.
- يمكنك استخدام رمز الدخول الذي تم استرداده لإجراء اتصالات بـ Google APIs نيابةً عن المستخدم.
-
يمكنك استخدام طريقة
-
فحص التعليمات البرمجية لتحديد مكانك
إرسال طلب إلى خادم OAuth 2.0 في Google في حال استخدام مخطط مخصّص، سيظهر طلبك على النحو التالي:
-
إيقاف دعم المخطط المخصص في وحدة التحكم في واجهة Google API:
- الانتقال إلى بيانات اعتماد OAuth 2.0 قائمة العملاء واختيار برنامج Android
- انتقِل إلى قسم الإعدادات المتقدّمة، وأزِل العلامة من المربّع بجانب مربع الاختيار تفعيل مخطط URI المخصّص، وانقر على حفظ في إيقاف دعم مخطط معرف الموارد المنتظم (URI) المخصص.
تمكين مخطط URI المخصص
إذا كان البديل الموصى به لا يعمل لديك، يمكنك تمكين مخططات URI المخصصة برنامج Android باتّباع التعليمات التالية:- الانتقال إلى قائمة بيانات اعتماد OAuth 2.0 اختَر برنامج Android.
- انتقِل إلى قسم الإعدادات المتقدّمة، وتأكَّد من مربع الاختيار تمكين مخطط URI المخصَّص، وانقر على حفظ للتفعيل دعم مخطط معرف موارد منتظم (URI) مخصص.
يمكنك استخدام واجهة برمجة تطبيقات Chrome Identity التي توفر استجابة OAuth 2.0 مباشرة لتطبيقك، مما يغنيك عن الحاجة إلى معرّف الموارد المنتظم (URI) لإعادة التوجيه.
إثبات ملكية التطبيق (Android وChrome)
يمكنك إثبات ملكية تطبيقك للحدّ من خطر انتحال هوية التطبيق.
Android
لإكمال عملية إثبات الهوية، يمكنك استخدام حساب المطوّر الخاص بك على Google Play. إذا كان لديك حساب وتم تسجيل تطبيقك في Google Play Console ما يلي: لإكمال عملية التحقّق من المعلِنين بنجاح:
- يجب أن يكون لديك تطبيق مسجَّل في Google Play Console بنفس اسم الحزمة والملف المرجعي لشهادة توقيع SHA-1 كعميل OAuth لنظام التشغيل Android إكمال التحقق من أجل.
- يجب أن يكون لديك إذن المشرف للتطبيق في Google Play Console مزيد من المعلومات حول إدارة أذونات الوصول في Google Play Console
في قسم إثبات ملكية التطبيق في برنامج Android، انقر على زر إثبات الملكية لإكمال عملية إثبات الملكية.
إذا نجحت عملية التحقّق، سيظهر إشعار لتأكيد نجاح العملية. لعملية التحقق. وبخلاف ذلك، ستظهر رسالة خطأ.
لإصلاح تعذُّر إثبات الملكية، يُرجى تجربة ما يلي:
- تأكَّد من أنّ التطبيق الذي تريد إثبات ملكيته هو تطبيق مسجَّل في Google Play Console.
- تأكّد من امتلاكك إذن المشرف للتطبيق في Google Play Console
Chrome
لإكمال عملية إثبات الملكية، عليك استخدام حساب المطوّر في "سوق Chrome الإلكتروني". يجب استيفاء المتطلبات التالية لإكمال عملية التحقّق من المعلِنين بنجاح:
- يجب أن يكون لديك عنصر مسجَّل في لوحة بيانات المطوّر في "سوق Chrome الإلكتروني" له معرّف العنصر نفسه مثل عميل OAuth لإضافة Chrome الذي تكمل التحقق من أجله.
- يجب أن تكون ناشرًا لعنصر في "سوق Chrome الإلكتروني". مزيد من المعلومات حول إدارة أذونات الوصول في لوحة بيانات المطوّر في سوق Chrome الإلكتروني.
في القسم إثبات ملكية التطبيق ضمن برنامج "إضافة Chrome"، انقر على زر إثبات الملكية لإكمال عملية إثبات الملكية.
ملاحظة: يُرجى الانتظار بضع دقائق قبل إكمال عملية إثبات الهوية بعد منح حق الوصول إلى حسابك.
إذا نجحت عملية التحقّق، سيظهر إشعار لتأكيد نجاح العملية. لعملية التحقق. وبخلاف ذلك، ستظهر رسالة خطأ.
لإصلاح تعذُّر إثبات الملكية، يُرجى تجربة ما يلي:
- تأكَّد من توفّر عنصر مسجَّل في لوحة بيانات المطوّر في "سوق Chrome الإلكتروني" باستخدام معرِّف العنصر نفسه كعميل OAuth لإضافة Chrome الذي تكمل عملية إثبات الملكية من أجله.
- تأكّد من أنك ناشر التطبيق، أي يجب أن تكون إما الناشر الفردي. التطبيق أو عضو في مجموعة ناشر التطبيق. مزيد من المعلومات حول إدارة أذونات الوصول في لوحة بيانات المطوّر في سوق Chrome الإلكتروني.
- إذا عدّلت للتو قائمة ناشري المجموعة، تأكَّد من أنّ عضوية مجموعة الناشرين في لوحة بيانات المطوّر في سوق Chrome الإلكتروني. مزيد من المعلومات حول مزامنة قائمة عضوية الناشرين
عنوان IP الاسترجاعي (macOS وLinux وWindows Desktop)
لتلقي رمز التفويض باستخدام عنوان URL هذا، يجب أن يكون تطبيقك ينتظر استقبال البيانات على خادم الويب المحلي. هذا ممكن على العديد من المنصات، ولكن ليس كلها. ومع ذلك، إذا كانت المنصة هذه الطريقة هي الطريقة التي ننصح بها للحصول على رمز التفويض.
عندما يتلقّى تطبيقك استجابة التفويض، يجب أن يستجيب من خلال ما يلي لضمان سهولة الاستخدام: عرض صفحة HTML تطلب من المستخدم إغلاق المتصفح والعودة إلى تطبيقك.
الاستخدام المقترَح | تطبيقات macOS وLinux وWindows لسطح المكتب (ولكن ليس النظام الأساسي العام لـ Windows) |
قيم النماذج | اضبط نوع التطبيق على تطبيق سطح المكتب. |
نسخ/لصق يدوي
تحديد نطاقات الوصول
تتيح النطاقات لتطبيقك أن يطلب فقط الوصول إلى الموارد التي يحتاج إليها مع لتمكين المستخدمين من التحكم في مقدار الوصول الذي يمنحونه لتطبيقك. وبالتالي، علاقة عكسية بين عدد النطاقات المطلوبة واحتمال والحصول على موافقة المستخدم.
قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات سيحتاج تطبيقك إلى إذن للوصول إليه.
يستخدم الإصدار الثالث من YouTube Data API النطاقات التالية:
瞄准镜 | |
---|---|
https://www.googleapis.com/auth/youtube | 管理您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | 查看包含以下信息的列表:当前活跃的频道会员、其当前级别以及其成为会员的时间 |
https://www.googleapis.com/auth/youtube.force-ssl | 查看、修改以及永久删除您的 YouTube 视频、评分、评论和字幕 |
https://www.googleapis.com/auth/youtube.readonly | 查看您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.upload | 管理您的 YouTube 视频 |
https://www.googleapis.com/auth/youtubepartner | 查看和管理您在 YouTube 上的资源和关联内容 |
https://www.googleapis.com/auth/youtubepartner-channel-audit | 查看您的 YouTube 频道中关于 YouTube 合作伙伴试演的隐私信息 |
يحتوي مستند نطاقات واجهة برمجة تطبيقات OAuth 2.0 على رابط بالنطاقات التي قد تستخدمها للوصول إلى Google APIs.
الحصول على رموز الدخول عبر OAuth 2.0
توضّح الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 من Google للحصول على موافقة المستخدم على تنفيذ طلب واجهة برمجة التطبيقات نيابةً عنه يجب أن يحتوي التطبيق على البيانات التالية: الموافقة قبل أن تتمكّن من تنفيذ طلب Google API الذي يتطلب تفويض المستخدم.
الخطوة 1: إنشاء أداة للتحقّق من الرموز وإجراء اختبار
تتيح Google استخدام مفتاح التدقيق لتبادل الرموز. (PKCE) لجعل تدفق التطبيقات المثبتة أكثر أمانًا. يتمّ إنشاء أداة فريدة للتحقّق من الرموز لكلّ يتم إرسال طلب التفويض وقيمته التي تم تحويلها، المسماة "code_challenge"، إلى للحصول على رمز التفويض.
إنشاء أداة التحقّق من الرموز
code_verifier
عبارة عن سلسلة عشوائية مشفرة تعتمد على التشفير عالي القصور وتستخدم
الأحرف [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"، بحد أدنى للطول 43 حرفًا
و128 حرفًا بحدّ أقصى.
يجب أن تحتوي أداة التحقق من الرموز على قصور كافٍ لجعل تخمين القيمة غير عملي.
إنشاء تحدّي الرمز
هناك طريقتان لإنشاء تحدي الرمز.
طرق إنشاء تحدّي الرموز | |
---|---|
S256 (موصى بها) | تحدي الرمز هو تجزئة Base64URL (بدون مساحة متروكة) بترميز SHA256 للرمز البرمجي.
أداة التحقق.
|
عادي | اختبار الرمز هو نفس قيمة أداة التحقق من الرموز التي تم إنشاؤها أعلاه.
|
الخطوة 2: إرسال طلب إلى خادم OAuth 2.0 في Google
للحصول على إذن المستخدم، أرسل طلبًا إلى خادم تفويض Google على
https://accounts.google.com/o/oauth2/v2/auth
تتعامل نقطة النهاية هذه مع البحث في الجلسة النشطة،
وتصادق على المستخدم وتحصل على موافقة المستخدم. يمكن الوصول إلى نقطة النهاية عبر طبقة المقابس الآمنة فقط،
يرفض اتصالات HTTP (غير المؤمنة بطبقة المقابس الآمنة).
يدعم خادم التفويض معلمات سلسلة طلب البحث التالية للتثبيت التطبيقات:
المعلمات | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page |
||||||||||||||||
redirect_uri |
مطلوب
تحدِّد هذه السياسة طريقة إرسال خادم تفويض Google للاستجابة إلى تطبيقك. تتوفر هناك العديد من خيارات إعادة التوجيه المتاحة للتطبيقات المثبّتة، وسيكون عليك إعداد بيانات اعتماد التفويض باستخدام طريقة إعادة توجيه معيّنة في الاعتبار. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظِمة (URI) المعتمَدة لإعادة التوجيه من أجل OAuth 2.0.
والذي قمتَ بتهيئته في حساب عميلك
API Console
Credentials pageوإذا لم تتطابق هذه القيمة مع
معرّف موارد منتظم (URI) معتمد، سيظهر لك خطأ يعرض الجدول أدناه قيمة معلَمة
|
||||||||||||||||
response_type |
مطلوب
تحدِّد هذه السياسة ما إذا كانت نقطة نهاية Google OAuth 2.0 تعرض رمز تفويض. يمكنك ضبط قيمة المَعلمة على |
||||||||||||||||
scope |
مطلوب
حاسمة مفصولة بمسافات قائمة بالنطاقات التي تحدد الموارد التي يمكن لتطبيقك الوصول إليها على نيابة عن المستخدم. تحدِّد هذه القيم شاشة الموافقة التي تعرضها Google على المستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاج إليها فقط. مع تمكين المستخدمين أيضًا من التحكم في مقدار الوصول الذي يمنحونه إلى التطبيق. وبالتالي، توجد علاقة عكسية بين عدد النطاقات المطلوبة. واحتمالية الحصول على موافقة المستخدم. يستخدم الإصدار الثالث من YouTube Data API النطاقات التالية:
يوفر مستند نطاقات واجهة برمجة تطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات برمجة تطبيقات Google. |
||||||||||||||||
code_challenge |
مقترَح
تحدِّد هذه السياسة |
||||||||||||||||
code_challenge_method |
مقترَح
تحدِّد هذه السياسة الطريقة التي تم استخدامها لترميز |
||||||||||||||||
state |
مقترَح
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين
طلب التفويض واستجابة خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلمة لعدة أغراض، مثل توجيه المستخدم إلى الصفحة
المورد الصحيح في تطبيقك، وإرسال nonces، وتخفيف طلبات المواقع الإلكترونية المشتركة
التزوير. بما أنّه يمكن تخمين |
||||||||||||||||
login_hint |
اختياريّ
إذا كان التطبيق يعرف المستخدِم الذي يحاول المصادقة، يمكنه استخدام هذه المَعلمة لتقديم تلميح إلى خادم مصادقة Google. ويستخدم الخادم التلميح يمكنك تبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو من خلال واختيار جلسة تسجيل الدخول المتعدد المناسبة. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرِّف |
نماذج عناوين URL للتفويض
تعرض علامات التبويب أدناه نماذج عناوين URL للمصادقة الخاصة بخيارات معرّف الموارد المنتظم (URI) المختلفة لإعادة التوجيه.
يطلب كل عنوان URL الوصول إلى نطاق يسمح بالوصول لعرض نسخة حسابك على YouTube.عناوين URL متطابقة باستثناء قيمة المعلَمة redirect_uri
. عناوين URL
تحتوي أيضًا على معلمي response_type
وclient_id
المطلوبين
كمعلمة state
الاختيارية. يحتوي كل عنوان URL على فواصل أسطر ومسافات
وسهولة القراءة.
مخطط معرِّف موارد منتظم (URI) مخصّص
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
عنوان IP للاسترجاع
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
الخطوة 3: تطلب Google من المستخدِم الموافقة
في هذه الخطوة، يقرِّر المستخدم ما إذا كان سيمنح تطبيقك إذن الوصول المطلوب. في هذا الوقت تعرض Google نافذة موافقة تعرض اسم تطبيقك وGoogle API. الخدمات التي يطلب الإذن بالوصول إليها باستخدام بيانات اعتماد تفويض المستخدم ملخصًا لنطاقات الوصول التي سيتم منحها. تشير رسالة الأشكال البيانية يمكن للمستخدم الموافقة بعد ذلك على منح إذن الوصول إلى نطاق واحد أو أكثر يطلبه تطبيقك أو لرفض الطلب.
لا يحتاج طلبك إلى اتخاذ أي إجراء في هذه المرحلة، إذ إنّه ينتظر الردّ من خادم OAuth 2.0 في Google يشير إلى ما إذا تم منح أي إمكانية وصول. يتم شرح هذا الرد في الخطوة التالية.
الأخطاء
قد تعرض الطلبات المُرسَلة إلى نقطة نهاية تفويض OAuth 2.0 من Google رسائل خطأ موجّهة للمستخدمين. بدلاً من مسارات المصادقة والترخيص المتوقعة. رموز الخطأ الشائعة والمقترحة والحلول مدرجة أدناه.
admin_policy_enforced
يتعذّر على حساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. الاطّلاع على مقالة المساعدة "مشرف Google Workspace" التحكّم في الجهات الخارجية وصول التطبيقات الداخلية إلى بيانات Google Workspace لمزيد من المعلومات حول كيفية تقييد المشرف لإمكانية الوصول إلى جميع النطاقات أو الوصول إلى أن يتم منح إذن الوصول صراحةً إلى معرِّف عميل OAuth.
disallowed_useragent
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن غير مسموح به من قِبل Google سياسات OAuth 2.0.
Android
قد تظهر رسالة الخطأ هذه لمطوِّري تطبيقات Android عند فتح طلبات الحصول على إذن في
android.webkit.WebView
وبدلاً من ذلك، على المطوّرين استخدام مكتبات Android مثل
تسجيل الدخول باستخدام حساب Google لنظام التشغيل Android أو OpenID Foundation
تطبيق AppAuth لنظام التشغيل Android
قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي نظام التشغيل، والذي يشمل كلاً من Android App Links المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية علامات التبويب المخصَّصة في Android المكتبة أيضًا خيارًا مدعومًا.
iOS
قد يواجه مطوّرو iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في
WKWebView
وبدلاً من ذلك، يجب أن يستخدم المطوّرون مكتبات iOS مثل
تسجيل الدخول باستخدام حساب Google لأجهزة iOS أو OpenID Foundation
تطبيق AppAuth لنظام التشغيل iOS
قد يظهر هذا الخطأ لمطوِّري الويب عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في
وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من
موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي
نظام التشغيل، والذي يشمل كلاً من
الروابط العامة
المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية
SFSafariViewController
المكتبة أيضًا خيارًا مدعومًا.
org_internal
معرِّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من إمكانية الوصول إلى حسابات Google في محددة مؤسسة Google Cloud: لمزيد من المعلومات حول خيار التهيئة هذا، راجع نوع المستخدِم في مقالة المساعدة "إعداد شاشة طلب الموافقة المتعلقة ببروتوكول OAuth".
invalid_grant
إذا كنت تستخدم
أداة التحقق من الرموز
الاختبار، فإن المعلمة code_callenge
غير صالحة أو مفقودة. تأكد من أن
تم ضبط مَعلمة code_challenge
بشكلٍ صحيح.
عند إعادة تحميل رمز دخول، قد تكون صلاحية الرمز المميز قد انتهت أو انتهت تم إبطاله. عليك المصادقة على المستخدم مرة أخرى وطلب موافقة المستخدم للحصول على رموز مميّزة جديدة. في حال المتابعة لمشاهدة هذا الخطأ، فتأكد من تهيئة تطبيقك بشكل صحيح وأنك باستخدام الرموز والمعلمات الصحيحة في طلبك. بخلاف ذلك، قد يحتوي حساب المستخدم على حذف بيانات النشاط التجاري أو إيقافها.
redirect_uri_mismatch
redirect_uri
الذي تم تمريره في طلب التفويض لا يتطابق مع القيمة المُصرّح بها.
معرّف الموارد المنتظم (URI) لإعادة التوجيه لمعرّف عميل OAuth. مراجعة معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في
Google API Console Credentials page
قد يكون redirect_uri
الذي تم تمريره غير صالح لنوع العميل.
قد تشير المعلَمة redirect_uri
إلى مسار OAuth خارج النطاق (OOB) الذي يتضمن
تم إيقافها ولم تعد متاحة. ارجع إلى
دليل نقل البيانات لتعديل
التكامل.
invalid_request
حدث خطأ في الطلب الذي قدّمته. وقد يرجع ذلك إلى عدة أسباب:
- لم يتم تنسيق الطلب بشكل صحيح
- كان الطلب يفتقد إلى المعلمات المطلوبة
- يستخدم الطلب طريقة إذن لا تتوافق مع Google. التحقّق من بروتوكول OAuth طريقة الدمج تستخدم طريقة دمج موصى بها
- يُستخدم مخطط مخصص لعنوان URI لإعادة التوجيه : إذا ظهرت لك رسالة الخطأ نظام معرّف الموارد المنتظم (URI) المخصّص غير متاح في تطبيقات Chrome أو المخطّط المخصّص لمعرّف الموارد المنتظم (URI). لم يتم تفعيلها لبرنامج Android، هذا يعني أنّك تستخدم معرّف موارد منتظم (URI) مخصّص. غير متاح في تطبيقات Chrome ويتم إيقافه تلقائيًا على Android مزيد من المعلومات حول مخطَّط معرّف الموارد المنتظم (URI) المخصّص بدائل
الخطوة 4: التعامل مع استجابة خادم OAuth 2.0
تعتمد الطريقة التي يتلقّى بها تطبيقك الاستجابة بشأن التفويض على
لمخطَّط الموارد المنتظم (URI) لإعادة التوجيه بغض النظر عن المخطط،
سيحتوي الرد على رمز تفويض (code
) أو خطأ
(error
). على سبيل المثال، تشير error=access_denied
إلى أن المستخدم
رفض الطلب.
إذا منح المستخدم إذن الوصول إلى تطبيقك، يمكنك استبدال رمز التفويض بـ رمز الدخول ورمز التحديث كما هو موضح في الخطوة التالية.
الخطوة 5: تغيير رمز التفويض لإعادة التحميل والوصول رموز مميزة
لاستبدال رمز تفويض برمز دخول، عليك طلب
نقطة نهاية https://oauth2.googleapis.com/token
وضبط المَعلمات التالية:
الحقول | |
---|---|
client_id |
معرّف العميل الذي تم الحصول عليه من API Console Credentials page |
client_secret |
سر العميل الذي تم الحصول عليه من API Console Credentials page |
code |
رمز التفويض الذي تم عرضه من الطلب الأولي. |
code_verifier |
أداة التحقّق من الرموز التي أنشأتها في الخطوة الأولى: |
grant_type |
كما هو موضح في OAuth 2.0
المواصفات، يجب ضبط قيمة هذا الحقل على authorization_code . |
redirect_uri |
أحد معرفات الموارد المنتظمة (URI) لإعادة التوجيه المدرجة لمشروعك في
API Console
Credentials page للتعرّف على
client_id |
يعرض المقتطف التالي نموذج طلب:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
يردّ Google على هذا الطلب من خلال عرض كائن JSON يحتوي على إمكانية وصول قصيرة الأجل والرمز المميز للتحديث.
يحتوي الردّ على الحقول التالية:
الحقول | |
---|---|
access_token |
الرمز المميز الذي يرسله تطبيقك لمصادقة طلب واجهة برمجة تطبيقات Google. |
expires_in |
العمر المتبقي لرمز الدخول بالثواني. |
id_token |
ملاحظة: لا يتم عرض هذه السمة إلا إذا تضمّن طلبك نطاق هوية،
مثل openid أو profile أو email . القيمة هي
رمز JSON المميّز للويب (JWT) الذي يحتوي على معلومات الهوية الموقّعة رقميًا حول
المستخدم. |
refresh_token |
هو رمز مميّز يمكنك استخدامه للحصول على رمز دخول جديد. تظل الرموز المميزة لإعادة التحميل صالحة حتى يلغي المستخدم الدخول. لاحظ أن الرموز المميزة للتحديث يتم إرجاعها دائمًا للتطبيقات المثبتة. |
scope |
نطاقات الوصول الممنوحة من access_token معبر عنها في شكل قائمة
سلاسل حساسة لحالة الأحرف ومفصولة بمسافات. |
token_type |
نوع الرمز المميّز الذي تم عرضه. في الوقت الحالي، يتم ضبط قيمة هذا الحقل دائمًا على
Bearer |
يعرض المقتطف التالي نموذجًا للرد:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
الاتصال بـ Google APIs
بعد حصول تطبيقك على رمز الدخول، يمكنك استخدام الرمز لإجراء اتصالات
واجهة برمجة التطبيقات نيابةً عن مستخدم معيّن
حساب مستخدم في حال منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. للقيام بذلك، قم بتضمين
رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين طلب بحث access_token
مَعلمة أو قيمة Bearer
لعنوان HTTP يتضمّن Authorization
. عندما يكون ذلك ممكنًا،
ويُفضل استخدام عنوان HTTP، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم
يمكنك استخدام مكتبة برامج لإعداد الطلبات إلى Google APIs (على سبيل المثال، عند
في YouTube Data API).
تجدر الإشارة إلى أنّ YouTube Data API تتيح حسابات الخدمة لمنصة YouTube فقط. مالكو المحتوى الذين يملكون قنوات متعددة على YouTube ويديرونها، مثل سجلات وشركات الإنتاج واستوديوهات الأفلام.
يمكنك تجربة جميع واجهات Google APIs وعرض نطاقاتها من خلال ملعب OAuth 2.0.
أمثلة على الحصول على HTTP
اتصال
youtube.channels
نقطة نهاية (YouTube Data API) باستخدام Authorization: Bearer
HTTP
على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
إليك طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمت مصادقته باستخدام access_token
مَعلمة سلسلة طلب البحث:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
أمثلة على curl
يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl
. إليك
مثال يستخدم خيار عنوان HTTP (مفضّل):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
أو بدلاً من ذلك، خيار مَعلمة سلسلة طلب البحث:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
إعادة تحميل رمز الدخول
تنتهي صلاحية رموز الدخول بشكل دوري وتصبح بيانات اعتماد غير صالحة لطلب بيانات ذي صلة من واجهة برمجة التطبيقات. إِنْتَ إعادة تحميل رمز الدخول بدون طلب الإذن من المستخدم (بما في ذلك عندما يكون المستخدم غير موجود) إذا طلبت الوصول بلا اتصال بالإنترنت إلى النطاقات المرتبطة بالرمز المميّز.
لإعادة تحميل رمز دخول، يرسل تطبيقك رمز HTTPS POST
.
إلى خادم تفويض Google (https://oauth2.googleapis.com/token
) بأنه
يتضمن المعلَمات التالية:
الحقول | |
---|---|
client_id |
معرّف العميل الذي تم الحصول عليه من API Console. |
client_secret |
سر العميل الذي تم الحصول عليه من API Console.
(لا يسري client_secret على الطلبات الواردة من العملاء المسجلين كـ
تطبيقات Android أو iOS أو Chrome).
|
grant_type |
بالنسبة
المحددة في
مواصفات OAuth 2.0،
يجب ضبط قيمة هذا الحقل على refresh_token . |
refresh_token |
الرمز المميّز لإعادة التحميل الذي يظهر من تبادل رمز التفويض |
يعرض المقتطف التالي نموذج طلب:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
طالما لم يُبطل المستخدم إذن الوصول الممنوح للتطبيق، يستخدم خادم الرمز المميز تعرض كائن JSON يحتوي على رمز دخول جديد. يعرض المقتطف التالي عيّنة. الرد:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
لاحظ أن هناك حدودًا على عدد الرموز المميزة لإعادة التحميل التي سيتم إصدارها؛ حد واحد لكل مجموعة العميل/المستخدم، ومجموعة أخرى لكل مستخدم عبر جميع البرامج. يجب حفظ الرموز المميّزة لإعادة التحميل في مساحة التخزين طويلة الأجل ومواصلة استخدامها طالما أنها لا تزال صالحة. إذا كان طلبك يطلب عددًا كبيرًا جدًا من الرموز المميزة للتحديث، قد ينحصر في هذه الحدود، وفي هذه الحالة قد تظهر رموز تحديث عن العمل.
إبطال رمز مميّز
في بعض الحالات، قد يرغب المستخدم في إبطال إذن الوصول الممنوح لأحد التطبيقات. يمكن للمستخدم إبطال إذن الوصول عن طريق زيارة إعدادات الحساب يمكنك الاطّلاع على إزالة الوصول إلى الموقع الإلكتروني أو التطبيق ضمن مواقع الجهات الخارجية التطبيقات التي يمكنها الوصول إلى حسابك مستند الدعم للحصول على مزيد من المعلومات.
يمكن أيضًا لأحد التطبيقات إبطال إذن الوصول الممنوح له آليًا. يُعد الإبطال الآلي مهمًا في الحالات التي يلغي فيها المستخدم اشتراكه، أو يزيل أو تغيرت بشكل كبير موارد واجهة برمجة التطبيقات التي يتطلبها التطبيق. أو بعبارةٍ أخرى، أن يتضمن جزء من عملية الإزالة طلب بيانات من واجهة برمجة التطبيقات لضمان الحصول على الأذونات ممنوح للتطبيق.
لإبطال رمز مميّز آليًا، يطلب تطبيقك
https://oauth2.googleapis.com/revoke
وتتضمّن الرمز المميّز كمَعلمة:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
يمكن أن يكون الرمز المميز رمز دخول أو رمزًا مميزًا لإعادة التحميل. إذا كان الرمز المميز عبارة عن رمز دخول وكان له الرمز المميز المقابل للتحديث، سيتم أيضًا إبطال الرمز المميز للتحديث.
إذا تمت معالجة الإبطال بنجاح، فسيتم عندئذٍ رمز حالة HTTP للاستجابة
200
بالنسبة إلى حالات الخطأ، يتم عرض رمز حالة HTTP 400
مع
مع رمز خطأ.
قراءات إضافية
أفضل الممارسات الحالية لمجموعة مهندسي شبكة الإنترنت (IETF) بروتوكول OAuth 2.0 وتحدِّد التطبيقات الأصلية العديد من أفضل الممارسات الموثَّقة هنا.
تطبيق ميزة "الحماية العابرة للحساب"
خطوة إضافية ينبغي لك اتخاذها لحماية حسابات المستخدمين الحسابات تنفّذ ميزة "على مستوى الحساب" يمكنك الحماية باستخدام "خدمة الحماية العابرة للحساب" من 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
يمكنك الاطّلاع على حماية حسابات المستخدمين باستخدام صفحة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات حول كيفية تفعيل ميزة "الحماية العابرة للحساب" والاطّلاع على قائمة كاملة بالأحداث المتاحة.