يمكن استخدام واجهات برمجة التطبيقات OAuth 2.0 من Google لكل من المصادقة والتفويض. يوضِّح هذا المستند عملية تنفيذ بروتوكول OAuth 2.0 للمصادقة، والتي تتوافق مع مواصفات اتصال OpenID، وهو مُعتمَد OpenID. تنطبق أيضًا المستندات المذكورة في استخدام OAuth 2.0 للوصول إلى واجهات برمجة تطبيقات Google على هذه الخدمة. وإذا كنت تريد استكشاف هذا البروتوكول بشكل تفاعلي، ننصحك باستخدام مساحة لعب 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 ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.
ضبط معرِّف موارد منتظم (URI) لإعادة التوجيه
يحدّد معرّف الموارد المنتظم (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 الأخرى.
وتعرض أيضًا شاشة موافقة المستخدم معلومات عن العلامة التجارية، مثل اسم منتجك وشعاره وعنوان URL للصفحة الرئيسية. يمكنك التحكّم في معلومات العلامة التجارية في API Console.
لتمكين شاشة الموافقة على مشروعك:
- افتح Consent Screen page في Google API Console .
- If prompted, select a project, or create a new one.
- املأ النموذج وانقر على حفظ .
يعرض مربّع إفادة الموافقة التالي ما سيراه المستخدم عند استخدام مجموعة من نطاقَي OAuth 2.0 وGoogle Drive في الطلب. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة لعب Google OAuth 2.0، لذلك لا يتضمّن معلومات العلامة التجارية التي سيتم تحديدها في API Console.)
الوصول إلى الخدمة
تقدّم Google والجهات الخارجية مكتبات يمكنك استخدامها لمراعاة العديد من تفاصيل التنفيذ حول مصادقة المستخدمين والوصول إلى واجهات Google APIs. ومن الأمثلة على ذلك خدمات Google Identity ومكتبات برامج Google والمتوفرة لمجموعة متنوعة من الأنظمة الأساسية.
إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في بقية هذا المستند، والتي توضّح مسارات طلبات HTTP التي تكون ضمن المكتبات المتاحة.
مصادقة المستخدم
تتضمّن مصادقة المستخدم الحصول على رمز مميّز لإثبات الهوية والتحقّق منه. الرموز المميّزة للمعرّف هي ميزة موحّدة في OpenID Connect مصمّمة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.
إنّ الأساليب الأكثر استخدامًا لمصادقة المستخدم والحصول على الرمز المميّز لرقم التعريف تُعرف باسم المسار "الخادم" والمسار "الضمني". يسمح مسار الخادم للخادم الخلفي للتطبيق بالوصول إلى هويته باستخدام متصفّح أو جهاز جوّال. ويتم استخدام التدفّق الضمني عندما يحتاج تطبيق من جهة العميل (عادةً يكون تطبيق JavaScript قيد التشغيل في المتصفّح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من الوصول إليه من خلال الخادم الخلفي.
يوضّح هذا المستند طريقة تنفيذ تدفق الخادم لمصادقة المستخدم. وتكون عملية التدفّق الضمني أكثر تعقيدًا بشكل كبير بسبب المخاطر الأمنية المرتبطة بمعالجة الرموز المميّزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ مسار ضمني، ننصحك بشدة باستخدام خدمات هوية Google.
تدفق الخادم
احرص على إعداد تطبيقك في API Console لتفعيله لاستخدام هذه البروتوكولات ومصادقة المستخدمين. عندما يحاول مستخدم تسجيل الدخول باستخدام حساب Google، ستحتاج إلى:
- إنشاء رمز مميّز لحالة التزوير
- إرسال طلب مصادقة إلى Google
- تأكيد الرمز المميز لحالة التزوير
- Exchange
codeللرمز المميّز للوصول والرمز المميّز لرقم التعريف - الحصول على معلومات المستخدم من الرمز المميّز لرقم التعريف
- مصادقة المستخدم
1- إنشاء رمز مميّز لحالة التزوير
يجب حماية أمان المستخدمين من خلال منع هجمات تزوير الطلبات. تتمثل الخطوة الأولى في إنشاء رمز مميّز فريد للجلسة يحدِّد الحالة بين تطبيقك وعميل المستخدم. ويمكنك لاحقًا مطابقة هذا الرمز المميز للجلسة الفريدة مع استجابة المصادقة التي تعرضها خدمة تسجيل الدخول إلى Google OAuth للتحقّق من أن المستخدم يقدّم الطلب وليس مهاجمًا ضارًا. وغالبًا ما يُشار إلى هذه الرموز المميّزة باسم رموز مميّزة لتقديم طلبات على مواقع إلكترونية مختلفة (CSRF).
إنّ خيار واحد للرمز المميّز للحالة هو سلسلة من 30 حرفًا تقريبًا يتم إنشاؤها باستخدام أداة إنشاء أرقام عشوائية عالية الجودة. وهناك تجزئة أخرى يتم إنشاؤها من خلال التوقيع على بعض متغيّرات حالة الجلسة باستخدام مفتاح يتم الاحتفاظ به سرًا في الخلفية.
ويوضّح الرمز التالي إنشاء رموز مميّزة فريدة للجلسة.
2,999
ويجب تنزيل مكتبة برامج 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) الأساسي من مستند Discovery باستخدام قيمة البيانات الوصفية 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 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:
2,999
ويجب تنزيل مكتبة برامج 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 مشفّر بترميز 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 |
دائمًا | وقت إصدار الرمز المميّز لرقم التعريف ويتم تمثيلها بتوقيت 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 على بروتوكول 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.
في حال عدم توفُّر مستخدم في قاعدة بيانات المستخدمين، عليك إعادة توجيه المستخدم إلى مسار اشتراك المستخدم الجديد. قد تتمكّن من التسجيل التلقائي للمستخدم استنادًا إلى المعلومات التي تتلقّاها من Google، أو على الأقل قد تتمكّن من ملء العديد من الحقول التي تطلبها في نموذج التسجيل على الأقل. بالإضافة إلى المعلومات الواردة في الرمز المميّز لرقم التعريف، يمكنك الحصول على معلومات إضافية عن الملف الشخصي للمستخدم في نقاط نهاية الملف الشخصي للمستخدم.
المواضيع المتقدمة
تصف الأقسام التالية واجهة برمجة التطبيقات OAuth 2.0 في Google بمزيد من التفصيل. هذه المعلومات مخصّصة لمطوّري البرامج الذين لديهم متطلبات متقدمة حول المصادقة والتفويض.
الوصول إلى واجهات Google API الأخرى
ومن مزايا استخدام OAuth 2.0 للمصادقة أنّ تطبيقك يمكن أن يحصل على
إذن باستخدام واجهات Google API أخرى بالنيابة عن المستخدم (مثل YouTube أو Google Drive أو
"تقويم Google" أو "جهات اتصال Google") في الوقت نفسه الذي تتم فيه مصادقة المستخدم. ولإجراء ذلك، يجب تضمين النطاقات الأخرى التي تحتاج إليها في طلب المصادقة الذي ترسله إلى Google. على سبيل المثال، لإضافة الفئة العمرية للمستخدم إلى طلب المصادقة، يجب
تمرير معلَمة النطاق
openid email https://www.googleapis.com/auth/profile.agerange.read. تتم مطالبة المستخدم بشكل مناسب على شاشة الموافقة. إنّ رمز الدخول
الذي تتلقّاه من Google يتيح لك الوصول إلى جميع واجهات برمجة التطبيقات ذات الصلة بنطاقات
الوصول التي طلبتها، وتم منحها.
إعادة تحميل الرموز المميزة
في طلبك للوصول إلى واجهة برمجة التطبيقات، يمكنك طلب عرض رمز مميّز لإعادة التحميل خلال
استبدال code. يوفر الرمز المميز لإعادة التحميل تطبيقك
إمكانية وصول مستمرة إلى واجهات برمجة تطبيقات Google أثناء عدم وجود المستخدم في تطبيقك. لطلب رمز مميّز لإعادة التحميل، أضِف المعلَمة access_type إلى offline في طلب المصادقة.
نقاط يجب أخذها في الاعتبار:
- احرص على تخزين الرمز المميّز لإعادة التحميل بأمان دائمًا، لأنّه يمكنك الحصول فقط على الرمز المميّز لإعادة التحميل في المرة الأولى التي تجري فيها عملية تبادل الرمز.
- هناك حدود لعدد الرموز المميّزة لإعادة التحميل التي يتم إصدارها: حد لكل عميل/مستخدم ووضع حد أقصى لكل مستخدم في جميع البرامج. إذا طلب التطبيق عددًا كبيرًا جدًا من الرموز المميّزة لإعادة التحميل، قد تُستنفد هذه الحدود، وفي هذه الحالة، تتوقف الرموز المميّزة القديمة لإعادة التحميل.
ولمزيد من المعلومات، يُرجى الاطّلاع على القسم إعادة تحميل رمز الدخول (بلا إنترنت).
طلب إعادة الموافقة
يمكنك مطالبة المستخدم بإعادة تفويض تطبيقك عن طريق ضبط مَعلمة prompt على consent في طلب المصادقة. عند تضمين السمة prompt=consent، يتم عرض شاشة طلب الموافقة في كل مرة يطلب فيها تطبيقك تفويضًا لنطاقات الوصول، حتى إذا تم منح جميع النطاقات مسبقًا لمشروعك على Google APIs. لهذا
السبب، ضمِّن prompt=consent عند الضرورة فقط.
لمزيد من المعلومات عن المَعلمة prompt، يُرجى الاطّلاع على prompt
في جدول معلّمات معرّف الموارد المنتظم (URI) للمصادقة.
معلمات معرّفات الموارد المنتظمة (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) لإعادة التوجيه من أجل استرداد
الرموز المميّزة من معرّف الموارد المنتظم (URI) #fragment. |
redirect_uri |
(مطلوب) | تحدِّد هذه السياسة مكان إرسال الردّ. ويجب أن تتطابق قيمة هذه المعلَمة تمامًا مع إحدى قيم إعادة التوجيه المصرّح بها التي حددتها في Credentials page ( API Consoleبما في ذلك مخطط HTTP أو HTTPS وحالة الأحرف والحرف اللاحقة "/"، إن وجدت). |
scope |
(مطلوب) | يجب أن تبدأ مَعلمة النطاق بالقيمة إذا كانت قيمة نطاق في حال توفّر قيمة النطاق بالإضافة إلى هذه النطاقات الخاصة بـ OpenID، يمكن أن تتضمن وسيطة نطاق أيضًا قيمًا أخرى للنطاق. يجب أن تكون جميع قيم النطاقات مفصولة بمسافة. على سبيل المثال، إذا كنت تريد
الوصول إلى كل ملف على Google Drive لمستخدم، قد تكون معلَمة نطاقك
للحصول على معلومات عن النطاقات المتاحة، يُرجى الاطّلاع على نطاقات OAuth 2.0 لواجهات برمجة تطبيقات Google أو مستندات واجهة برمجة تطبيقات Google التي تريد استخدامها. |
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 أو داخل عناوين الطلبات. وفي حال تخزين الرموز المميّزة لرقم التعريف على خادمك، عليك أيضًا تخزينها بأمان.
ما يميّز الرموز المميّزة للمعرّفات هو أنّك يمكنك تمريرها إلى مختلف مكوّنات تطبيقك. ويمكن لهذه المكوّنات استخدام رمز مميّز للمعرّف كآلية مصادقة بسيطة للمصادقة على التطبيق والمستخدم. قبل أن تتمكّن من استخدام المعلومات في الرمز المميّز للمعرّف أو الاعتماد عليها كتأكيد على أنّ المستخدم قد مصادقة، عليك إثبات صحتها.
يتطلب التحقق من الرمز المميز لرقم التعريف عدة خطوات:
- تحقَّق من أنّ جهة الإصدار قد وقّعت على نحو صحيح في الرمز المميّز لرقم التعريف. يتم توقيع الرموز المميزة التي تصدرها 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) للمفاتيح من مستند Discovery باستخدام قيمة البيانات الوصفية jwks_uri. قد يتم تقييد الطلبات الواردة إلى نقطة نهاية تصحيح الأخطاء
أو قد تحدث أخطاء متقطّعة.
ولأنّ محرّك بحث Google لا يغيّر مفاتيحه العامة سوى نادرًا، يمكنك تخزينها مؤقتًا باستخدام توجيهات ذاكرة التخزين المؤقت الخاصة باستجابة HTTP، وفي معظم الحالات، يمكن تنفيذ عملية التحقّق من الجهاز محليًا بفعالية أكبر من استخدام نقطة النهاية tokeninfo. وتتطلّب عملية التحقّق هذه استرداد الشهادات وتحليلها، وإجراء الطلبات المشفّرة المناسبة
للتحقّق من التوقيع. الكثير من المكتبات التي تقدّم تصحيح أخطاء لها تتوفر بلغات مختلفة لتنفيذ ذلك (راجِع jwt.io).
الحصول على معلومات الملف الشخصي للمستخدم
للحصول على معلومات إضافية عن الملف الشخصي عن المستخدم، يمكنك استخدام رمز الدخول (الذي يتلقّاه تطبيقك أثناء خطوات المصادقة) ومعيار اتصال OpenID:
للالتزام بسياسة OpenID، يجب تضمين قيم نطاق
openid profileفي طلب المصادقة.إذا كنت تريد تضمين عنوان البريد الإلكتروني للمستخدم، يمكنك تحديد قيمة إضافية لنطاق
email. لتحديدprofileوemail، يمكنك تضمين المعلَمة التالية في معرّف الموارد المنتظم (URI) لطلب المصادقة:scope=openid%20profile%20email
- أضِف رمز الدخول إلى عنوان التفويض وقدِّم طلب
GETعبر HTTPS إلى نقطة نهاية userinfo، التي يجب استردادها من مستند Discovery باستخدام قيمة البيانات الوصفيةuserinfo_endpoint. تتضمّن استجابة userinfo معلومات عن المستخدم على النحو الموضّح فيOpenID Connect Standard Claimsوقيمةclaims_supportedللبيانات الوصفية في مستند "اقتراحات". وقد يختار المستخدمون أو مؤسساتهم تقديم حقول معيّنة أو حجبها، لذلك قد لا تحصل على معلومات لكل حقل لنطاقات الوصول المصرّح بها.
مستند Discovery
يتطلب بروتوكول OpenID Connect استخدام نقاط نهاية متعددة لمصادقة المستخدمين ولطلب الموارد، بما في ذلك الرموز المميّزة ومعلومات المستخدم والمفاتيح العامة.
لتبسيط عمليات التنفيذ وزيادة المرونة، يسمح OpenID Connect باستخدام "مستند أثناء التصفّح"، وهو مستند JSON تم العثور عليه في موقع معروف يحتوي على أزواج المفتاح/القيمة التي تقدّم تفاصيل حول إعداد موفّر OpenID، بما في ذلك معرّفات الموارد المنتظمة (URI) للرمز المميّز والإبطال ومعلومات المستخدم ونقاط النهاية العامة. قد يتم استرداد مستند Discovery لخدمة OpenID Connect من Google من:
https://accounts.google.com/.well-known/openid-configuration
لاستخدام خدمات OpenID من Google، عليك ترميز معرّف الموارد المنتظم (URI) للمستند أثناء التصفّح (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:
{
"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).