يمكن استخدام واجهات برمجة التطبيقات OAuth 2.0 من Google لكل من المصادقة والتفويض. يصف هذا المستند عملية تنفيذ OAuth 2.0 للمصادقة، والتي تتوافق مع مواصفات OpenID Connect، وهي معتمدة من OpenID. تنطبق أيضًا الوثائق الواردة في استخدام OAuth 2.0 للوصول إلى Google APIs على هذه الخدمة أيضًا. وإذا أردت استكشاف هذا البروتوكول بشكل تفاعلي، نقترح عليك استخدام مساحة تشغيل OAuth 2.0 من Google. للحصول على مساعدة بشأن Stack Overflow، يمكنك وضع علامة "google-oauth" على أسئلتك.
إعداد OAuth 2.0
قبل أن يتمكّن تطبيقك من استخدام نظام مصادقة OAuth 2.0 من Google لتسجيل دخول المستخدم، يجب إعداد مشروع في Google API Console للحصول على بيانات اعتماد OAuth 2.0، وضبط عنوان URL لإعادة التوجيه، وتخصيص معلومات العلامة التجارية التي تظهر للمستخدمين في شاشة موافقة المستخدم (اختياريًا). يمكنك أيضًا استخدام API Console لإنشاء حساب خدمة وتفعيل الفوترة وإعداد الفلترة وتنفيذ مهام أخرى. لمزيد من التفاصيل، راجِع مساعدةGoogle API Console.
الحصول على بيانات اعتماد OAuth 2.0
تحتاج إلى بيانات اعتماد OAuth 2.0، بما في ذلك معرِّف العميل وسر العميل لمصادقة المستخدمين والوصول إلى واجهات برمجة التطبيقات من Google.
لعرض معرف العميل وسر العميل لبيانات اعتماد OAuth 2.0 معينة ، انقر على النص التالي: حدد بيانات الاعتماد . في النافذة التي تفتح ، اختر مشروعك وبيانات الاعتماد التي تريدها ، ثم انقر فوق عرض .
أو اعرض معرف العميل وسر العميل من صفحة بيانات الاعتماد في API Console :
- Go to the Credentials page.
- انقر فوق اسم بيانات الاعتماد الخاصة بك أو رمز القلم الرصاص ( create ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.
ضبط عنوان URL لإعادة التوجيه
إنّ عنوان URL لإعادة التوجيه الذي تضبطه في 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.)

