تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة تطبيقات OAuth لوكيل خطة البيانات

المستندات ذات الصلة

تمت الموافقة على معيار OAuth 2.0 بموجب RFC 6749. يتوفّر مستند مفصّل على الرابط https://oauth.net/2. تم تحديد المصادقة الأساسية لبروتوكول HTTP في القسم 2 من RFC 2617.

نظرة عامة

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

بدلاً من استخدام بيانات اعتماد المستخدم النهائي للوصول إلى الموارد المحمية، مثل تفاصيل خطة البيانات، يحصل GTAF على رمز مميز للوصول. يتم إصدار رموز الدخول إلى GTAF نيابةً عن بيانات اعتماد GTAF. بعد ذلك، تستخدم GTAF رمز الدخول للوصول إلى تفاصيل خطة البيانات التي يستضيفها DPA.

يوضّح الشكل التالي التدفق العالي المستوى للمعلومات:

الشكل 1. مسار OAuth التجريدي

رموز الدخول

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

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

يمكن أن تتضمّن رموز الدخول أشكالاً وبِنى وطرق استخدام مختلفة (مثل خصائص التشفير) استنادًا إلى متطلبات الأمان التي يفرضها مشغّل شبكة الجوّال. لا تتوافق GTAF إلا مع رموز الدخول من النوع "حامل" المحدّدة في [RFC6750].

مصادقة البرنامج

تعمل أداة GTAF كـ "عميل سرّي" وهي قادرة على الحفاظ على أمان كلمات المرور. لا يتيح إطار عمل GTAF حاليًا سوى مصادقة HTTP الأساسية للمصادقة مع DPA. يتم ترميز معرّف العميل باستخدام خوارزمية الترميز "application/x-www-form-urlencoded"، ويتم استخدام القيمة المرمّزة كاسم مستخدم، ويتم ترميز كلمة المرور باستخدام الخوارزمية نفسها واستخدامها ككلمة مرور.

تتم مصادقة البرامج السرية، مثل GTAF، التي يتم إصدار بيانات اعتماد العميل لها، مع خادم OAuth الخاص بشركة الاتصالات أثناء تقديم الطلبات إلى نقطة نهاية الرمز المميز. تُستخدم مصادقة البرنامج لتنفيذ ما يلي: \

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

تستخدم GTAF مَعلمة الطلب "client_id" لتعريف نفسها عند إرسال الطلبات إلى نقطة نهاية الرمز المميز.

من المهم بشكل خاص إمكانية تغيير بيانات اعتماد العميل. يجب أن يكون خادم OAuth قادرًا على توفير مجموعتَين متزامنتَين من بيانات الاعتماد أثناء التبديل، ويجب أن تتوفّر فيه إمكانية إيقاف بيانات الاعتماد. في عملية تغيير دوري لبيانات الاعتماد النموذجية:

تنشئ شركة الاتصالات بيانات اعتماد جديدة على خادم OAuth وتسلّمها إلى مدير الحساب الفني بطريقة آمنة.
تختبر Google بيانات الاعتماد الجديدة وتغيّر إعدادات GTAF لاستخدام بيانات الاعتماد الجديدة.
تُبلغ Google مشغّل شبكة الجوّال بأنّه قد يتم إيقاف بيانات الاعتماد القديمة.
يوقف مشغّل شبكة الجوّال بيانات الاعتماد ويرسل إشعارًا إلى Google
تتحقّق Google من أنّ بيانات الاعتماد القديمة لم تعُد صالحة

يجب أن يكون خادم OAuth قادرًا على توفير عملية التدوير المذكورة أعلاه.

نقطة نهاية الرمز المميز

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

في ما يلي بعض النقاط التي يجب مراعاتها عند ضبط نقطة نهاية الرمز المميّز:

يجب توفير موقع نقطة نهاية الرمز المميز في مستندات الخدمة.
قد يتضمّن معرّف الموارد المنتظم (URI) لنقطة النهاية مكوّن طلب بحث منسّقًا على النحو "application/x-www-form-urlencoded"، ويجب الاحتفاظ به عند إضافة مَعلمات طلب بحث إضافية. يجب ألا يتضمّن معرّف الموارد المنتظم (URI) لنقطة النهاية مكوّنًا مجزّأً.
بما أنّ الطلبات المُرسَلة إلى نقطة نهاية الرمز المميز تؤدي إلى نقل بيانات الاعتماد بنص عادي (في طلب HTTP واستجابته)، يجب أن يستخدم خادم OAuth الخاص بمشغّل شبكة الجوّال بروتوكول أمان طبقة النقل (TLS) لإرسال الطلبات إلى نقطة نهاية الرمز المميز.
تستخدم GTAF طريقة HTTP "POST" عند تقديم طلب للحصول على رمز دخول.
يجب التعامل مع المَعلمات المُرسَلة بدون قيمة على أنّها محذوفة من الطلب. يجب أن يتجاهل خادم OAuth مَعلمات الطلبات غير المعروفة. يجب عدم تضمين مَعلمات الطلب والاستجابة أكثر من مرّة واحدة.
لا تتوافق GTAF إلا مع رموز الدخول من النوع "حامل".

