يمكن استخدام واجهات برمجة تطبيقات OAuth 2.0 من Google للمصادقة والتفويض. يوضّح هذا المستند طريقة تنفيذنا لبروتوكول OAuth 2.0 للمصادقة، وهو ما يتوافق مع مواصفات اتصال OpenID، وهو معتمد من OpenID. تنطبق أيضًا المستندات المتوفّرة في استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs على هذه الخدمة. إذا أردت استكشاف هذا البروتوكول بشكل تفاعلي، ننصحك باستخدام Google OAuth 2.0 Playground. للحصول على المساعدة على Stack Overflow، ضَع العلامة google-oauth على أسئلتك.
إعداد OAuth 2.0
قبل أن يتمكّن تطبيقك من استخدام نظام المصادقة OAuth 2.0 من Google لتسجيل دخول المستخدمين، عليك إعداد مشروع في Google Cloud Console للحصول على بيانات اعتماد OAuth 2.0، وتحديد معرّف الموارد المنتظم (URI) لإعادة التوجيه، وتخصيص معلومات العلامة التجارية التي تظهر للمستخدمين على شاشة موافقة المستخدم (اختياري). يمكنك أيضًا استخدام Cloud Console لإنشاء حساب خدمة وتفعيل الفوترة وإعداد الفلترة وتنفيذ مهام أخرى. لمزيد من التفاصيل، يُرجى الاطّلاع على Google Cloud Console المساعدة.
الحصول على بيانات اعتماد OAuth 2.0
تحتاج إلى بيانات اعتماد OAuth 2.0، بما في ذلك معرّف العميل وسر العميل، لمصادقة المستخدمين والوصول إلى واجهات Google APIs.
للاطّلاع على معرّف العميل وسر العميل لبيانات اعتماد OAuth 2.0 معيّنة، انقر على النص التالي: اختيار بيانات الاعتماد. في النافذة التي تفتح، اختَر مشروعك وبيانات الاعتماد التي تريدها، ثم انقر على عرض.
يمكنك أيضًا الاطّلاع على معرّف العميل وسر العميل من Clients page فيCloud Console:
- Go to the Clients page.
- انقر على اسم عميلك أو على رمز التعديل (create). يظهر معرّف العميل وسرّه في أعلى الصفحة.
ضبط معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه
يحدّد معرّف الموارد المنتظم لإعادة التوجيه الذي ضبطته في Cloud Console المكان الذي ترسل إليه Google الردود على طلبات المصادقة.
لإنشاء معرّفات الموارد المنتظمة لإعادة التوجيه أو عرضها أو تعديلها لبيانات اعتماد OAuth 2.0 معيّنة، اتّبِع الخطوات التالية:
- Go to the Clients page.
- انقر على العميل.
- عرض معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه أو تعديلها
إذا لم يكن هناك عميل مُدرَج في صفحة "العملاء"، يعني ذلك أنّ مشروعك لا يتضمّن بيانات اعتماد OAuth. لإنشاء حساب، انقر على إنشاء حساب عميل.
تخصيص شاشة موافقة المستخدم
بالنسبة إلى المستخدمين، تتضمّن تجربة المصادقة باستخدام بروتوكول OAuth 2.0 شاشة موافقة توضّح المعلومات التي يشاركها المستخدم والشروط السارية. على سبيل المثال، عندما يسجّل المستخدم الدخول، قد يُطلب منه منح تطبيقك إذن الوصول إلى عنوان بريده الإلكتروني ومعلومات حسابه الأساسية. يمكنك طلب الوصول إلى هذه المعلومات باستخدام المَعلمة
scope التي يدرجها تطبيقك في
طلب المصادقة. يمكنك أيضًا استخدام النطاقات لطلب الوصول إلى واجهات Google API الأخرى.
تعرض شاشة موافقة المستخدم أيضًا معلومات العلامة التجارية، مثل اسم منتجك وشعاره وعنوان URL للصفحة الرئيسية. يمكنك التحكّم في معلومات العلامة التجارية في Cloud Console.
لتفعيل شاشة الموافقة في مشروعك، اتّبِع الخطوات التالية:
- افتح Branding page في Google Cloud Console.
- If prompted, select a project, or create a new one.
- املأ النموذج وانقر على حفظ.
يوضّح مربّع حوار الموافقة التالي ما سيظهر للمستخدم عند توفّر مجموعة من نطاقات OAuth 2.0 ونطاقات Google Drive في الطلب. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة بروتوكول OAuth 2.0، لذلك لا يتضمّن معلومات عن العلامة التجارية التي سيتم ضبطها في Cloud Console.)
الوصول إلى الخدمة
توفّر Google والجهات الخارجية مكتبات يمكنك استخدامها للتعامل مع العديد من تفاصيل التنفيذ المتعلقة بمصادقة المستخدمين والوصول إلى واجهات Google API. وتشمل الأمثلة خدمات Google Identity ومكتبات برامج Google المتاحة لمجموعة متنوعة من الأنظمة الأساسية.
إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في بقية هذا المستند، والتي توضّح مسارات طلبات HTTP التي تستند إليها المكتبات المتاحة.
مصادقة المستخدم
تتضمّن مصادقة المستخدم الحصول على رمز مميّز صالح وتعزيزه. رموز التعريف هي ميزة موحّدة في اتصال OpenID مصمّمة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.
إنّ الطريقتَين الأكثر شيوعًا لمصادقة المستخدم والحصول على رمز مميّز للمعرّف هما ما يُعرفان باسم مسار "الخادم" ومسار "الوصول الضمني". يتيح مسار الخادم لخادم الخلفية الخاص بأحد التطبيقات إثبات هوية الشخص الذي يستخدم متصفّحًا أو جهازًا جوّالاً. يتم استخدام التدفق الضمني عندما يحتاج تطبيق من جهة العميل (عادةً تطبيق JavaScript يعمل في المتصفح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من استخدام خادم الخلفية.
يوضّح هذا المستند كيفية تنفيذ عملية المصادقة من جهة الخادم. يكون التدفق الضمني أكثر تعقيدًا بكثير بسبب المخاطر الأمنية المرتبطة بمعالجة الرموز المميزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ عملية تدفّق ضمني، ننصحك بشدة باستخدام خدمات Google لإثبات الهوية.
مسار الخادم
تأكَّد من إعداد تطبيقك في Cloud Console للسماح له باستخدام هذه البروتوكولات والتأكّد من هوية المستخدمين. عندما يحاول مستخدم تسجيل الدخول باستخدام Google، عليك إجراء ما يلي:
- إنشاء رمز مميّز للحالة مضاد للتزوير
- إرسال طلب مصادقة إلى Google
- تأكيد الرمز المميز للحالة المضاد للتزوير
- استبدال
codeبرمز الدخول ورمز التعريف - الحصول على معلومات المستخدم من الرمز المميّز للمعرّف
- مصادقة المستخدم
1. إنشاء رمز مميّز للحالة المضادة للتزوير
عليك حماية أمان المستخدمين من خلال منع هجمات تزوير الطلبات. تتمثّل الخطوة الأولى في إنشاء رمز مميّز فريد للجلسة يحتفظ بالحالة بين تطبيقك وجهاز المستخدم. يمكنك لاحقًا مطابقة رمز الجلسة المميز هذا مع رد المصادقة الذي تعرضه خدمة "تسجيل الدخول باستخدام Google OAuth" للتأكّد من أنّ المستخدم هو من يرسل الطلب وليس مهاجمًا خبيثًا. ويُشار إلى هذه الرموز المميزة غالبًا باسم رموز مميزة لمنع تزوير الطلبات عبر المواقع الإلكترونية (CSRF).
من الخيارات الجيدة لرمز الحالة المميز سلسلة من 30 حرفًا أو نحو ذلك يتم إنشاؤها باستخدام مولّد أرقام عشوائية عالي الجودة. والطريقة الأخرى هي إنشاء قيمة تجزئة من خلال توقيع بعض متغيرات حالة الجلسة باستخدام مفتاح يتم الاحتفاظ به سرًا في الخلفية.
يوضّح الرمز البرمجي التالي كيفية إنشاء رموز مميزة فريدة للجلسات.
PHP
يجب تنزيل مكتبة برامج Google APIs للغة PHP لاستخدام هذا النموذج.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
يجب تنزيل مكتبة برامج Google APIs للغة Java لاستخدام هذا النموذج.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
يجب تنزيل مكتبة برامج Google APIs للغة Python لاستخدام هذا النموذج.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. إرسال طلب مصادقة إلى Google
تتمثل الخطوة التالية في إنشاء طلب GET HTTPS باستخدام مَعلمات معرّف الموارد المنتظم المناسبة.
يُرجى ملاحظة استخدام HTTPS بدلاً من HTTP في جميع خطوات هذه العملية، إذ يتم رفض اتصالات HTTP. يجب استرداد عنوان URI الأساسي من مستند Discovery
باستخدام قيمة البيانات الوصفية authorization_endpoint. تفترض المناقشة التالية أنّ معرّف الموارد المنتظم الأساسي هو https://accounts.google.com/o/oauth2/v2/auth.
بالنسبة إلى الطلب الأساسي، حدِّد المَعلمات التالية:
client_id، الذي تحصل عليه من Cloud Console Clients page .response_type، والتي يجب أن تكونcodeفي طلب أساسي لمسار رمز التفويض. (يمكنك الاطّلاع على مزيد من المعلومات علىresponse_type.)scope، والتي يجب أن تكونopenid emailفي الطلب الأساسي. (مزيد من المعلومات علىscope)- يجب أن يكون
redirect_uriنقطة نهاية HTTP على الخادم ستتلقّى الاستجابة من Google. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي تم إعداده في Cloud Console Credentials page. إذا لم تتطابق هذه القيمة مع معرّف URI معتمد، سيتعذّر تنفيذ الطلب وسيظهر الخطأredirect_uri_mismatch. - يجب أن يتضمّن
stateقيمة الرمز المميز الفريد للجلسة المضاد للتزوير، بالإضافة إلى أي معلومات أخرى مطلوبة لاسترداد السياق عندما يعود المستخدم إلى تطبيقك، مثل عنوان URL الأولي. (مزيد من المعلومات علىstate) -
nonceهي قيمة عشوائية ينشئها تطبيقك وتتيح ميزة "الحماية من إعادة الإرسال" عند توفّرها. - يمكن أن يكون
login_hintهو عنوان البريد الإلكتروني للمستخدم أو السلسلةsub، وهي تعادل معرّف المستخدم على Google. في حال عدم تقديمlogin_hintوكان المستخدم مسجّلاً الدخول، ستتضمّن شاشة الموافقة طلبًا بالموافقة على إرسال عنوان البريد الإلكتروني للمستخدم إلى تطبيقك. (يمكنك الاطّلاع على مزيد من المعلومات فيlogin_hint.) - استخدِم المَعلمة
hdلتحسين عملية OpenID Connect لمستخدمي نطاق معيّن مرتبط بمؤسسة Google Workspace أو Cloud (يمكنك الاطّلاع على مزيد من المعلومات علىhd).
في ما يلي مثال على معرّف موارد منتظم (URI) كامل لمصادقة OpenID Connect، مع فواصل أسطر ومسافات لتسهيل القراءة:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
يجب أن يمنح المستخدمون موافقتهم إذا كان تطبيقك يطلب أي معلومات جديدة عنهم، أو إذا كان يطلب الوصول إلى حساب لم يسبق لهم الموافقة عليه.
3- تأكيد الرمز المميز للحالة المضادة للتزوير
يتم إرسال الردّ إلى redirect_uri الذي حدّدته في الطلب. يتم عرض جميع الردود في سلسلة طلب البحث:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
على الخادم، عليك التأكّد من أنّ الرمز state الذي تلقّيته من Google يتطابق مع الرمز المميز للجلسة الذي أنشأته في الخطوة 1. تساعد عملية التحقّق هذه في التأكّد من أنّ المستخدم هو من يرسل الطلب وليس نصًا برمجيًا ضارًا.
يوضّح الرمز التالي كيفية تأكيد رموز الجلسة التي أنشأتها في الخطوة 1:
PHP
يجب تنزيل مكتبة برامج Google APIs للغة PHP لاستخدام هذا النموذج.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
يجب تنزيل مكتبة برامج Google APIs للغة Java لاستخدام هذا النموذج.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
يجب تنزيل مكتبة برامج Google APIs للغة Python لاستخدام هذا النموذج.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. استبدال code برمز مميّز للوصول ورمز مميّز لمعرّف
تتضمّن الاستجابة المَعلمة code، وهي رمز تفويض صالح لمرة واحدة يمكن أن يستبدله الخادم برمز دخول ورمز تعريف. يُجري الخادم عملية التبادل هذه من خلال إرسال طلب HTTPS POST. يتم إرسال طلب POST إلى نقطة نهاية الرمز المميّز، والتي يجب استردادها من مستند Discovery باستخدام قيمة البيانات الوصفية token_endpoint. تفترض المناقشة التالية أنّ نقطة النهاية هي
https://oauth2.googleapis.com/token. يجب أن يتضمّن الطلب المَعلمات التالية في نص POST:
| الحقول | |
|---|---|
code |
رمز التفويض الذي يتم إرجاعه من الطلب الأوّلي |
client_id |
معرّف العميل الذي تحصل عليه من Cloud Console Clients page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
client_secret |
سر العميل الذي تحصل عليه من Cloud Console Clients page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
redirect_uri |
معرّف موارد منتظم (URI) معتمَد لإعادة التوجيه خاص بـ client_id المحدّد في
Cloud Console
Clients page، كما هو موضّح في
ضبط معرّف موارد منتظم (URI) لإعادة التوجيه |
grant_type |
يجب أن يحتوي هذا الحقل على قيمة authorization_code،
كما هو محدّد في مواصفات OAuth 2.0. |
قد يبدو الطلب الفعلي على النحو التالي:
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=https%3A//oauth2.example.com/code& grant_type=authorization_code
تحتوي الاستجابة الناجحة لهذا الطلب على الحقول التالية في مصفوفة JSON:
| الحقول | |
|---|---|
access_token |
رمز مميّز يمكن إرساله إلى إحدى واجهات Google API |
expires_in |
تمثّل هذه السمة مدة صلاحية رمز الدخول المتبقية بالثواني. |
id_token |
JWT يحتوي على معلومات هوية المستخدم التي وقّعتها Google رقميًا. |
scope |
نطاقات الوصول التي يمنحها access_token معبَّر عنها كقائمة من السلاسل الحساسة لحالة الأحرف والمفصولة بمسافات |
token_type |
تحدّد هذه السمة نوع الرمز المميز الذي تم عرضه. في الوقت الحالي، تكون قيمة هذا الحقل دائمًا
Bearer.
|
refresh_token |
(اختياري)
لا يظهر هذا الحقل إلا إذا تم ضبط المَعلمة |
5- الحصول على معلومات المستخدم من رمز المعرّف المميّز
رمز التعريف هو JWT، أي عنصر JSON مرمز باستخدام Base64 وموقّع تشفيرًا. في العادة، من المهم التحقّق من صحة رمز تعريف قبل استخدامه، ولكن بما أنّك تتواصل مباشرةً مع Google عبر قناة HTTPS بدون وسيط وتستخدم سر العميل لمصادقة نفسك لدى Google، يمكنك التأكّد من أنّ الرمز المميز الذي تتلقّاه صادر عن Google وصالح. إذا كان الخادم يمرّر رمز التعريف إلى مكوّنات أخرى في تطبيقك، من المهم للغاية أن تقوم المكوّنات الأخرى بالتحقّق من صحة الرمز المميز قبل استخدامه.
بما أنّ معظم مكتبات واجهات برمجة التطبيقات تجمع بين التحقّق من الصحة وعملية فك ترميز القيم المرمّزة باستخدام base64url وتحليل JSON بداخلها، من المحتمل أن ينتهي بك الأمر بالتحقّق من صحة الرمز المميّز على أي حال أثناء الوصول إلى المطالبات في الرمز المميّز لتعريف الهوية.
حمولة رمز التعريف
رمز التعريف هو عنصر JSON يحتوي على مجموعة من أزواج الاسم/القيمة. في ما يلي مثال على ذلك، تم تنسيقه لتسهيل قراءته:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
قد تحتوي رموز التعريف المميزة من Google على الحقول التالية (المعروفة باسم مطالبات):
| المطالبة | تم الإدخال | الوصف |
|---|---|---|
aud |
دائمًا | الجمهور المستهدف لرمز التعريف المميز هذا. يجب أن يكون أحد معرّفات عميل OAuth 2.0 لتطبيقك. |
exp |
دائمًا | وقت انتهاء الصلاحية الذي يجب عدم قبول الرمز المميّز للمعرّف بعده أو عنده يتم تمثيله بتنسيق وقت حقبة Unix (ثوانٍ صحيحة). |
iat |
دائمًا | الوقت الذي تم فيه إصدار رمز التعريف المميّز. يتم تمثيله في وقت حقبة Unix (ثوانٍ صحيحة). |
iss |
دائمًا | معرّف الجهة المصدرة للردّ استخدِم دائمًا
https://accounts.google.com أو accounts.google.com لرموز
التعريف على Google. |
sub |
دائمًا | معرّف للمستخدم، وهو فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. يمكن أن يتضمّن حساب Google عناوين بريد إلكتروني متعدّدة في أوقات مختلفة، ولكن لا يتم تغيير قيمة sub أبدًا. استخدِم sub داخل تطبيقك
كمفتاح المعرّف الفريد للمستخدم. الحد الأقصى للطول هو 255 حرفًا من أحرف ASCII مع مراعاة حالة الأحرف. |
at_hash |
تجزئة رمز الدخول توفّر عملية التحقّق من صحة رمز الدخول ما يثبت أنّه مرتبط برمز التعريف. إذا تم إصدار رمز التعريف المميز مع القيمة access_token في مسار الخادم، يتم تضمين هذه المطالبة دائمًا. يمكن استخدام هذا الادعاء كآلية بديلة للحماية من هجمات تزوير الطلبات على المواقع الإلكترونية، ولكن إذا اتّبعت الخطوة 1 والخطوة 3، لن يكون من الضروري التحقّق من رمز الدخول المميز. |
|
azp |
client_id مقدّم العرض المفوَّض لا تكون هذه المطالبة مطلوبة إلا عندما يكون الطرف الذي يطلب رمز التعريف المميز مختلفًا عن الجمهور المستهدف لرمز التعريف المميز. قد يحدث ذلك في Google للتطبيقات الهجينة التي يتوفّر فيها تطبيق ويب وتطبيق Android بنطاق client_id مختلف في OAuth 2.0، ولكن يشتركان في مشروع Google APIs نفسه. |
|
email |
عنوان البريد الإلكتروني للمستخدِم يتم توفيرها فقط إذا تضمّنت النطاق email في طلبك. قد لا تكون قيمة هذا الادعاء فريدة لهذا الحساب وقد تتغير بمرور الوقت، لذا يجب عدم استخدام هذه القيمة كمعرّف أساسي للربط بسجلّ المستخدم. ولا يمكنك أيضًا الاعتماد على نطاق مطالبة email لتحديد مستخدمي مؤسسات Google Workspace أو Cloud، بل عليك استخدام مطالبة hd بدلاً من ذلك.
|
|
email_verified |
تعرض القيمة "صحيح" إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم، أو "خطأ" في حال عدم إثباتها. | |
family_name |
اسم العائلة للمستخدم. يمكن تقديم هذه السمة عند توفّر مطالبة name. |
|
given_name |
الاسم الأول للمستخدم. يمكن تقديم هذه السمة عند توفّر مطالبة name. |
|
hd |
النطاق المرتبط بمؤسسة Google Workspace أو Cloud الخاصة بالمستخدم يتم توفيرها فقط إذا كان المستخدم ينتمي إلى مؤسسة Google Cloud. يجب التحقّق من هذا الادّعاء عند حصر إمكانية الوصول إلى أحد المراجع بأعضاء من نطاقات معيّنة فقط. يشير عدم توفّر هذا الادعاء إلى أنّ الحساب لا ينتمي إلى نطاق مستضاف على Google. | |
locale |
تمثّل هذه السمة اللغة المحلية للمستخدم، ويتم تحديدها باستخدام علامة لغة BCP 47.
يمكن تقديم هذه السمة عندما يكون هناك مطالبة name. |
|
name |
الاسم الكامل للمستخدم، بتنسيق قابل للعرض يمكن تقديم هذه السمة في الحالات التالية:
عند توفّر مطالبات |
|
nonce |
قيمة nonce التي يقدّمها تطبيقك في طلب المصادقة
يجب الحماية من هجمات إعادة الإرسال من خلال عرض هذه القيمة مرة واحدة فقط. |
|
picture |
تمثّل هذه السمة عنوان URL لصورة الملف الشخصي للمستخدم. يمكن تقديم هذه السمة في الحالات التالية:
عند توفّر مطالبات |
|
profile |
تمثّل هذه السمة عنوان URL لصفحة الملف الشخصي للمستخدم. يمكن تقديم هذه السمة في الحالات التالية:
عند توفّر مطالبات |
6. مصادقة المستخدم
بعد الحصول على معلومات المستخدم من رمز التعريف، يجب طلب البحث في قاعدة بيانات المستخدمين في تطبيقك. إذا كان المستخدم متوفّرًا في قاعدة البيانات، عليك بدء جلسة تطبيق لهذا المستخدم إذا استوفت استجابة Google API جميع متطلبات تسجيل الدخول.
إذا لم يكن المستخدم متوفّرًا في قاعدة بيانات المستخدمين، عليك إعادة توجيهه إلى مسار الاشتراك الخاص بالمستخدمين الجدد. قد تتمكّن من تسجيل المستخدم تلقائيًا استنادًا إلى المعلومات التي تتلقّاها من Google، أو على الأقل قد تتمكّن من ملء العديد من الحقول التي تحتاج إليها في نموذج التسجيل مسبقًا. بالإضافة إلى المعلومات الواردة في رمز التعريف، يمكنك الحصول على معلومات إضافية عن الملف الشخصي للمستخدم من نقاط نهاية الملف الشخصي للمستخدم.
مواضيع متقدمة
توضّح الأقسام التالية واجهة Google OAuth 2.0 API بتفصيل أكبر. هذه المعلومات موجّهة للمطوّرين الذين لديهم متطلبات متقدّمة بشأن المصادقة والتفويض.
الوصول إلى واجهات برمجة تطبيقات Google الأخرى
من مزايا استخدام OAuth 2.0 للمصادقة أنّ تطبيقك يمكنه الحصول على إذن لاستخدام واجهات Google APIs الأخرى نيابةً عن المستخدم (مثل YouTube أو Google Drive أو "تقويم Google" أو "جهات اتصال Google") في الوقت نفسه الذي تتم فيه مصادقة المستخدم. لإجراء ذلك، عليك تضمين النطاقات الأخرى التي تحتاج إليها في طلب المصادقة الذي ترسله إلى Google. على سبيل المثال، لإضافة الفئة العمرية للمستخدم إلى طلب المصادقة، مرِّر مَعلمة نطاق بقيمة openid email https://www.googleapis.com/auth/profile.agerange.read. تتم مطالبة المستخدم بشكل مناسب على شاشة الموافقة. سيسمح رمز الدخول الذي تتلقّاه من Google لتطبيقك بالوصول إلى جميع واجهات برمجة التطبيقات ذات الصلة بنطاقات الوصول التي طلبتها وتم منحك إذن الوصول إليها.
رموز إعادة التحميل
في طلب الوصول إلى واجهة برمجة التطبيقات، يمكنك طلب عرض رمز مميز لإعادة التحميل أثناء عملية
code التبادل. يوفّر رمز التحديث لتطبيقك إمكانية الوصول المستمر إلى واجهات برمجة تطبيقات Google عندما لا يكون المستخدم متواجدًا في تطبيقك. لطلب رمز مميّز لإعادة التحميل، أضِف المَعلمة access_type إلى offline في طلب المصادقة.
الاعتبارات:
- احرِص على تخزين رمز التحديث بشكل آمن ودائم، لأنّه لا يمكنك الحصول على رمز تحديث إلا في المرة الأولى التي تنفّذ فيها عملية تبادل الرموز.
- هناك حدود لعدد رموز التحديث التي يتم إصدارها: حد واحد لكل مجموعة من العميل/المستخدم، وحد آخر لكل مستخدم على مستوى جميع العملاء. إذا كان تطبيقك يطلب عددًا كبيرًا جدًا من رموز التحديث، قد يواجه هذه الحدود، وفي هذه الحالة، تتوقف رموز التحديث الأقدم عن العمل.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعادة تحميل رمز دخول (الوصول بلا إنترنت).
طلب إعادة الموافقة
يمكنك أن تطلب من المستخدم إعادة منح الإذن لتطبيقك من خلال ضبط المَعلمة prompt على consent في طلب المصادقة. عند تضمين prompt=consent،
تظهر شاشة الموافقة في كل مرة يطلب فيها تطبيقك تفويض نطاقات
الوصول، حتى إذا تم منح جميع النطاقات لمشروعك على Google APIs سابقًا. لهذا السبب، يجب تضمين السمة prompt=consent فقط عند الضرورة.
لمزيد من المعلومات عن المَعلمة prompt، يُرجى الاطّلاع على prompt
في جدول مَعلمات معرّف الموارد المنتظم للمصادقة.
مَعلمات معرّف الموارد المنتظم (URI) للمصادقة
يقدّم الجدول التالي أوصافًا أكثر اكتمالاً للمعلمات التي تقبلها واجهة برمجة التطبيقات الخاصة بالمصادقة باستخدام OAuth 2.0 من Google.
| المَعلمة | مطلوب | الوصف |
|---|---|---|
client_id |
(مطلوب) | سلسلة معرّف العميل التي تحصل عليها من Cloud Console Clients page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
nonce |
(مطلوب) | قيمة عشوائية ينشئها تطبيقك وتتيح الحماية من إعادة التشغيل. |
response_type |
(مطلوب) | إذا كانت القيمة code، يتم إطلاق
مسار رمز التفويض الأساسي،
الذي يتطلّب POST إلى نقطة نهاية الرمز المميز للحصول على الرموز المميزة. إذا كانت القيمة token id_token أو id_token token، يتم تشغيل التدفق الضمني، ما يتطلّب استخدام JavaScript في معرّف الموارد المنتظم (URI) لإعادة التوجيه من أجل استرداد الرموز المميزة من معرّف URI #fragment. |
redirect_uri |
(مطلوب) | تحدّد هذه السمة المكان الذي يتم إرسال الردّ إليه. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم إعادة التوجيه المسموح بها التي تحدّدها في Cloud Console Clients page (بما في ذلك نظام HTTP أو HTTPS، حالة الأحرف، وعلامة "/" اللاحقة، إن وجدت). |
scope |
(مطلوب) | يجب أن تبدأ مَعلمة النطاق بالقيمة في حال توفُّر قيمة النطاق في حال توفُّر قيمة النطاق بالإضافة إلى نطاقات OpenID المحدّدة هذه، يمكن أن يتضمّن وسيطة النطاق أيضًا قيم نطاق أخرى. يجب فصل جميع قيم النطاق بمسافة. على سبيل المثال، إذا أردت
الوصول إلى ملفات معيّنة في Google Drive الخاص بأحد المستخدمين، قد يكون مَعلمة النطاق
للحصول على معلومات حول النطاقات المتاحة، يُرجى الاطّلاع على نطاقات OAuth 2.0 في Google APIs أو المستندات الخاصة بواجهة Google API التي تريد استخدامها. |
state |
(اختياري، ولكن ننصح به بشدة) | سلسلة مبهمة يتم إرسالها ذهابًا وإيابًا في البروتوكول، أي يتم عرضها كمعلَمة URI في عملية المصادقة الأساسية، وفي معرّف URI يمكن أن يكون |
access_type |
(اختياري) | القيمتان المسموح بإدراجهما هما offline وonline. يتم توثيق التأثير في الوصول بلا إنترنت. إذا تم طلب رمز مميز للوصول، لن يتلقّى العميل رمزًا مميزًا لإعادة التحميل ما لم يتم تحديد القيمة offline. |
display |
(اختياري) | قيمة سلسلة ASCII لتحديد طريقة عرض خادم التفويض لصفحات واجهة مستخدم المصادقة والموافقة. يتم تحديد القيم التالية وتقبلها خوادم Google، ولكن ليس لها أي تأثير على سلوك تدفق البروتوكول: page وpopup وtouch وwap. |
hd |
(اختياري) | تبسيط عملية تسجيل الدخول إلى الحسابات التي تملكها مؤسسة Google Cloud من خلال تضمين نطاق مؤسسة Google Cloud (على سبيل المثال، mycollege.edu)، يمكنك الإشارة إلى أنّه يجب تحسين واجهة مستخدم اختيار الحساب لتناسب الحسابات في هذا النطاق. لتحسين الأداء لحسابات المؤسسات على Google Cloud بشكل عام بدلاً من نطاق مؤسسة واحد على Google Cloud، اضبط قيمة علامة النجمة ( لا تعتمد على تحسين واجهة المستخدم هذا للتحكّم في المستخدمين الذين يمكنهم الوصول إلى تطبيقك، لأنّه يمكن تعديل الطلبات من جهة العميل. احرص على التحقّق من أنّ رمز التعريف الذي تم عرضه يتضمّن قيمة مطالبة |
include_granted_scopes |
(اختياري) | إذا تم توفير هذه المَعلمة بالقيمة true وتم منح طلب التفويض، سيتضمّن التفويض أي تفويضات سابقة تم منحها لمجموعة المستخدم/التطبيق هذه لنطاقات أخرى. راجِع التفويض التزايدي.
يُرجى العِلم أنّه لا يمكنك إجراء تفويض متزايد باستخدام مسار "التطبيق المثبَّت". |
login_hint |
(اختياري) | عندما يعرف تطبيقك المستخدم الذي يحاول مصادقته، يمكنه تقديم هذه المَعلمة كتلميح إلى خادم المصادقة. يؤدي تمرير هذه الإشارة إلى إيقاف أداة اختيار الحساب، ويتم إما ملء مربّع البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول، أو اختيار الجلسة المناسبة (إذا كان المستخدم يستعمل ميزة تسجيل الدخول المتعدد)، ما يساعدك في تجنُّب المشاكل التي تحدث إذا سجّل تطبيقك الدخول إلى حساب المستخدم الخاطئ.
يمكن أن تكون القيمة إما عنوان بريد إلكتروني أو السلسلة sub، وهي
تعادل معرّف المستخدم على Google. |
prompt |
(اختياري) | قائمة مفصولة بمسافات تتضمّن قيم السلسلة التي تحدّد ما إذا كان خادم التفويض يطلب من المستخدم إعادة المصادقة والموافقة. القيم المحتمَلة هي:
إذا لم يتم تحديد أي قيمة ولم يسبق للمستخدم منح إذن الوصول، سيتم عرض شاشة موافقة للمستخدم. |
hl |
(اختياري) | علامة لغة BCP 47 تُستخدَم لتحديد
لغة العرض لشاشات تسجيل الدخول واختيار الحساب والموافقة. في حال عدم توفير هذه المَعلمة، سيتم تلقائيًا ضبط اللغة على اللغة المحدّدة في حساب Google أو إعدادات المتصفّح لدى المستخدم. على سبيل المثال، لطلب واجهة المستخدم باللغة الإنجليزية البريطانية، اضبط المَعلمة على
en-GB.
|
التحقّق من صحة رمز مميّز لتعريف الهوية
عليك التحقّق من صحة جميع رموز التعريف المميزة على خادمك ما لم تكن على علم بأنّها واردة مباشرةً من Google. على سبيل المثال، يجب أن يتأكّد الخادم من صحة أي رموز تعريف يتلقّاها من تطبيقات العميل.
في ما يلي بعض الحالات الشائعة التي قد ترسل فيها رموز التعريف إلى الخادم:
- إرسال رموز تعريف مع الطلبات التي تتطلّب المصادقة تخبرك رموز التعريف بالمستخدم المحدّد الذي يرسل الطلب والعميل الذي تم منح رمز التعريف له.
رموز التعريف حسّاسة ويمكن إساءة استخدامها إذا تم اعتراضها. يجب التأكّد من معالجة هذه الرموز المميزة بشكل آمن من خلال نقلها عبر HTTPS فقط وباستخدام بيانات POST فقط أو ضمن عناوين طلبات. إذا كنت تخزّن رموز التعريف على خادمك، يجب تخزينها بشكل آمن أيضًا.
من الميزات التي تجعل رموز التعريف مفيدة هي إمكانية نقلها بين مختلف مكوّنات تطبيقك، إذ يمكن لهذه المكوّنات استخدام رمز التعريف كآلية مصادقة بسيطة لمصادقة التطبيق والمستخدم. ولكن قبل أن تتمكّن من استخدام المعلومات الواردة في رمز التعريف أو الاعتماد عليها كإثبات على أنّ المستخدم قد أجرى مصادقة، يجب التحقّق من صحتها.
تتطلّب عملية التحقّق من صحة رمز التعريف عدة خطوات:
- تأكَّد من أنّ رمز التعريف المميّز تم توقيعه بشكل صحيح من قِبل جهة الإصدار. يتم توقيع الرموز المميزة الصادرة عن Google باستخدام إحدى الشهادات المتوفّرة في معرّف الموارد المنتظم (URI) المحدّد في قيمة البيانات الوصفية
jwks_uriضمن مستند Discovery. - تأكَّد من أنّ قيمة مطالبة
issفي رمز التعريف تساويhttps://accounts.google.comأوaccounts.google.com. - تأكَّد من أنّ قيمة مطالبة
audفي رمز التعريف تساوي رقم تعريف العميل الخاص بتطبيقك. - تأكَّد من عدم انقضاء وقت انتهاء الصلاحية (
expالمطالبة) لرمز التعريف. - إذا حدّدت قيمة للمَعلمة hd في الطلب، تأكَّد من أنّ رمز التعريف المميّز يتضمّن مطالبة
hdتتطابق مع نطاق مقبول مرتبط بمؤسسة Google Cloud.
تتضمّن الخطوات من 2 إلى 5 مقارنات بين السلاسل والتاريخ فقط، وهي بسيطة جدًا، لذا لن نذكرها بالتفصيل هنا.
الخطوة الأولى أكثر تعقيدًا، وتتضمّن التحقّق من التوقيعات المشفرة. لأغراض تصحيح الأخطاء، يمكنك استخدام نقطة النهاية tokeninfo من Google للمقارنة مع المعالجة المحلية التي يتم تنفيذها على الخادم أو الجهاز. لنفترض أنّ قيمة رمز التعريف هي
XYZ123. عندئذٍ، عليك إلغاء الإشارة إلى معرّف الموارد الموحّد https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. إذا كان توقيع الرمز المميز صالحًا، سيكون الردّ هو حمولة JWT في شكل عنصر JSON تم فك ترميزه.
نقطة النهاية tokeninfo مفيدة لتصحيح الأخطاء، ولكن لأغراض الإنتاج، استردِد المفاتيح العامة من Google من نقطة نهاية المفاتيح ونفِّذ عملية التحقّق محليًا. يجب استرداد معرّف الموارد المنتظم (URI) للمفاتيح من مستند الاكتشاف
باستخدام قيمة البيانات الوصفية jwks_uri. قد يتم تقييد عدد الطلبات التي يتم إرسالها إلى نقطة نهاية تصحيح الأخطاء، أو قد تخضع لأخطاء متقطّعة.
بما أنّ Google لا تغيّر مفاتيحها العامة إلا نادرًا، يمكنك تخزينها مؤقتًا باستخدام توجيهات التخزين المؤقت الخاصة باستجابة HTTP، وفي معظم الحالات، يمكنك إجراء عملية التحقّق المحلية بكفاءة أكبر بكثير من استخدام نقطة النهاية tokeninfo. تتطلّب عملية التحقّق هذه استرداد الشهادات وتحليلها، وإجراء عمليات التشفير المناسبة للتحقّق من التوقيع. لحسن الحظ، تتوفّر مكتبات تم تصحيح أخطائها بشكل جيد في مجموعة متنوعة من اللغات لإجراء ذلك (راجِع jwt.io).
الحصول على معلومات الملف الشخصي للمستخدم
للحصول على معلومات إضافية عن الملف الشخصي للمستخدم، يمكنك استخدام رمز الدخول (الذي يتلقّاه تطبيقك أثناء مسار المصادقة) ومعيار اتصال OpenID:
للامتثال لمعيار OpenID، عليك تضمين قيم نطاق
openid profileفي طلب المصادقة.إذا أردت تضمين عنوان البريد الإلكتروني للمستخدم، يمكنك تحديد قيمة نطاق إضافية هي
email. لتحديد كلّ منprofileوemail، يمكنك تضمين المَعلمة التالية في معرّف الموارد المنتظم (URI) لطلب المصادقة:scope=openid%20profile%20email
- أضِف رمز الدخول إلى عنوان التفويض وأرسِل طلب
GETعبر HTTPS إلى نقطة نهاية userinfo، التي يجب استردادها من مستند Discovery باستخدام قيمة بياناتuserinfo_endpointالوصفية. تتضمّن استجابة userinfo معلومات عن المستخدم، كما هو موضّح فيOpenID Connect Standard Claimsوقيمة البيانات الوصفيةclaims_supportedفي مستند Discovery. يمكن للمستخدمين أو مؤسساتهم اختيار تقديم أو حجب حقول معيّنة، لذا قد لا تتلقّى معلومات عن كل حقل من نطاقات الوصول المصرّح بها.
مستند الاستكشاف
يتطلّب بروتوكول OpenID Connect استخدام نقاط نهاية متعدّدة لمصادقة المستخدمين وطلب الموارد، بما في ذلك الرموز المميزة ومعلومات المستخدمين والمفاتيح العامة.
لتسهيل عمليات التنفيذ وزيادة المرونة، يتيح OpenID Connect استخدام "مستند اكتشاف"، وهو مستند JSON يمكن العثور عليه في موقع معروف ويتضمّن أزواج قيم أو مفاتيح تقدّم تفاصيل حول إعدادات موفّر OpenID Connect، بما في ذلك معرّفات الموارد المنتظمة لنقاط نهاية التفويض والرموز المميزة والإبطال ومعلومات المستخدم والمفاتيح العامة. يمكن استرداد مستند الاستكشاف لخدمة OpenID Connect من Google من:
https://accounts.google.com/.well-known/openid-configuration
لاستخدام خدمات OpenID Connect من Google، عليك ترميز معرّف الموارد المنتظم لمستند Discovery-document
(https://accounts.google.com/.well-known/openid-configuration) في تطبيقك.
يجلب تطبيقك المستند، ويطبّق قواعد التخزين المؤقت في الرد، ثم يسترد معرّفات الموارد المنتظمة (URI) الخاصة بنقاط النهاية منه حسب الحاجة. على سبيل المثال، لمصادقة مستخدم، سيسترد الرمز قيمة البيانات الوصفية authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth في المثال أدناه) كمعرّف موارد منتظم أساسي لطلبات المصادقة التي يتم إرسالها إلى Google.
في ما يلي مثال على هذا المستند، وأسماء الحقول هي تلك المحدّدة في OpenID Connect Discovery 1.0 (يُرجى الرجوع إلى هذا المستند لمعرفة معانيها). القيم توضيحية بحتة وقد تتغيّر، على الرغم من أنّها منسوخة من نسخة حديثة من مستند Google Discovery الفعلي:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
يمكنك تجنُّب جولة HTTP من خلال تخزين القيم مؤقتًا من مستند Discovery. يتم استخدام عناوين التخزين المؤقت العادية لبروتوكول HTTP ويجب الالتزام بها.
مكتبات العملاء
تسهّل مكتبات البرامج التالية تنفيذ بروتوكول OAuth 2.0 من خلال الدمج مع أُطر العمل الشائعة:
الامتثال لمعيار OpenID Connect
يتوافق نظام المصادقة OAuth 2.0 من Google مع الميزات المطلوبة في مواصفات OpenID Connect Core. يجب أن يتوافق أي برنامج مصمّم للعمل مع OpenID Connect مع هذه الخدمة (باستثناء كائن طلب OpenID).