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

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

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

نظرة عامة

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

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

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

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

رموز الدخول

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

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

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

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

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

تتم مصادقة البرامج السرية، مثلاً GTAF، التي يتم إصدار بيانات اعتماد العميل لها، مع خادم OAuth الخاص بمشغِّل شبكة الجوّال أثناء تقديم طلبات إلى نقطة نهاية الرمز المميز. يتم استخدام مصادقة البرنامج لـ: \

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

تستخدم ميزة GTAF معلمة

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

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

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

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

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

إليك بعض النقاط التي يجب أخذها في الاعتبار عند إعداد نقطة نهاية الرمز المميز:

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

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

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

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

 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 (OK): \

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

يتم تضمين المعلمات في نص كيان استجابة HTTP باستخدام &"application;json". ويتم إنشاء تسلسلات المعلّمات في شكل بنية رمز كائن JavaScript (JSON) من خلال إضافة كل معلّمة على المستوى الأعلى في البنية. ويتم تضمين أسماء المعلّمات وقيم سلاسلها كسلاسل JSON. ويتم تضمين القيم الرقمية كأرقام JSON. ولا يهم ترتيب المعلّمات، بل يمكن أن يختلف.

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

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

     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.
• يجب أن يتجنّب "إطار الشفافية والموافقة" وضع افتراضات حول أحجام القيم. يجب أن يوثّق خادم OAuth حجم أي قيمة تحددها.

استجابة الخطأ

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

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

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

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

يتوقع GTAF عرض رمز الدخول مع القيمة "exp;es_in"(مدة البقاء). يجب ألا تقل قيمة انتهاء الصلاحية_في 900 ثانية، ويجب ألا تزيد عن بضع ساعات. يجب ألا يتسبب طلب رمز مميز جديد في انتهاء صلاحية الرموز المميزة الحالية.

لمزيد من التفاصيل حول مختلف أنواع المِنَح، يُرجى الاطّلاع على القسم 1.3 من RFC 6749.

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

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

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

ملاحظة: يجب أن يكون سر العميل "لتعديل بنود معالجة البيانات" الحقيقي أكثر أمانًا من ذلك المعروض في المثال.

لإنشاء سلسلة التفويض، معرّف العميل، ':&#39؛ وكلمة المرور يتم ربطهما وتشفير base64. يمكن تكرار ذلك في واجهة سطر أوامر على النحو التالي:

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

بعد ذلك، يقدِّم GTAF طلب HTTPS POST إلى خادم OAuth باستخدام بيانات الاعتماد هذه، ونوع منح بيانات Client_credential، والنطاق الذي تم ضبطه. على سبيل المثال، يبدو طلب GTAF&#39s مشابهًا للطلب الذي تم إنشاؤه من خلال:

$ 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	طلب_غير صالح	لا يتضمّن الطلب معلّمة مطلوبة أو يتضمّن قيمة معلّمة غير متوافقة (بخلاف نوع المنح) أو يكرّر معلّمة أو يتضمّن بيانات اعتماد متعددة أو يستخدم أكثر من آلية واحدة للمصادقة مع GTAF أو قد يكون مكتوبًا بشكلٍ غير صحيح.
HTTP 401	عميل_غير صالح	تعذّرت مصادقة العميل (على سبيل المثال، برنامج غير معروف، أو عدم تضمين برنامج مصادقة، أو طريقة مصادقة غير متوافقة). قد يعرض خادم OAuth رمز حالة HTTP 401 (غير مصرح به) للإشارة إلى أنظمة مصادقة HTTP المتوافقة. إذا حاول العميل المصادقة عبر حقل "طلب التفويض" و"التفويض&;;"، يجب أن يستجيب خادم OAuth برمز حالة HTTP 401 (غير مسموح به) وأن يتضمّن حقل "عنوان URL لـ WWW-Authenticate&quot، الذي يتوافق مع نظام المصادقة الذي يستخدمه العميل.
HTTP 500	تعذّر خادم OAuth

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