يمكن استخدام واجهات برمجة تطبيقات OAuth 2.0 من Google لكل من المصادقة والترخيص. ويوضّح هذا المستند تنفيذ OAuth 2.0 للمصادقة، والذي يتوافق مع مواصفات OpenID Connect، وهو معتمد من OpenID. تسري المستندات الواردة في استخدام OAuth 2.0 للوصول إلى Google APIs أيضًا على هذه الخدمة. إذا أردت استكشاف هذا البروتوكول بشكل تفاعلي، ننصحك بمساحة المرح Google OAuth 2.0. للحصول على مساعدة بشأن Stack Overflow، ضَع علامة "google-oauth" على أسئلتك.
إعداد OAuth 2.0
قبل أن يتمكّن تطبيقك من استخدام نظام مصادقة OAuth 2.0 من Google لتسجيل دخول المستخدم، عليك إعداد مشروع في Google API Console للحصول على بيانات اعتماد OAuth 2.0، وضبط معرّف موارد منتظم (URI) لإعادة التوجيه، وتخصيص (اختياريًا) معلومات العلامة التجارية التي تظهر للمستخدمين على شاشة موافقة المستخدم. يمكنك أيضًا استخدام API Console لإنشاء حساب خدمة وتفعيل الفوترة وإعداد الفلترة وتنفيذ مهام أخرى. لمزيد من التفاصيل، يمكنك الاطّلاع على مساعدةGoogle API Console.
الحصول على بيانات اعتماد OAuth 2.0
تحتاج إلى بيانات اعتماد OAuth 2.0، بما في ذلك معرِّف العميل وسر العميل، لمصادقة المستخدمين والوصول إلى واجهات برمجة تطبيقات Google.
لعرض معرف العميل وسر العميل لبيانات اعتماد OAuth 2.0 معينة ، انقر على النص التالي: حدد بيانات الاعتماد . في النافذة التي تفتح ، اختر مشروعك وبيانات الاعتماد التي تريدها ، ثم انقر فوق عرض .
أو اعرض معرف العميل وسر العميل من صفحة بيانات الاعتماد في API Console :
- Go to the Credentials page.
- انقر فوق اسم بيانات الاعتماد الخاصة بك أو رمز القلم الرصاص ( create ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.
ضبط عنوان URL لإعادة التوجيه
يحدّد معرّف الموارد المنتظم (URI) لإعادة التوجيه الذي تضبطه في API Console المكان الذي يرسل فيه محرّك بحث Google الردود على طلبات المصادقة التي تقدّمها.
لإنشاء أو عرض أو تحرير عناوين URI المعاد توجيهها لبيانات اعتماد OAuth 2.0 ، قم بما يلي:
- Go to the Credentials page.
- في قسم معرفات عميل OAuth 2.0 من الصفحة ، انقر على بيانات الاعتماد.
- عرض أو تحرير عناوين URI المعاد توجيهها.
إذا لم يكن هناك قسم معرفات عميل OAuth 2.0 في صفحة بيانات الاعتماد ، فلن يحتوي مشروعك على بيانات اعتماد OAuth. لإنشاء واحدة ، انقر فوق إنشاء بيانات الاعتماد .
تخصيص شاشة موافقة المستخدم
بالنسبة إلى المستخدمين، تتضمن تجربة مصادقة OAuth 2.0 شاشة موافقة تصف المعلومات التي يصدرها المستخدم والأحكام السارية. على سبيل المثال، عندما يسجّل المستخدم الدخول، قد يُطلب منه منح تطبيقك إمكانية الوصول إلى عنوان بريده الإلكتروني ومعلومات حسابه الأساسية. يمكنك طلب الوصول إلى هذه المعلومات باستخدام المَعلمة
scope
التي يتضمّنها تطبيقك في
طلب المصادقة. يمكنك أيضًا استخدام النطاقات لطلب الوصول إلى
واجهات Google APIs الأخرى.
تعرض شاشة موافقة المستخدم أيضًا معلومات العلامة التجارية، مثل اسم المنتج والشعار وعنوان URL للصفحة الرئيسية. يمكنك التحكّم في معلومات العلامة التجارية في API Console.
لتمكين شاشة الموافقة على مشروعك:
- افتح 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، لذلك لا يتضمّن معلومات العلامة التجارية التي سيتم ضبطها في API Console.)
![لقطة شاشة لصفحة الموافقة](https://developers.google.cn/static/identity/protocols/oauth2/images/examples/scope-authorization.png?authuser=9&hl=ar)
الوصول إلى الخدمة
توفّر Google والجهات الخارجية مكتبات يمكنك استخدامها للاعتناء بالعديد من تفاصيل التنفيذ المتعلقة بمصادقة المستخدمين والحصول على إمكانية الوصول إلى Google APIs. وتشمل الأمثلة خدمات هوية Google ومكتبات عملاء Google المتاحة لمجموعة متنوعة من الأنظمة الأساسية.
إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في باقي هذا المستند التي تصف تدفق طلبات HTTP التي تقع ضمن المكتبات المتاحة.
مصادقة المستخدم
تتضمن مصادقة المستخدم الحصول على رمز مميز للمعرف والتحقق من صحته. الرموز المميّزة لمعرّف هي ميزة موحّدة في OpenID Connect وهي مصممة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.
يُطلق على الأساليب الأكثر استخدامًا لمصادقة المستخدم والحصول على رمز مميّز لرقم التعريف اسم المسار "الخادم" والمسار "الضمني". يسمح مسار الخادم لخادم الخلفية لأحد التطبيقات بإثبات هوية الشخص باستخدام متصفح أو جهاز جوّال. ويتم استخدام التدفّق الضمني عندما يحتاج تطبيق من جهة العميل (عادةً تطبيق JavaScript يتم تشغيله في المتصفّح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من الوصول من خلال الخادم الخلفي.
يصف هذا المستند كيفية تنفيذ تدفق الخادم لمصادقة المستخدم. ويعتبر التدفّق الضمني أكثر تعقيدًا بسبب المخاطر الأمنية التي تتعلّق بمعالجة الرموز المميّزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ مسار ضمني، ننصحك بشدة باستخدام خدمات هوية Google.
تدفق الخادم
تأكَّد من إعداد تطبيقك في API Console للسماح له باستخدام هذه البروتوكولات ومصادقة المستخدمين. عندما يحاول المستخدم تسجيل الدخول باستخدام حساب Google، يجب إجراء ما يلي:
- إنشاء رمز مميّز للحالة ضد التزييف
- إرسال طلب مصادقة إلى Google
- تأكيد الرمز المميّز لحالة مكافحة التزييف
- Exchange
code
لرمز الدخول والرمز المميز لرقم التعريف - الحصول على معلومات المستخدم من الرمز المميّز لرقم التعريف
- مصادقة المستخدم
1- إنشاء رمز مميّز لحالة مكافحة التزييف
يجب حماية أمان المستخدمين من خلال منع هجمات تزييف الطلبات. تتمثّل الخطوة الأولى في إنشاء رمز مميّز فريد للجلسة يحتفظ بحالة المستخدم بين تطبيقك وبرنامج المستخدم. يمكنك لاحقًا مطابقة هذا الرمز المميز الفريد للجلسة مع استجابة المصادقة التي تعرضها خدمة تسجيل الدخول عبر OAuth من Google للتحقق من أن المستخدم هو الذي يُجري الطلب وليس مهاجمًا ضارًا. ويُشار غالبًا إلى هذه الرموز المميّزة على أنّها رموز مميّزة لتزوير الطلبات من مواقع إلكترونية مختلفة (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
باستخدام معلمات URI المناسبة.
ضَع في اعتبارك استخدام بروتوكول HTTPS بدلاً من HTTP في جميع خطوات هذه العملية، لأنّه يتم رفض اتصالات HTTP. يجب استرداد معرّف الموارد المنتظم (URI) الأساسي من مستند "اقتراحات"
باستخدام قيمة البيانات الوصفية authorization_endpoint
. تفترض المناقشة التالية أن معرّف الموارد المنتظم (URI) الأساسي هو https://accounts.google.com/o/oauth2/v2/auth
.
بالنسبة إلى الطلب الأساسي، حدِّد المَعلمات التالية:
client_id
، التي تحصل عليها من API Console Credentials page .response_type
، والذي يجب أن يكونcode
في طلب مسار رمز التفويض الأساسي. (يمكنك الاطّلاع على مزيد من المعلومات علىresponse_type
.)scope
، والذي يجب أن يكونopenid email
في الطلب الأساسي. (اطّلِع على مزيد من المعلومات علىscope
.)- يجب أن يكون
redirect_uri
نقطة نهاية HTTP على خادمك الذي سيتلقّى استجابة من Google. يجب أن تتطابق القيمة تمامًا مع أحد معرِّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبرنامج OAuth 2.0، والذي ضبطته في API Console Credentials page. وإذا كانت هذه القيمة لا تتطابق مع معرّف موارد منتظم (URI) مُعتمَد، سيتعذّر تنفيذ الطلب وسيظهر خطأredirect_uri_mismatch
. - يجب أن تتضمن
state
قيمة الرمز المميز الفريد للجلسة المتعلق بمكافحة التزييف، بالإضافة إلى أي معلومات أخرى لازمة لاستعادة السياق عند عودة المستخدم إلى تطبيقك، مثل عنوان URL للبدء. (اطّلِع على مزيد من المعلومات علىstate
.) nonce
هي قيمة عشوائية ينشئها تطبيقك وتوفّر الحماية من إعادة التشغيل عند توفّرها.- يمكن أن يكون
login_hint
عنوان البريد الإلكتروني للمستخدم أو سلسلةsub
، التي تعادل رقم تعريف Google للمستخدم. إذا لم تدخِلlogin_hint
وكان المستخدم مسجّلاً الدخول حاليًا، ستتضمّن شاشة الموافقة طلبًا للموافقة على إصدار عنوان البريد الإلكتروني للمستخدم في تطبيقك. (يمكنك الاطّلاع على مزيد من المعلومات علىlogin_hint
.) - يمكنك استخدام المَعلمة
hd
لتحسين مسار "ربط OpenID" لمستخدمي نطاق معيّن مرتبط بمؤسسة على 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
إلى نقطة نهاية الرمز المميّز، التي يجب استردادها من مستند "اقتراحات" باستخدام قيمة البيانات الوصفية token_endpoint
. تفترض المناقشة التالية أن نقطة النهاية هي https://oauth2.googleapis.com/token
. يجب أن يتضمّن الطلب المَعلمات التالية في نص POST
:
الحقول | |
---|---|
code |
رمز التفويض الذي يتم عرضه من الطلب الأولي. |
client_id |
معرِّف العميل الذي تحصل عليه من API Console Credentials page، كما هو موضَّح في الحصول على بيانات اعتماد OAuth 2.0. |
client_secret |
سر العميل الذي تحصل عليه من API Console Credentials page، كما هو موضَّح في الحصول على بيانات اعتماد OAuth 2.0. |
redirect_uri |
معرّف موارد منتظم (URI) لإعادة التوجيه مسموح به للسمة client_id المحدّدة في
API Console
Credentials 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 |
expires_in |
المدة المتبقية لرمز الدخول بالثواني. |
id_token |
JWT يحتوي على معلومات هوية المستخدم الموقّعة رقميًا من قِبل Google. |
scope |
نطاقات الوصول التي تم منحها في access_token ، ويتم التعبير عنها في شكل قائمة من
السلاسل الحساسة لحالة الأحرف والمحددة بمسافات. |
token_type |
تحدد نوع الرمز المميّز الذي يتم عرضه. في الوقت الحالي، تكون القيمة في هذا الحقل دائمًا
Bearer .
|
refresh_token |
(اختياري)
ولا يتوفّر هذا الحقل إلا في حال ضبط المَعلمة
|
5. الحصول على معلومات المستخدم من الرمز المميز للمعرّف
الرمز المميّز للمعرّف هو رمز JWT (المعروف اختصارًا باسم JSON Web Token)، وهو كائن 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 على الحقول التالية (المعروفة باسم المطالبات):
Claim | تم الإدخال | الوصف |
---|---|---|
aud |
دائمًا | تمثّل هذه السمة الجمهور الذي تم تخصيص هذا الرمز المميّز له. ويجب أن يكون أحد معرّفات عملاء OAuth 2.0 لتطبيقك. |
exp |
دائمًا | وقت انتهاء الصلاحية الذي يجب ألا يتم قبول الرمز المميّز للمستند بعده. يمثّل ذلك التاريخ بتوقيت يونكس (عدد صحيح بالثواني). |
iat |
دائمًا | الوقت الذي تم فيه إصدار الرمز المميّز للمعرّف يتم التمثيل بتوقيت يونكس (عدد صحيح بالثواني). |
iss |
دائمًا | معرّف جهة الإصدار لجهة إصدار الردّ ويجب استخدام https://accounts.google.com أو accounts.google.com في الرموز المميّزة لمعرّف Google. |
sub |
دائمًا | معرّف للمستخدم يكون فريدًا بين جميع حسابات Google ولا تتم إعادة استخدامه على الإطلاق. يمكن أن يكون لحساب Google عدة عناوين بريد إلكتروني في أوقات مختلفة، ولكن لا تتغير قيمة sub مطلقًا. استخدِم sub في تطبيقك
كمفتاح المعرّف الفريد للمستخدم. الحد الأقصى للطول هو 255 حرفًا حساسًا لحالة الأحرف. |
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، أو على الأقل يمكنك ملء العديد من الحقول التي تطلبها في نموذج التسجيل. بالإضافة إلى المعلومات الواردة في الرمز المميّز لرقم التعريف، يمكنك الحصول على معلومات إضافية في الملف الشخصي للمستخدم في نقاط النهاية الخاصة بالملف الشخصي للمستخدم.
مواضيع متقدمة
تشرح الأقسام التالية واجهة برمجة التطبيقات OAuth 2.0 الخاصة بـ Google بمزيد من التفصيل. هذه المعلومات مخصّصة للمطوّرين الذين لديهم متطلبات متقدمة متعلقة بالمصادقة والتفويض.
الوصول إلى 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 APIs بينما لا يكون المستخدم متاحًا في تطبيقك. لطلب الرمز المميّز لإعادة التحميل، أضِف ضبط المَعلمة
access_type
على offline
في طلب المصادقة.
نقاط يجب أخذها في الاعتبار:
- احرِص على تخزين الرمز المميّز لإعادة التحميل بأمان ودائم، لأنّه لا يمكنك الحصول على الرمز المميّز لإعادة التحميل إلا في المرة الأولى التي تُجري فيها عملية تبادل الرموز.
- هناك حدود لعدد الرموز المميّزة لإعادة التحميل التي يتم إصدارها: حد أقصى لكل مجموعة عميل/مستخدم وحد آخر لكل مستخدم في جميع البرامج. إذا طلب تطبيقك عددًا كبيرًا جدًا من الرموز المميّزة لإعادة التحميل، قد يتخطّى هذه الحدود، وفي تلك الحالة ستتوقف الرموز المميّزة لإعادة التحميل القديمة عن العمل.
لمزيد من المعلومات، يمكنك الاطّلاع على إعادة تحميل رمز الدخول (الوصول بلا إنترنت).
طلب إعادة الموافقة
يمكنك أن تطلب من المستخدم إعادة تفويض تطبيقك من خلال ضبط
معلَمة prompt
على consent
في
طلب المصادقة. عند تضمين prompt=consent
، يتم عرض شاشة الموافقة في كل مرة يطلب فيها تطبيقك إذنًا بنطاقات الوصول، حتى إذا سبق أن تم منح جميع النطاقات لمشروعك على Google APIs. لهذا السبب، لا تُدرِج prompt=consent
إلا عند الضرورة.
لمزيد من المعلومات عن المَعلمة prompt
، اطّلِع على prompt
في جدول مَعلمات معرّف الموارد المنتظم (URI) للمصادقة.
معلمات معرّف الموارد المنتظم (URI) للمصادقة
يقدّم الجدول التالي أوصافًا أكثر اكتمالاً للمعلَمات التي تقبلها واجهة برمجة التطبيقات لمصادقة OAuth 2.0 من Google.
المَعلمة | مطلوبة | الوصف |
---|---|---|
client_id |
(مطلوب) | سلسلة معرِّف العميل التي تحصل عليها من Credentials page API Console، كما هو موضَّح في الحصول على بيانات اعتماد OAuth 2.0. |
nonce |
(مطلوب) | قيمة عشوائية ينشئها تطبيقك وتفعّل الحماية من إعادة التشغيل. |
response_type |
(مطلوب) | إذا كانت القيمة code ، يتم تشغيل
مسار رمز التفويض الأساسي،
يتطلب ذلك استخدام POST في نقطة نهاية الرمز المميّز للحصول على الرموز المميّزة. إذا كانت القيمة
token id_token أو id_token token ، يتم تشغيل
تدفق ضمني
يتطلّب استخدام JavaScript في معرّف الموارد المنتظم (URI) لإعادة التوجيه لاسترداد الرموز المميّزة من
معرّف #fragment الخاص بمعرّف الموارد المنتظم (URI). |
redirect_uri |
(مطلوب) | تحدد أين تم إرسال الرد. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم إعادة التوجيه المسموح بها التي حدّدتها في API Console Credentials page (بما في ذلك مخطط HTTP أو HTTPS، والحالة، واللاحقة '/'، إن توفّرت). |
scope |
(مطلوب) | يجب أن تبدأ مَعلمة النطاق بالقيمة في حال توفّر قيمة نطاق في حال توفّر قيمة نطاق بالإضافة إلى هذه النطاقات الخاصة بـ OpenID، يمكن أن تتضمن وسيطة النطاق أيضًا قيمًا أخرى للنطاق. يجب أن تكون جميع قيم النطاق مفصولة بمسافات. على سبيل المثال، إذا أردت
الوصول لكل ملف إلى حساب مستخدم على Google Drive، قد تكون مَعلمة النطاق هي
للحصول على معلومات عن النطاقات المتاحة، يُرجى الاطّلاع على نطاقات OAuth 2.0 لواجهات Google APIs أو مستندات Google API التي تريد استخدامها. |
state |
(اختياري، ولكن يُنصح به بشدة) | سلسلة مبهمة يتم عرضها ذهابًا وإيابًا في البروتوكول، أي أنّه يتم عرضها كمَعلمة معرّف موارد منتظم (URI) في المسار الأساسي، وفي معرّف ويمكن أن تكون السمة |
access_type |
(سؤال اختياري) | القيمتان المسموح بإدراجهما هما offline وonline . تم توثيق التأثير في ميزة الوصول بلا إنترنت، وفي حال طلب رمز دخول، لن يتلقّى العميل الرمز المميّز لإعادة التحميل ما لم يتم تحديد قيمة offline . |
display |
(سؤال اختياري) | قيمة سلسلة ASCII لتحديد كيفية عرض خادم التفويض لصفحات واجهة المستخدم للمصادقة والمستخدم. يتم تحديد القيم التالية وقبولها من خلال خوادم Google، ولكن ليس لها أي تأثير على طريقة عملها: page وpopup وtouch وwap . |
hd |
(سؤال اختياري) | تبسيط عملية تسجيل الدخول للحسابات التي تمتلكها مؤسسة على Google Cloud من خلال
تضمين نطاق المؤسسة على Google Cloud (على سبيل المثال، mycollege.edu)،
يمكنك الإشارة إلى أنّه يجب تحسين واجهة مستخدم اختيار الحسابات للحسابات في ذلك
النطاق. لتحسين أداء حسابات المؤسسات في Google Cloud بشكل عام بدلاً من نطاق مؤسسة واحد فقط في Google Cloud، اضبط قيمة علامة النجمة ( لا تعتمد على عملية تحسين واجهة المستخدم هذه للتحكم في الأشخاص الذين يمكنهم الوصول إلى تطبيقك، إذ يمكن تعديل الطلبات من جهة العميل. احرص على validate من أنّ
الرمز المميّز للمعرّف الذي تم عرضه يتضمّن قيمة مطالبة |
include_granted_scopes |
(سؤال اختياري) | إذا تم توفير هذه المَعلمة مع القيمة true وتم منح طلب التفويض، سيشمل التفويض أي عمليات تفويض سابقة تم منحها لهذا المستخدم أو التطبيق للنطاقات الأخرى. يُرجى الاطّلاع على التفويض الإضافي.
تجدر الإشارة إلى أنه لا يمكنك إجراء تفويض متزايد مع تدفق التطبيقات المُثبتة. |
login_hint |
(سؤال اختياري) | وعندما يعرف تطبيقك المستخدم الذي يحاول المصادقة عليه، يمكنه تقديم هذه
المَعلمة كتلميح لخادم المصادقة. ويؤدي تمرير هذا التلميح إلى إيقاف محدِّد الحساب وإما ملء مربّع البريد الإلكتروني في نموذج تسجيل الدخول مسبقًا أو اختيار الجلسة المناسبة (في حال كان المستخدم يستخدم تسجيل الدخول المتعدّد)، والذي يمكن أن يساعدك في تجنّب المشاكل التي تحدث إذا كان التطبيق يسجّل الدخول إلى حساب المستخدم غير الصحيح.
ويمكن أن تكون القيمة إما عنوان بريد إلكتروني أو سلسلة sub ، أي ما يعادل معرّف المستخدم على Google. |
prompt |
(سؤال اختياري) | يشير ذلك المصطلح إلى قائمة قيم السلسلة المفصولة بمسافات والتي تحدِّد ما إذا كان خادم التفويض
يطلب من المستخدم إعادة المصادقة والموافقة. في ما يلي القيم المحتمَلة:
إذا لم يتم تحديد أي قيمة ولم يسبق للمستخدم السماح بالوصول، سيتم عرض شاشة طلب الموافقة للمستخدم. |
التحقّق من الرمز المميّز للمعرّف
يجب التحقّق من صحة جميع الرموز المميّزة الخاصة بمعرّفات الهوية على خادمك، إلا إذا كنت تعرف أنّها مصدرها Google مباشرةً. على سبيل المثال، يجب أن يتحقّق الخادم من صحة أي رموز مميزة للمعرِّف يتلقّاها من تطبيقات العميل.
في ما يلي بعض المواقف الشائعة التي يمكنك فيها إرسال الرموز المميّزة للمعرّف إلى خادمك:
- يتم إرسال الرموز المميّزة للمعرّف مع الطلبات التي تحتاج إلى مصادقة. تُطلعك الرموز المميّزة لرقم التعريف على المستخدم المحدّد الذي قدّم الطلب وعن العميل الذي تم منح الرمز المميّز للمعرّف له.
الرموز المميّزة لمستند التعريف حسّاسة ويمكن إساءة استخدامها في حال اعتراضها. يجب التأكّد من معالجة هذه الرموز المميّزة بشكل آمن من خلال نقلها فقط عبر HTTPS وعبر بيانات POST فقط أو ضمن عناوين الطلبات. في حال تخزين الرموز المميّزة لرقم التعريف على خادمك، يجب أيضًا تخزينها بشكلٍ آمن.
إنّ ما يجعل الرموز المميّزة للمعرّف مفيدة هي إمكانية تمريرها حول مكوّنات مختلفة من تطبيقك. يمكن أن تستخدم هذه المكوّنات الرمز المميّز للمعرّف كآلية مصادقة بسيطة لمصادقة التطبيق والمستخدم. ولكن قبل أن تتمكن من استخدام المعلومات في الرمز المميز لرقم التعريف أو الاعتماد عليها كتأكيد على أن المستخدم قد صادق على المعلومات، يجب التحقق منها.
يتطلّب التحقّق من الرمز المميّز للمعرّف عدة خطوات:
- تحقَّق من أنّ جهة الإصدار قد وقّعت بشكلٍ صحيح على الرمز المميّز للمعرّف. يتم توقيع الرموز المميّزة التي أصدرتها Google
باستخدام إحدى الشهادات المتوفّرة في معرّف الموارد المنتظم (URI) المحدَّد في قيمة البيانات الوصفية
jwks_uri
في مستند "اقتراحات". - تأكَّد من أنّ قيمة مطالبة
iss
في الرمز المميّز للمعرّف تساويhttps://accounts.google.com
أوaccounts.google.com
. - تأكَّد من أنّ قيمة مطالبة
aud
في الرمز المميّز لرقم التعريف تساوي قيمة معرِّف العميل لتطبيقك. - تحقّق من عدم انقضاء وقت انتهاء صلاحية الرمز المميّز للمعرّف (
exp
مطالبة). - إذا حدّدت قيمة مَعلمة hd في الطلب، تأكَّد من أنّ الرمز المميّز للمعرّف يتضمّن مطالبة
hd
تتطابق مع نطاق مقبول مرتبط بمؤسسة في Google Cloud.
تتضمّن الخطوات من 2 إلى 5 مقارنات بين السلاسل والتاريخ تكون واضحة تمامًا، لذلك لن نوضّحها بالتفصيل هنا.
الخطوة الأولى أكثر تعقيدًا، وتنطوي على التحقق من التوقيع المشفّر. لأغراض تصحيح الأخطاء، يمكنك استخدام نقطة نهاية tokeninfo
من Google للمقارنة مع المعالجة المحلية التي يتم تنفيذها على الخادم أو الجهاز. لنفترض أنّ قيمة الرمز المميّز لرقم التعريف هي
XYZ123
. بعد ذلك، يجب الإشارة إلى معرّف الموارد المنتظم (URI)
https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. إذا كان توقيع الرمز المميّز صالحًا، ستكون الاستجابة هي حمولة JWT في نموذج كائن JSON الذي تم فك ترميزه.
نقطة النهاية tokeninfo
مفيدة لتصحيح الأخطاء، ولكن لأغراض الإنتاج، يمكنك استرداد مفاتيح Google العامة من نقطة نهاية المفاتيح وإجراء عملية التحقق
محليًا. يجب استرداد معرِّف الموارد المنتظم (URI) للمفاتيح من مستند "اكتشاف"
باستخدام قيمة البيانات الوصفية jwks_uri
. قد يتم تقييد الطلبات إلى نقطة نهاية تصحيح الأخطاء أو قد تؤدي إلى حدوث أخطاء متقطّعة بأي طريقة أخرى.
وبما أنّ محرّك بحث Google لا يغيّر مفاتيحه العامة إلا نادرًا، يمكنك تخزينها مؤقتًا باستخدام توجيهات ذاكرة التخزين المؤقت لاستجابة HTTP، وفي الغالبية العظمى من الحالات، إجراء عمليات تحقّق محلية بكفاءة أكبر مقارنةً باستخدام نقطة النهاية tokeninfo
. وتتطلب عملية التحقق هذه استرداد الشهادات وتحليلها، وإجراء عمليات استدعاء التشفير المناسبة للتحقق من التوقيع. ولحسن الحظّ، تتوفّر مكتبات تم تصحيح الأخطاء فيها بعدة لغات (يمكنك الاطّلاع على jwt.io).
الحصول على معلومات الملف الشخصي للمستخدم
للحصول على معلومات إضافية في الملف الشخصي عن المستخدم، يمكنك استخدام رمز الدخول (الذي يتلقّاه تطبيقك أثناء مسار المصادقة) ومعيار OpenID Connect:
للالتزام بسياسة OpenID، يجب تضمين قيم نطاق
openid profile
في طلب المصادقة.إذا كنت تريد تضمين عنوان البريد الإلكتروني للمستخدم، يمكنك تحديد قيمة نطاق إضافية للسمة
email
. لتحديد كل منprofile
وemail
، يمكنك تضمين المَعلمة التالية في عنوان URI لطلب المصادقة:scope=openid%20profile%20email
- أضِف رمز الدخول إلى عنوان التفويض وقدِّم طلب HTTPS
GET
إلى نقطة نهاية معلومات المستخدم التي يجب استردادها من مستند "الاكتشاف" باستخدام قيمة البيانات الوصفيةuserinfo_endpoint
. يتضمّن الردّ على userinfo معلومات عن المستخدم، على النحو الموضّح فيOpenID Connect Standard Claims
وقيمة البيانات الوصفيةclaims_supported
في مستند "اقتراحات". قد يختار المستخدمون أو مؤسساتهم توفير حقول معيّنة أو حجزها، لذلك قد لا تحصل على معلومات عن كل حقل لنطاقات الوصول المصرَّح بها.
مستند "اقتراحات"
يتطلب بروتوكول OpenID Connect استخدام نقاط نهاية متعددة لمصادقة المستخدمين ولطلب الموارد، بما في ذلك الرموز المميّزة ومعلومات المستخدم والمفاتيح العامة.
لتبسيط عمليات التنفيذ وزيادة المرونة، يتيح OpenID Connect استخدام "مستند الاستكشاف"، وهو مستند JSON يتم العثور عليه في موقع معروف يحتوي على أزواج المفتاح/القيمة التي تقدّم تفاصيل حول ضبط موفِّر خدمة OpenID Connect، بما في ذلك معرِّفات الموارد المنتظمة (URI) للتفويض والرمز المميّز والإبطال ومعلومات المستخدم ونقاط نهاية المفاتيح العامة. يمكن استرداد مستند Discovery لخدمة OpenID Connect من Google من:
https://accounts.google.com/.well-known/openid-configuration
لاستخدام خدمات OpenID Connect من Google، يجب ترميز معرف الموارد المنتظم (URI) لمستند Discovery (https://accounts.google.com/.well-known/openid-configuration
) برمجيًا في تطبيقك.
يجلب تطبيقك المستند ويطبّق قواعد التخزين المؤقت في الاستجابة، ثم يسترد منه معرّفات الموارد المنتظمة (URI) لنقطة النهاية حسب الحاجة. على سبيل المثال، لمصادقة مستخدم، سيسترد الرمز قيمة البيانات الوصفية authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
في المثال أدناه) باعتبارها معرّف الموارد المنتظم (URI) الأساسي لطلبات المصادقة التي يتم إرسالها إلى 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" ] }
قد يمكنك تجنب إرسال واستقبال عنوان URL لبروتوكول HTTP من خلال التخزين المؤقت للقيم من مستند Discovery. يتم استخدام رؤوس تخزين HTTP القياسية ويجب الالتزام بها.
مكتبات العملاء
تبسّط مكتبات العملاء التالية عملية استخدام OAuth 2.0 من خلال الدمج مع أُطر العمل الرائجة:
الامتثال لـ OpenID Connect
يتوافق نظام مصادقة OAuth 2.0 من Google مع الميزات المطلوبة لمواصفات OpenID Connect Core. يجب أن يعمل أي برنامج تم تصميمه للعمل مع OpenID Connect مع هذه الخدمة (باستثناء كائن طلب OpenID).