نطاق رمز الدخول

تسمح نقاط نهاية التفويض والرمز المميز للعميل بتحديد نطاق طلب الوصول باستخدام مَعلمة الطلب "scope". في المقابل، يستخدم خادم التفويض مَعلمة الردّ "scope" لإبلاغ العميل بنطاق رمز الدخول الذي تم إصداره.

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

لا يتطلّب إطار عمل GTAF تنفيذ النطاق، ولكنّه يتيح استخدام هذه الميزة. لمزيد من المعلومات، يُرجى الرجوع إلى القسم 3.3 من RFC 6749.

إصدار رمز دخول

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

الردّ الناجح

عندما يرسل GTAF طلبًا، يصدر خادم OAuth رمز دخول ورمز مميز اختياري لإعادة التحميل، وينشئ الردّ عن طريق إضافة المَعلمات التالية إلى نص الردّ على طلب HTTP مع رمز الحالة 200 (موافق): \

access_token: مطلوبة. رمز الدخول الذي يوفّره خادم OAuth. تتوقّع GTAF أن تعرض نقطة نهاية الرمز المميّز رمزًا مميّزًا للحامل.
‫expires_in: مطلوبة. تمثّل هذه السمة مدة صلاحية رمز الدخول بالثواني. على سبيل المثال، تشير القيمة "3600" إلى أنّ رمز الدخول ستنتهي صلاحيته بعد ساعة واحدة من وقت إنشاء الاستجابة. في حال عدم توفّرها، على خادم OAuth توفير وقت انتهاء الصلاحية بطرق أخرى أو توثيق القيمة التلقائية.
token_type: مطلوبة. تمثّل هذه السمة نوع الرمز المميّز الذي تم إصداره. لمزيد من المعلومات عن أنواع الرموز المميزة المختلفة، يُرجى الرجوع إلى القسم 7.1 من RFC 6749. القيمة غير حساسة لحالة الأحرف. لا تتوافق GTAF إلا مع رموز الدخول المميزة في وقت كتابة هذا المستند.
‫refresh_token: اختياري. رمز إعادة التحميل، الذي يمكن استخدامه للحصول على رموز دخول جديدة باستخدام إذن الوصول نفسه
scope: اختياري، إذا تم تنفيذه وكان مطابقًا للنطاق الذي طلبه إطار اعتماد Google، وإلا يكون مطلوبًا.

يتم تضمين المَعلمات في نص الكيان الخاص باستجابة HTTP باستخدام "application/json". يتم تحويل المَعلمات إلى سلسلة بتنسيق JavaScript Object Notation (JSON) من خلال إضافة كل مَعلمة إلى أعلى مستوى من البنية. يتم تضمين أسماء المَعلمات وقيم السلسلة كملفات JSON. يتم تضمين القيم الرقمية كأرقام JSON. لا يهم ترتيب المَعلمات ويمكن أن يختلف.

يجب أن يتضمّن خادم التفويض حقل عنوان الاستجابة "Cache-Control" في HTTP مع القيمة "no-store" في أي استجابة تحتوي على رموز مميزة أو بيانات اعتماد أو معلومات حساسة أخرى، بالإضافة إلى حقل عنوان الاستجابة "Pragma" مع القيمة "no-cache".

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

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

في ما يلي بعض النقاط المهمة التي يجب مراعاتها:

تتجاهل GTAF أسماء القيم غير المعروفة في الردّ.
لم يتم تحديد أحجام الرموز المميزة والقيم الأخرى التي يتم تلقّيها من خادم OAuth.
يجب أن تتجنّب GTAF وضع افتراضات بشأن أحجام القيم. يجب أن يوثّق خادم OAuth حجم أي قيمة يصدرها.

ردّ الخطأ

إذا تعذّر تنفيذ طلب تفويض لأي سبب، مثل عدم توفّر معرّف الموارد المنتظم لإعادة التوجيه أو عدم صلاحيته أو عدم تطابقه، أو إذا كان معرّف العميل غير متوفّر أو غير صالح، يجب أن يستجيب خادم OAuth برمز حالة HTTP 400 (طلب غير صالح) (ما لم يُحدّد خلاف ذلك)، ويجب أن يتضمّن مَعلمة واحدة على الأقل من المَعلمات المدرَجة في قسم "الاستجابة والرموز الخاصة بالأخطاء".