الوصول إلى الخدمة
توفر Google والجهات الخارجية مكتبات يمكنك استخدامها للاعتناء بالعديد من تفاصيل التنفيذ المتعلقة بمصادقة المستخدمين والحصول على إمكانية الوصول إلى واجهات Google APIs. ومن الأمثلة على ذلك خدمات هوية Google ومكتبات عملاء Google المتاحة لمجموعة متنوعة من الأنظمة الأساسية.
إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في بقية هذا المستند، والتي تصف تدفقات طلبات HTTP التي تقع ضمن المكتبات المتاحة.
مصادقة المستخدم
تتضمن مصادقة المستخدم الحصول على رمز مميز للمعرف والتحقق من صحته. الرموز المميّزة لمعرّفات الهوية هي ميزة موحّدة في اتصال OpenID مصمَّمة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.
يُطلق على الأساليب الأكثر استخدامًا لمصادقة المستخدم والحصول على الرمز المميّز للمعرّف مسار "الخادم" والمسار "الضمني". يسمح مسار الخادم لخادم الخلفية لأحد التطبيقات بإثبات هوية الشخص باستخدام متصفّح أو جهاز جوّال. ويُستخدَم المسار الضمني عندما يحتاج تطبيق من جهة العميل (عادةً تطبيق JavaScript يتم تشغيله في المتصفّح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من الوصول عبر خادم الخلفية.
يصف هذا المستند كيفية تنفيذ تدفق الخادم لمصادقة المستخدم. ويكون التدفّق الضمني أكثر تعقيدًا إلى حدّ كبير بسبب المخاطر المتعلّقة بالأمان في معالجة الرموز المميّزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ مسار ضمني، ننصحك بشدة باستخدام خدمات هوية Google.
مسار الخادم
تأكَّد من إعداد تطبيقك في API Console لتفعيله من أجل استخدام هذه البروتوكولات ومصادقة المستخدمين. عندما يحاول المستخدم تسجيل الدخول باستخدام حساب Google، عليك إجراء ما يلي:
- إنشاء رمز مميّز لحالة مكافحة التزوير
- إرسال طلب مصادقة إلى Google
- تأكيد الرمز المميّز لحالة مكافحة التزوير
- Exchange
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
باستخدام مَعلمات معرّف الموارد المنتظم (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. يجب أن تتطابق القيمة تمامًا مع أحد عناوين URL المعتمَدة لإعادة التوجيه لبرنامج 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 Connect لمستخدمي نطاق معيّن مرتبط بمؤسسة على Google 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 API. |
expires_in |
المدة المتبقية لرمز الدخول بالثواني. |
id_token |
ملف JWT يتضمّن معلومات هوية المستخدم التي وقّعت Google رقميًا عليها. |
scope |
نطاقات الوصول التي تم منحها من خلال access_token ، ويتم التعبير عنها في شكل قائمة من سلاسل
سلاسل حساسة ومفصولة بمسافات. |
token_type |
تحدّد نوع الرمز المميّز الذي يتم عرضه. في الوقت الحالي، يحتوي هذا الحقل دائمًا على القيمة Bearer .
|
refresh_token |
(اختياري)
لا يتوفّر هذا الحقل إلا إذا تم ضبط المَعلمة
|
5. الحصول على معلومات المستخدم من الرمز المميّز للمعرّف
الرمز المميّز للمعرّف هو JWT (رمز JSON للويب)، وهو كائن 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 |
دائمًا | وقت انتهاء الصلاحية الذي يجب عدم قبول الرمز المميّز للمستند بعد هذا التاريخ ويمكن تمثيلها بتنسيق Unix (عدد صحيح بالثواني). |
iat |
دائمًا | وقت إصدار الرمز المميّز للمعرّف ويتم تمثيلهما بوقت يونكس (عدد صحيح بالثواني). |
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
يختلفان عن نوع OAuth 2.0 client_id ولكنهما يتشاركان في مشروع Google APIs نفسه. |
|
email |
عنوان البريد الإلكتروني للمستخدم قد لا تكون هذه القيمة فريدة لهذا المستخدم ولا تكون مناسبة
للاستخدام كمفتاح أساسي. يتم تقديمها فقط إذا كان نطاقك يتضمّن قيمة النطاق email . |
|
email_verified |
صحيح إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم، وإلا فهو خطأ. | |
family_name |
اسم العائلة أو أسماء العائلة للمستخدم. يمكن تقديم هذه السمة عند وجود مطالبة بخدمة
name . |
|
given_name |
الاسم الأول للمستخدم أو الأسماء الأولى له. يمكن تقديم هذه السمة عند وجود مطالبة بخدمة
name . |
|
hd |
النطاق المرتبط لمؤسسة Google Cloud للمستخدم. يتم تقديم هذه المعلومات فقط إذا كان المستخدم ينتمي إلى مؤسسة في Google Cloud. | |
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 الأخرى نيابةً عن المستخدم (مثل YouTube أو Google Drive
أو "تقويم 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، التي عليك استردادها من مستند "الاكتشاف" باستخدام قيمة البيانات الوصفيةuserinfo_endpoint
. يتضمن الردّ على userinfo معلومات عن المستخدم، كما هو موضّح فيOpenID Connect Standard Claims
وقيمة البيانات الوصفية للسمةclaims_supported
ضمن مستند Discovery. قد يختار المستخدمون أو مؤسساتهم توفير حقول معيّنة أو حجزها، لذا قد لا تحصل على معلومات عن كل حقل لنطاقات الوصول المصرَّح بها.
مستند Discovery
يتطلب بروتوكول 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
) بشكل ثابت في تطبيقك.
يجلب التطبيق المستند ويطبّق قواعد التخزين المؤقت في الاستجابة، ثم يسترد عناوين URL لنقاط النهاية منه حسب الحاجة. على سبيل المثال، لمصادقة مستخدم، سيسترجع الرمز قيمة البيانات الوصفية 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" ] }
قد تتمكن من تجنب نقل بيانات HTTP ذهابًا وإيابًا من خلال تخزين القيم مؤقتًا من مستند Discovery. يتم استخدام رؤوس التخزين المؤقت القياسية عبر بروتوكول HTTP ويجب الالتزام بها.
مكتبات العملاء
تسهّل مكتبات العملاء التالية تنفيذ OAuth 2.0 من خلال التكامل مع أُطر العمل الرائجة:
- مكتبة برامج Google APIs للغة Java
- مكتبة برامج Google APIs للغة Python
- مكتبة برامج Google APIs لنظام NET .
- مكتبة برامج Google APIs للغة Ruby
- مكتبة برامج Google APIs للغة PHP
- مكتبة OAuth 2.0 لمجموعة أدوات الويب من Google
- مجموعة أدوات Google لوحدات التحكّم التي تستخدم بروتوكول OAuth 2.0 لنظام التشغيل Mac
الامتثال لاتصال OpenID
يتوافق نظام مصادقة OAuth 2.0 من Google مع الميزات المطلوبة لمواصفات OpenID Connect Core. أي برنامج تم تصميمه للعمل مع OpenID Connect يجب أن يتوافق مع هذه الخدمة (باستثناء كائن طلب OpenID).