تنفيذ خادم OAuth 2.0

معالجة طلبات التفويض

عندما تحتاج إلى إجراء عملية ربط الحساب باستخدام مسار رمز التفويض في OAuth 2.0، تُرسِل Google المستخدم إلى نقطة نهاية التفويض مع طلب يحتوي على المَعلمات التالية:

على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على الرابط https://myservice.example.com/auth، قد يبدو الطلب على النحو التالي:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

لكي تتمكّن نقطة نهاية التفويض من معالجة طلبات تسجيل الدخول، عليك اتّباع الخطوات التالية:

1. تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي حدّدته لشركة Google، وأنّ redirect_uri يتطابق مع عنوان URL لإعادة التوجيه الذي قدّمته Google لخدمتك. هذه عمليات التحقّق مهمة لمنع منح إذن الوصول إلى تطبيقات العميل غير المقصودة أو التي تم ضبط إعداداتها بشكلٍ خاطئ. إذا كنت تتيح استخدام مسارات متعددة لبروتوكول OAuth 2.0، تأكَّد أيضًا من أنّ القيمة response_type هي code.
2. تحقَّق مما إذا كان المستخدم مسجِّلاً الدخول إلى خدمتك. إذا لم يكن المستخدم مسجِّلاً الدخول، أكمِل خطوات تسجيل الدخول أو الاشتراك في الخدمة.
3. أنشئ رمز تفويض لاستخدامه من قِبل Google للوصول إلى واجهة برمجة التطبيقات. يمكن أن يكون رمز التفويض أي قيمة سلسلة، ولكن يجب أن يمثّل بشكل فريد المستخدم والعميل الذي يخصّه الرمز المميّز ووقت انتهاء صلاحية الرمز، ويجب ألا يكون قابلاً للتخمين. عادةً ما تُصدر رموًا مختصةً بالتفاويض تنتهي صلاحيتها بعد 10 دقائق تقريبًا.
4. تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة redirect_uri يحتوي على الشكل التالي:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. إعادة توجيه متصفّح المستخدم إلى عنوان URL المحدّد بالمَعلمة redirect_uri أدرِج رمز التفويض الذي أنشأته للتو وقيمة الحالة الأصلية غير المعدَّلة عند إعادة التوجيه من خلال إلحاق المَعلمتَين code وstate. في ما يلي مثال على عنوان URL الناتج:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

معالجة طلبات استبدال الرموز المميّزة

تتحمّل نقطة نهاية تبادل الرموز المميّزة في خدمتك مسؤولية نوعَين من عمليات مبادلة الرموز المميّزة:

• تبديل رموز التفويض برموز الدخول والرموز المميّزة لإعادة التحميل
• استبدال الرموز المميّزة لإعادة التحميل برموز الدخول

تتضمّن طلبات استبدال الرموز المميّزة المَعلمات التالية:

ضبط كيفية إرسال Google لبيانات الاعتماد إلى خادمك

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

ترسل Google بيانات الاعتماد تلقائيًا في نص الطلب. إذا كان خادم التفويض يتطلّب أن تكون بيانات اعتماد العميل في عنوان الطلب، عليك ضبط عملية دمج Cloud-to-cloud على النحو التالي:

الانتقال إلى Play Console

1. من قائمة المشاريع، انقر على فتح بجانب المشروع الذي تريد العمل عليه.

2. ضمن من السحابة الإلكترونية إلى السحابة الإلكترونية، اختَر تطوير.

3. انقر على فتح بجانب عملية الدمج.

4. انتقِل للأسفل إلى قسم الأذونات (اختيارية) وضَع علامة في مربّع الاختيار إرسال Google لمعرّف العميل والسرية من خلال عنوان المصادقة الأساسية لبروتوكول HTTP.

5. انقر على حفظ لحفظ التغييرات.

تبديل رموز التفويض برموز الدخول والرموز المميّزة لإعادة التحميل

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

بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي authorization_code، وتكون قيمة code هي قيمة رمز التفويض الذي منحته سابقًا إلى Google. في ما يلي مثال على طلب استبدال رمز التفويض برمز دخول ورمز مميز لإعادة التحميل:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

لتبديل رموز التفويض برمز دخول ورمز إعادة تحميل، تستجيب نقطة نهاية تبادل الرموز المميّزة لطلبات POST من خلال تنفيذ الخطوات التالية:

