يمكن استخدام واجهات برمجة تطبيقات OAuth 2.0 من Google للمصادقة والتفويض. يوضّح هذا المستند عملية تنفيذ OAuth 2.0 للمصادقة، وهي تتوافق مع مواصفات اتصال OpenID، كما أنّها معتمَدة من OpenID. تنطبق أيضًا المستندات المتوفّرة في استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs على هذه الخدمة. إذا أردت استكشاف هذا البروتوكول بشكل تفاعلي، ننصحك باستخدام مساحة بروتوكول OAuth 2.0 في Google. للحصول على المساعدة على Stack Overflow، ضَع العلامة google-oauth على أسئلتك.
إعداد OAuth 2.0
قبل أن يتمكّن تطبيقك من استخدام نظام المصادقة OAuth 2.0 من Google لتسجيل دخول المستخدمين، عليك إعداد مشروع في للحصول على بيانات اعتماد OAuth 2.0، وتحديد معرّف الموارد المنتظم (URI) لإعادة التوجيه، وتخصيص معلومات العلامة التجارية التي تظهر للمستخدمين على شاشة موافقة المستخدم (اختياري). يمكنك أيضًا استخدام لإنشاء حساب خدمة وتفعيل الفوترة وإعداد الفلترة وتنفيذ مهام أخرى. لمزيد من التفاصيل، يُرجى الاطّلاع على المساعدة.
الحصول على بيانات اعتماد OAuth 2.0
تحتاج إلى بيانات اعتماد OAuth 2.0، بما في ذلك معرّف العميل وسر العميل، لمصادقة المستخدمين والوصول إلى واجهات Google APIs.
لعرض معرف العميل وسر العميل لبيانات اعتماد OAuth 2.0 معينة ، انقر على النص التالي: حدد بيانات الاعتماد . في النافذة التي تفتح ، اختر مشروعك وبيانات الاعتماد التي تريدها ، ثم انقر فوق عرض .
أو اعرض معرف العميل وسر العميل من صفحة بيانات الاعتماد في API Console :
- Go to the Credentials page.
- انقر فوق اسم بيانات الاعتماد الخاصة بك أو رمز القلم الرصاص ( create ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.
ضبط معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه
يحدّد معرّف الموارد المنتظم لإعادة التوجيه الذي ضبطته في المكان الذي ترسل إليه Google الردود على طلبات المصادقة.
لإنشاء أو عرض أو تحرير عناوين URI المعاد توجيهها لبيانات اعتماد OAuth 2.0 ، قم بما يلي:
- Go to the Credentials page.
- في قسم معرفات عميل OAuth 2.0 من الصفحة ، انقر على بيانات الاعتماد.
- عرض أو تحرير عناوين URI المعاد توجيهها.
إذا لم يكن هناك قسم معرفات عميل OAuth 2.0 في صفحة بيانات الاعتماد ، فلن يحتوي مشروعك على بيانات اعتماد OAuth. لإنشاء واحدة ، انقر فوق إنشاء بيانات الاعتماد .
تخصيص شاشة موافقة المستخدم
بالنسبة إلى المستخدمين، تتضمّن تجربة المصادقة باستخدام بروتوكول OAuth 2.0 شاشة موافقة توضّح المعلومات التي يشاركها المستخدم والشروط السارية. على سبيل المثال، عندما يسجّل المستخدم الدخول، قد يُطلب منه منح تطبيقك إذن الوصول إلى عنوان بريده الإلكتروني ومعلومات الحساب الأساسية. يمكنك طلب الوصول إلى هذه المعلومات باستخدام المَعلمة
scope التي يدرجها تطبيقك في
طلب المصادقة. يمكنك أيضًا استخدام النطاقات لطلب الوصول إلى واجهات برمجة تطبيقات Google الأخرى.
تعرض شاشة موافقة المستخدم أيضًا معلومات العلامة التجارية، مثل اسم منتجك وشعاره وعنوان URL للصفحة الرئيسية. يمكنك التحكّم في معلومات العلامة التجارية في .
لتمكين شاشة الموافقة على مشروعك:
- افتح Consent Screen page في Google API Console .
- If prompted, select a project, or create a new one.
- املأ النموذج وانقر على حفظ .
يوضّح مربّع الموافقة التالي ما سيظهر للمستخدم عند توفّر مجموعة من نطاقات OAuth 2.0 وGoogle Drive في الطلب. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة بروتوكول OAuth 2.0 من Google، لذلك لا يتضمّن معلومات العلامة التجارية التي سيتم ضبطها في .)
الوصول إلى الخدمة
توفّر Google والجهات الخارجية مكتبات يمكنك استخدامها للتعامل مع العديد من تفاصيل التنفيذ المتعلقة بمصادقة المستخدمين والوصول إلى واجهات Google API. وتشمل الأمثلة خدمات Google Identity ومكتبات برامج Google المتاحة لمجموعة متنوعة من الأنظمة الأساسية.
إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في بقية هذا المستند، والتي توضّح مسارات طلبات HTTP التي تستند إليها المكتبات المتاحة.
مصادقة المستخدم
تتضمّن مصادقة المستخدم الحصول على رمز مميّز صالح وتعزيزه. رموز التعريف هي ميزة موحّدة في اتصال OpenID مصمّمة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.
إنّ أكثر الطرق شيوعًا لمصادقة المستخدم والحصول على رمز مميّز للمعرّف تُعرف باسم مسار "الخادم" ومسار "الوصول الضمني". يتيح مسار الخادم لخادم الخلفية الخاص بأحد التطبيقات إثبات هوية الشخص الذي يستخدم متصفّحًا أو جهازًا جوّالاً. يتم استخدام عملية الربط الضمني عندما يحتاج تطبيق من جهة العميل (عادةً تطبيق JavaScript يعمل في المتصفح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من استخدام خادم الخلفية.
يوضّح هذا المستند كيفية تنفيذ عملية المصادقة من جهة الخادم. يكون التدفق الضمني أكثر تعقيدًا بكثير بسبب المخاطر الأمنية المرتبطة بمعالجة الرموز المميزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ تدفق ضمني، ننصحك بشدة باستخدام خدمات Google لإثبات الهوية.
مسار الخادم
تأكَّد من إعداد تطبيقك في ليتمكّن من استخدام هذه البروتوكولات والتأكّد من هوية المستخدمين. عندما يحاول مستخدم تسجيل الدخول باستخدام 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
تتمثل الخطوة التالية في إنشاء طلب HTTPS GET يتضمّن مَعلمات معرّف الموارد المنتظم المناسبة.
يُرجى ملاحظة استخدام HTTPS بدلاً من HTTP في جميع خطوات هذه العملية، إذ يتم رفض اتصالات HTTP. يجب استرداد عنوان URI الأساسي من مستند Discovery
باستخدام قيمة البيانات الوصفية authorization_endpoint. تستند المناقشة التالية إلى أنّ معرّف الموارد المنتظم الأساسي هو https://accounts.google.com/o/oauth2/v2/auth.
بالنسبة إلى الطلب الأساسي، حدِّد المَعلمات التالية:
client_id، الذي تحصل عليه من .response_type، والذي يجب أن يكونcodeفي طلب أساسي لمسار رمز التفويض. (مزيد من المعلومات علىresponse_type)scope، والتي يجب أن تكونopenid emailفي الطلب الأساسي. (مزيد من المعلومات علىscope)- يجب أن يكون
redirect_uriنقطة نهاية HTTP على الخادم ستتلقّى الاستجابة من Google. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المصرّح بها لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي تم إعداده في 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 |
معرّف العميل الذي تحصل عليه من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
client_secret |
سر العميل الذي تحصل عليه من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
redirect_uri |
معرّف موارد منتظم (URI) معتمَد لإعادة التوجيه خاص بـ client_id المحدّد في
، كما هو موضّح في
ضبط معرّف موارد منتظم (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 APIs الأخرى
من مزايا استخدام OAuth 2.0 للمصادقة أنّ تطبيقك يمكنه الحصول على إذن باستخدام واجهات Google APIs الأخرى نيابةً عن المستخدم (مثل YouTube أو Google Drive أو "تقويم Google" أو "جهات اتصال Google") في الوقت نفسه الذي تتم فيه مصادقة المستخدم. لإجراء ذلك، أدرِج النطاقات الأخرى التي تحتاج إليها في طلب المصادقة الذي ترسله إلى Google. على سبيل المثال، لإضافة الفئة العمرية للمستخدم إلى طلب المصادقة، مرِّر مَعلمة نطاق بقيمة openid email https://www.googleapis.com/auth/profile.agerange.read. تتم مطالبة المستخدم بشكل مناسب على شاشة الموافقة. سيسمح رمز الدخول الذي تتلقّاه من Google لتطبيقك بالوصول إلى جميع واجهات برمجة التطبيقات ذات الصلة بنطاقات الوصول التي طلبتها وتم منحك إذن الوصول إليها.
رموز إعادة التحميل
في طلب الوصول إلى واجهة برمجة التطبيقات، يمكنك طلب عرض رمز مميز لإعادة التحميل أثناء عملية
code التبادل. يوفّر رمز التحديث لتطبيقك إمكانية الوصول المستمر إلى واجهات Google API عندما لا يكون المستخدم متواجدًا في تطبيقك. لطلب رمز مميّز لإعادة التحميل، أضِف المَعلمة access_type إلى offline في طلب المصادقة.
الاعتبارات:
- احرِص على تخزين رمز التحديث بشكل آمن ودائم، لأنّه لا يمكنك الحصول على رمز تحديث إلا في المرة الأولى التي تنفّذ فيها عملية تبادل الرموز.
- هناك حدود لعدد رموز التحديث التي يتم إصدارها: حد واحد لكل مجموعة من العميل/المستخدم، وحد آخر لكل مستخدم على مستوى جميع العملاء. إذا كان تطبيقك يطلب عددًا كبيرًا جدًا من رموز الدخول المميزة، قد يواجه هذه الحدود، وفي هذه الحالة، تتوقف رموز الدخول المميزة الأقدم عن العمل.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعادة تحميل رمز الدخول (الوصول بلا إنترنت).
طلب الموافقة مجددًا
يمكنك أن تطلب من المستخدم إعادة منح الإذن لتطبيقك من خلال ضبط المَعلمة
prompt على consent في
طلب المصادقة. عند تضمين prompt=consent، يتم عرض شاشة الموافقة في كل مرة يطلب فيها تطبيقك تفويض نطاقات الوصول، حتى إذا تم منح جميع النطاقات لمشروعك على Google APIs سابقًا. لهذا السبب، لا تُدرِج prompt=consent إلا عند الضرورة.
لمزيد من المعلومات عن المَعلمة prompt، يُرجى الاطّلاع على prompt
في جدول مَعلمات معرّف الموارد المنتظم للمصادقة.
مَعلمات معرّف الموارد المنتظم (URI) للمصادقة
يقدّم الجدول التالي أوصافًا أكثر اكتمالاً للمعلمات التي تقبلها واجهة برمجة التطبيقات الخاصة بالمصادقة في OAuth 2.0 من Google.
| المَعلمة | مطلوب | الوصف |
|---|---|---|
client_id |
(مطلوب) | سلسلة معرّف العميل التي تحصل عليها من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0 |
nonce |
(مطلوب) | قيمة عشوائية ينشئها تطبيقك وتتيح الحماية من إعادة الإرسال. |
response_type |
(مطلوب) | إذا كانت القيمة code، يتم إطلاق
مسار رمز التفويض الأساسي،
ما يتطلّب POST إلى نقطة نهاية الرمز المميز للحصول على الرموز المميزة. إذا كانت القيمة token id_token أو id_token token، يتم تشغيل التدفق الضمني، ما يتطلب استخدام JavaScript في معرّف الموارد المنتظم (URI) لإعادة التوجيه من أجل استرداد الرموز المميزة من معرّف الموارد المنتظم (URI) #fragment. |
redirect_uri |
(مطلوب) | تحدّد هذه السمة الوجهة التي يتم إرسال الردّ إليها. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم إعادة التوجيه المسموح بها التي تحدّدها في (بما في ذلك نظام 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 |
(اختياري) | قائمة مفصولة بمسافات تتضمّن قيم السلسلة التي تحدّد ما إذا كان خادم التفويض يطلب من المستخدم إعادة المصادقة والموافقة. القيم المحتمَلة هي:
إذا لم يتم تحديد أي قيمة ولم يسبق للمستخدم منح إذن الوصول، سيتم عرض شاشة موافقة للمستخدم. |
التحقّق من صحة رمز مميّز لتعريف الهوية
عليك التحقّق من صحة جميع رموز التعريف المميزة على خادمك ما لم تكن على علم بأنّها واردة مباشرةً من Google. على سبيل المثال، يجب أن يتأكّد الخادم من صحة أي رموز تعريف يتلقّاها من تطبيقات العميل.
في ما يلي بعض الحالات الشائعة التي قد ترسل فيها رموز التعريف إلى الخادم:
- إرسال رموز تعريف مع الطلبات التي تتطلّب المصادقة تخبرك رموز التعريف بالمستخدم المحدّد الذي يرسل الطلب والعميل الذي تم منح رمز التعريف له.
رموز التعريف حسّاسة ويمكن إساءة استخدامها إذا تم اعتراضها. يجب التأكّد من معالجة هذه الرموز المميزة بشكل آمن من خلال نقلها عبر HTTPS فقط وباستخدام بيانات POST فقط أو ضمن عناوين طلبات HTTP. إذا كنت تخزّن رموز التعريف على خادمك، عليك أيضًا تخزينها بشكل آمن.
من الميزات التي تجعل رموز التعريف مفيدة هي إمكانية نقلها بين مختلف مكوّنات تطبيقك، إذ يمكن لهذه المكوّنات استخدام رمز التعريف كآلية مصادقة بسيطة لمصادقة التطبيق والمستخدم. ولكن قبل أن تتمكّن من استخدام المعلومات الواردة في الرمز المميّز لبطاقة التعريف أو الاعتماد عليها كإقرار بأنّ المستخدم قد أجرى مصادقة، يجب التحقّق من صحتها.
تتطلّب عملية التحقّق من صحة رمز التعريف عدة خطوات:
- تأكَّد من أنّ رمز التعريف المميّز تم توقيعه بشكل صحيح من قِبل جهة الإصدار. يتم توقيع الرموز المميزة الصادرة عن 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) للمفاتيح من مستند Discovery
باستخدام قيمة البيانات الوصفية jwks_uri. قد يتم تقييد عدد الطلبات التي يتم إرسالها إلى نقطة نهاية تصحيح الأخطاء أو قد تخضع لأخطاء متقطّعة.
بما أنّ Google لا تغيّر مفاتيحها العامة إلا نادرًا، يمكنك تخزينها مؤقتًا باستخدام توجيهات التخزين المؤقت الخاصة باستجابة HTTP، وفي معظم الحالات، يمكنك إجراء عملية التحقّق المحلية بكفاءة أكبر بكثير من استخدام نقطة النهاية tokeninfo. تتطلّب عملية التحقّق هذه استرداد الشهادات وتحليلها، وإجراء عمليات التشفير المناسبة للتحقّق من التوقيع. لحسن الحظ، تتوفّر مكتبات تم تصحيح أخطائها بشكل جيد في مجموعة متنوعة من اللغات لإنجاز هذه المهمة (راجِع jwt.io).
الحصول على معلومات الملف الشخصي للمستخدم
للحصول على معلومات إضافية عن الملف الشخصي للمستخدم، يمكنك استخدام رمز الدخول (الذي يتلقّاه تطبيقك أثناء مسار المصادقة) ومعيار OpenID Connect:
للامتثال لمعيار 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. يمكن للمستخدمين أو مؤسساتهم اختيار تقديم أو حجب حقول معيّنة، لذا قد لا تتلقّى معلومات عن كل حقل من نطاقات الوصول المصرّح بها.
مستند Discovery
يتطلّب بروتوكول OpenID Connect استخدام نقاط نهاية متعدّدة لمصادقة المستخدمين وطلب الموارد، بما في ذلك الرموز المميزة ومعلومات المستخدمين والمفاتيح العامة.
لتسهيل عمليات التنفيذ وزيادة المرونة، يتيح OpenID Connect استخدام "مستند اكتشاف"، وهو مستند JSON يمكن العثور عليه في موقع معروف ويتضمّن أزواج قيم أو مفاتيح تقدّم تفاصيل حول إعدادات موفّر OpenID Connect، بما في ذلك معرّفات الموارد المنتظمة لنقاط نهاية التفويض والرموز المميزة والإبطال ومعلومات المستخدم والمفاتيح العامة. يمكن استرداد مستند Discovery لخدمة 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).