منح التفويض في GTAF

منح التفويض هو بيانات اعتماد تمثّل تفويض المستخدم النهائي (للوصول إلى الموارد المحمية، مثل معلومات رصيد البيانات) التي تستخدمها GTAF للحصول على رمز مميز للوصول.

يستخدم GTAF نوع منح الإذن client_credentials. في نوع منح الإذن client_credentials، يطلب GTAF رمزًا مميزًا باستخدام طلب HTTP POST ومصادقة HTTP الأساسية. يتم إرسال جميع الطلبات عبر بروتوكول أمان طبقة النقل (أي HTTPS)، ولا يمكن دمج GTAF مع خادم OAuth بدون شهادة TLS صالحة. يمكن أن تمرِّر GTAF نطاق رمز مميّز قابلاً للضبط، وستمرِّر نطاقًا فارغًا إذا لم يتم ضبط أي نطاق.

تتوقّع GTAF أن يتم عرض رمز دخول مع قيمة "expires_in" (مدة البقاء). يجب أن تكون قيمة expires_in‏ 900 ثانية على الأقل، ويجب ألا تتجاوز بضع ساعات. يجب ألا يؤدي طلب رمز مميّز جديد إلى انتهاء صلاحية الرموز المميزة الحالية قبل الموعد المحدد.

لمزيد من التفاصيل حول أنواع منح الأذونات المختلفة، راجِع القسم 1.3 من RFC 6749.

مثال على الطلب والاستجابة

لنفترض أنّ GTAF يتضمّن الإعداد التالي لخادم OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

ملاحظة: يجب أن يكون الرمز السري للعميل الخاص بـ DPA حقيقي أكثر أمانًا من الرمز السري المعروض في المثال.

لإنشاء سلسلة التفويض، يتم ربط معرّف العميل و":" وكلمة المرور معًا ثم يتم ترميزها باستخدام base64. يمكن تكرار ذلك في واجهة سطر الأوامر كما يلي:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

بعد ذلك، يرسل GTAF طلب HTTPS POST إلى خادم OAuth باستخدام بيانات الاعتماد هذه ونوع منح client_credentials والنطاق الذي تم ضبطه. في المثال، يبدو طلب GTAF مشابهًا للطلب الذي تم إنشاؤه بواسطة:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

لن تتطابق العناوين المستخدَمة في GTAF مع العناوين التي يرسلها curl، على الرغم من أنّ عنوان التفويض سيكون مطابقًا.

يتوقّع GTAF تلقّي ردّ بالتنسيق التالي:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

في ما يلي مثال على ردّ صالح:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

ملاحظة: يجب أن تكون الاستجابة ملف JSON صالحًا.

الاستجابة للأخطاء ورموزها

إذا تعذّر تنفيذ طلب تفويض من GTAF لأي سبب من الأسباب المذكورة في قسم "استجابة الخطأ"، يجب أن يستجيب خادم OAuth برمز حالة HTTP 400 (طلب غير صالح) (ما لم يُحدّد خلاف ذلك) وأن يتضمّن أحد المَعلمات التالية مع الاستجابة:

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

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

يتوقّع GTAF أن يتيح خادم OAuth الردود التالية التي تشير إلى حدوث خطأ:

رمز الخطأ	الرد	السبب
HTTP 400	invalid_request	الطلب يفتقر إلى مَعلمة مطلوبة، أو يتضمّن قيمة مَعلمة غير متوافقة (بخلاف نوع المنح)، أو يكرّر مَعلمة، أو يتضمّن بيانات اعتماد متعدّدة، أو يستخدم أكثر من آلية واحدة للمصادقة مع GTAF، أو يكون غير صالح بأي شكل آخر.
HTTP 401	invalid_client	تعذّرت مصادقة البرنامج (على سبيل المثال، برنامج غير معروف أو لم يتم تضمين مصادقة البرنامج أو طريقة مصادقة غير متوافقة). قد يعرض خادم OAuth رمز حالة HTTP 401 (غير مصرح به) للإشارة إلى مخطّطات مصادقة HTTP المتوافقة. إذا حاول العميل إجراء المصادقة من خلال حقل عنوان الطلب "Authorization"، يجب أن يستجيب خادم OAuth برمز حالة HTTP 401 (غير مصرّح به) وأن يتضمّن حقل عنوان الاستجابة "WWW-Authenticate" الذي يتطابق مع مخطط المصادقة الذي يستخدمه العميل.
HTTP 500	تعذُّر خادم OAuth

للاطّلاع على تفاصيل الردود الأخرى التي يمكن استخدامها لتصحيح الأخطاء، يُرجى الرجوع إلى القسم 5.2 من RFC 6749.

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