1. تأكَّد من أنّ client_id يحدِّد مصدر الطلب كمصدر مفوَّض، وأنّ client_secret يتطابق مع القيمة المتوقّعة.
2. تأكَّد من أنّ رمز التفويض صالح ولم تنته صلاحيته، وأنّ رقم تعريف العميل المحدّد في الطلب يتطابق مع رقم تعريف العميل المرتبط برمز التفويض.
3. تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة redirect_uri مطابق للقيمة المستخدَمة في طلب التفويض الأوّلي.
4. إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400 Bad Request مع {"error": "invalid_grant"} كنص.
5. بخلاف ذلك، استخدِم رقم تعريف المستخدم من رمز التفويض لإنشاء رمز مميَّز لإعادة التحميل ورمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب أن يكون من الصعب تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، والذي يكون عادةً بعد ساعة من إصدار الرمز. لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل.
6. عرض عنصر JSON التالي في نص استجابة HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

تخزِّن Google رمزَي الدخول المميّز وإعادة التحميل للمستخدم وتسجِّل انتهاء صلاحية رمز الدخول المميّز. عند انتهاء صلاحية رمز الدخول، تستخدم Google رمز إعادة التحميل للحصول على رمز دخول جديد من نقطة نهاية تبادل الرموز المميّزة.

استبدال الرموز المميّزة لإعادة التحميل برموز الدخول

عند انتهاء صلاحية رمز دخول، ترسل Google طلبًا إلى نقطة نهاية تبادل الرموز المميّزة لاستبدال رمز مميّز لإعادة التحميل برمز دخول جديد.

بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي refresh_token، وتكون قيمة refresh_token هي قيمة الرمز المميّز لإعادة التحميل الذي منحته سابقًا إلى Google. في ما يلي مثال على طلب استبدال رمز إعادة تحميل برمز دخول:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

لتبادل رمز إعادة التحميل للحصول على رمز دخول مميّز، يجب أن تستجيب نقطة نهاية تبادل الرموز المميّزةPOST لطلبات POST من خلال تنفيذ الخطوات التالية:

1. تأكَّد من أنّ client_id يحدِّد مصدر الطلب على أنّه Google، وأنّ client_secret يتطابق مع القيمة المتوقّعة.
2. تأكَّد من أنّ رمز إعادة التنشيط صالح، ومن أنّ معرّف العميل المحدّد في الطلب يتطابق مع معرّف العميل المرتبط برمز إعادة التنشيط.
3. إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400 Bad Request مع {"error": "invalid_grant"} كنص.
4. بخلاف ذلك، استخدِم رقم تعريف المستخدم من الرمز المميَّز لإعادة التحميل لإنشاء رمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب ألا يكون يمكن تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، وهو عادةً ما يكون بعد ساعة من إصدار الرمز.
5. عرض عنصر JSON التالي في نص استجابة HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

التعامل مع طلبات معلومات المستخدم

نقطة نهاية userinfo هي مورد OAuth 2.0 محمي يعرض مطالبات بشأن المستخدم المرتبط. يُعد تنفيذ نقطة نهاية userinfo واستضافتها اختياريًا، باستثناء حالات الاستخدام التالية:

• تسجيل الدخول إلى حساب مرتبط باستخدام Google One Tap.
• اشتراك سلس على AndroidTV.

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

على سبيل المثال، إذا كانت نقطة نهاية userinfo متاحة على https://myservice.example.com/userinfo، قد يظهر الطلب على النحو التالي:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

لتتمكّن نقطة نهاية معلومات المستخدم من معالجة الطلبات، عليك اتّباع الخطوات التالية:

1. يمكنك استخراج رمز الدخول من عنوان التفويض ومعلومات الإرجاع للمستخدم المرتبط برمز الدخول.
2. إذا كان رمز الدخول غير صالح، يمكنك عرض الخطأ HTTP 401 "غير مصرح به" مع استخدام عنوان الاستجابة WWW-Authenticate. في ما يلي مثال على استجابة خطأ في معلومات المستخدم:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

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

3. إذا كان رمز الدخول صالحًا، يتم عرض الاستجابة HTTP 200 مع كائن JSON التالي في نص HTTPS. الرد:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }
   

   إذا عرضت نقطة نهاية معلومات المستخدم استجابة نجاح HTTP 200، يتم تسجيل الرمز المميز الذي تم استرداده والمطالبات مقابل حساب المستخدم على Google.

   استجابة نقطة نهاية لمعلومات المستخدم
   sub	معرّف فريد يعرّف المستخدِم في نظامك.
   email	عنوان البريد الإلكتروني للمستخدم.
   given_name	اختياري: الاسم الأول للمستخدم.
   family_name	اختياري: اسم العائلة للمستخدم.
   name	اختياري: اسم المستخدم الكامل.
   picture	اختياري: صورة الملف الشخصي للمستخدم.