اتصال OpenID

يمكن استخدام واجهات برمجة التطبيقات 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 :

  1. Go to the Credentials page.
  2. انقر فوق اسم بيانات الاعتماد الخاصة بك أو رمز القلم الرصاص ( ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.

ضبط عنوان URL لإعادة التوجيه

إنّ عنوان URL لإعادة التوجيه الذي تضبطه في API Console يحدّد المكان الذي يرسل فيه محرّك بحث Google الردود على طلبات المصادقة.

لإنشاء أو عرض أو تحرير عناوين URI المعاد توجيهها لبيانات اعتماد OAuth 2.0 ، قم بما يلي:

  1. Go to the Credentials page.
  2. في قسم معرفات عميل OAuth 2.0 من الصفحة ، انقر على بيانات الاعتماد.
  3. عرض أو تحرير عناوين URI المعاد توجيهها.

إذا لم يكن هناك قسم معرفات عميل OAuth 2.0 في صفحة بيانات الاعتماد ، فلن يحتوي مشروعك على بيانات اعتماد OAuth. لإنشاء واحدة ، انقر فوق إنشاء بيانات الاعتماد .

تخصيص شاشة موافقة المستخدم

بالنسبة إلى المستخدمين، تتضمن تجربة مصادقة OAuth 2.0 شاشة موافقة تصف المعلومات التي سيصدرها المستخدم والبنود السارية. على سبيل المثال، عندما يسجّل المستخدم الدخول، قد يُطلب منه منح تطبيقك إمكانية الوصول إلى عنوان بريده الإلكتروني ومعلومات الحساب الأساسية. ويمكنك طلب الوصول إلى هذه المعلومات باستخدام المَعلمة scope التي يتضمّنها تطبيقك في طلب المصادقة. يمكنك أيضًا استخدام النطاقات لطلب الوصول إلى Google APIs الأخرى.

تعرض شاشة موافقة المستخدم أيضًا معلومات العلامة التجارية، مثل اسم منتجك وشعاره وعنوان URL للصفحة الرئيسية. يمكنك التحكم في معلومات العلامة التجارية في API Console.

لتمكين شاشة الموافقة على مشروعك:

  1. افتح Consent Screen page في Google API Console .
  2. If prompted, select a project, or create a new one.
  3. املأ النموذج وانقر على حفظ .

يعرض مربّع إفادة الموافقة التالي ما يراه المستخدم عند توفُّر مجموعة من نطاقات OAuth 2.0 وGoogle Drive في الطلب. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة تشغيل OAuth 2.0 من Google، لذلك لا يتضمّن معلومات العلامة التجارية التي قد يتم ضبطها في API Console.)

لقطة شاشة لصفحة الموافقة

الوصول إلى الخدمة

توفر Google والجهات الخارجية مكتبات يمكنك استخدامها للاعتناء بالعديد من تفاصيل التنفيذ المتعلقة بمصادقة المستخدمين والحصول على إمكانية الوصول إلى واجهات Google APIs. ومن الأمثلة على ذلك خدمات هوية Google ومكتبات عملاء Google المتاحة لمجموعة متنوعة من الأنظمة الأساسية.

إذا اخترت عدم استخدام مكتبة، اتّبِع التعليمات الواردة في بقية هذا المستند، والتي تصف تدفقات طلبات HTTP التي تقع ضمن المكتبات المتاحة.

مصادقة المستخدم

تتضمن مصادقة المستخدم الحصول على رمز مميز للمعرف والتحقق من صحته. الرموز المميّزة لمعرّفات الهوية هي ميزة موحّدة في اتصال OpenID مصمَّمة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.

يُطلق على الأساليب الأكثر استخدامًا لمصادقة المستخدم والحصول على الرمز المميّز للمعرّف مسار "الخادم" والمسار "الضمني". يسمح مسار الخادم لخادم الخلفية لأحد التطبيقات بإثبات هوية الشخص باستخدام متصفّح أو جهاز جوّال. ويُستخدَم المسار الضمني عندما يحتاج تطبيق من جهة العميل (عادةً تطبيق JavaScript يتم تشغيله في المتصفّح) إلى الوصول إلى واجهات برمجة التطبيقات مباشرةً بدلاً من الوصول عبر خادم الخلفية.

يصف هذا المستند كيفية تنفيذ تدفق الخادم لمصادقة المستخدم. ويكون التدفّق الضمني أكثر تعقيدًا إلى حدّ كبير بسبب المخاطر المتعلّقة بالأمان في معالجة الرموز المميّزة واستخدامها من جهة العميل. إذا كنت بحاجة إلى تنفيذ مسار ضمني، ننصحك بشدة باستخدام خدمات هوية Google.

مسار الخادم

تأكَّد من إعداد تطبيقك في API Console لتفعيله من أجل استخدام هذه البروتوكولات ومصادقة المستخدمين. عندما يحاول المستخدم تسجيل الدخول باستخدام حساب Google، عليك إجراء ما يلي:

  1. إنشاء رمز مميّز لحالة مكافحة التزوير
  2. إرسال طلب مصادقة إلى Google
  3. تأكيد الرمز المميّز لحالة مكافحة التزوير
  4. Exchange code لرمز الدخول والرمز المميز لرقم التعريف
  5. الحصول على معلومات المستخدم من الرمز المميّز للمعرّف
  6. مصادقة المستخدم

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 (اختياري)

لا يتوفّر هذا الحقل إلا إذا تم ضبط المَعلمة access_type على offline في طلب المصادقة. لمعرفة التفاصيل، يُرجى الاطّلاع على إعادة تحميل الرموز المميّزة.

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 الاسم الكامل للمستخدم في شكل قابل للعرض. يمكن تقديم هذه المعلومات في الحالات التالية:
  • اشتمل نطاق الطلب على السلسلة "profile"
  • عرض الرمز المميز للرقم التعريفي من إعادة تحميل الرمز المميز

عند تقديم مطالبات name، يمكنك استخدامها لتعديل سجلات المستخدمين في تطبيقك. تجدر الإشارة إلى أنّه لا يمكن أبدًا ضمان ظهور هذه المطالبة.

nonce قيمة nonce التي يوفّرها تطبيقك في طلب المصادقة. عليك فرض الحماية ضد هجمات إعادة التشغيل من خلال ضمان تقديمها مرة واحدة فقط.
picture عنوان URL لصورة الملف الشخصي للمستخدم. يمكن تقديم هذه المعلومات في الحالات التالية:
  • اشتمل نطاق الطلب على السلسلة "profile"
  • عرض الرمز المميز للرقم التعريفي من إعادة تحميل الرمز المميز

عند تقديم مطالبات picture، يمكنك استخدامها لتعديل سجلات المستخدمين في تطبيقك. تجدر الإشارة إلى أنّه لا يمكن أبدًا ضمان ظهور هذه المطالبة.

profile عنوان URL لصفحة الملف الشخصي للمستخدم. يمكن تقديم هذه المعلومات في الحالات التالية:
  • اشتمل نطاق الطلب على السلسلة "profile"
  • عرض الرمز المميز للرقم التعريفي من إعادة تحميل الرمز المميز

عند تقديم مطالبات profile، يمكنك استخدامها لتعديل سجلات المستخدمين في تطبيقك. تجدر الإشارة إلى أنّه لا يمكن أبدًا ضمان ظهور هذه المطالبة.

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 ثم تتضمّن القيمة profile أو القيمة email أو كليهما.

في حال توفُّر قيمة نطاق profile، قد يتضمّن الرمز المميّز للمعرّف (ولكن ليس من المضمون ذلك) مطالبات profile التلقائية للمستخدم.

في حال توفُّر قيمة نطاق email، يتضمّن الرمز المميّز للمعرّف مطالبتَي email وemail_verified.

بالإضافة إلى هذه النطاقات الخاصة بـ OpenID، يمكن أن تتضمن وسيطة النطاق أيضًا قيمًا أخرى للنطاق. يجب أن تكون جميع قيم النطاق مفصولة بمسافات. على سبيل المثال، إذا أردت الوصول إلى كل ملف في حساب أحد المستخدمين على Google Drive، قد تكون مَعلمة النطاق openid profile email https://www.googleapis.com/auth/drive.file.

للحصول على معلومات عن النطاقات المتاحة، يُرجى الاطّلاع على نطاقات OAuth 2.0 لواجهات Google APIs أو مستندات Google API التي تريد استخدامها.

state (اختياري، ولكن ننصح به بشدة)

سلسلة مبهمة يتم تناولها ذهابًا وإيابًا في البروتوكول، أي أنّه يتم عرضها كمَعلَمة معرّف موارد منتظم (URI) في المسار الأساسي، وفي معرّف #fragment معرّف الموارد المنتظم (URI) في التدفق الضمني.

ويمكن أن تفيدك السمة state في الربط بين الطلبات والردود. بما أنّه يمكن تخمين redirect_uri، يمكن أن يزيد استخدام قيمة state من ضمانك بأنّ الاتصال الوارد هو نتيجة طلب مصادقة أرسله تطبيقك. وفي حال إنشاء سلسلة عشوائية أو ترميز تجزئة حالة عميل (مثل ملف تعريف ارتباط) في متغيّر state هذا، يمكنك التحقّق من صحة الاستجابة للتأكد من أنّ الطلب والاستجابة قد صدرا في المتصفّح نفسه. ويوفّر ذلك حماية من هجمات، مثل تزوير الطلبات من موقع إلكتروني مختلف.

access_type (سؤال اختياري) القيمتان المسموح بإدراجهما هما offline وonline. تم توثيق التأثير في ميزة الوصول بلا إنترنت. وفي حال طلب رمز دخول، لن يتلقى البرنامج الرمز المميز لإعادة التحميل ما لم يتم تحديد قيمة offline.
display (سؤال اختياري) قيمة سلسلة ASCII لتحديد كيفية عرض خادم التفويض لصفحات واجهة المستخدم الخاصة بالمصادقة والموافقة. ويتم تحديد القيم التالية وقبولها من خلال خوادم Google، ولكن ليس لها أي تأثير في طريقة عملها: page وpopup وtouch وwap.
hd (سؤال اختياري)

يمكنك تبسيط عملية تسجيل الدخول إلى الحسابات التي تمتلكها مؤسسة على Google Cloud. من خلال تضمين نطاق المؤسسة على Google Cloud (على سبيل المثال، mycollege.edu)، يمكنك الإشارة إلى ضرورة تحسين واجهة مستخدم اختيار الحسابات للحسابات في ذلك النطاق. لتحسين حسابات المؤسسات على Google Cloud بشكلٍ عام بدلاً من نطاق مؤسسة واحد فقط على Google Cloud، اضبط قيمة علامة النجمة (*): hd=*.

لا تعتمد على تحسين واجهة المستخدم هذا للتحكم في الأشخاص الذين يمكنهم الوصول إلى تطبيقك، إذ يمكن تعديل الطلبات من جهة العميل. احرص على validate من أنّ الرمز المميّز للمعرّف الذي تم عرضه يتضمّن قيمة مطالبة hd تتطابق مع ما تتوقّعه (مثل mycolledge.edu). وعلى عكس مَعلمة الطلب، فإنّ المطالبة التي تتضمّن رمز المعرّف المميز hd مضمّنة في رمز أمان مميّز من Google، لذا يمكن الوثوق بالقيمة.

include_granted_scopes (سؤال اختياري) إذا تم توفير هذه المَعلمة مع القيمة true وتم منح طلب التفويض، سيتضمّن التفويض أي أذونات سابقة تم منحها لهذا المستخدم أو التطبيق لنطاقات أخرى. يُرجى مراجعة التفويض الإضافي.

تجدر الإشارة إلى أنّه لا يمكنك إجراء تفويض متزايد مع مسار التطبيقات المُثبَّتة.

login_hint (سؤال اختياري) عندما يحدد تطبيقك المستخدم الذي يحاول مصادقته، يمكن أن يقدّم هذه المَعلمة كتلميح لخادم المصادقة. يؤدي تمرير هذا التلميح إلى إيقاف محدِّد الحساب وإما ملء مربّع البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو اختيار الجلسة المناسبة (إذا كان المستخدم يستخدم تسجيل الدخول المتعدد)، ما يمكن أن يساعدك في تجنّب المشاكل التي تحدث إذا سجّل تطبيقك في حساب المستخدم غير الصحيح. يمكن أن تكون القيمة إما عنوان بريد إلكتروني أو سلسلة sub، ما يعادل معرّف Google للمستخدم.
prompt (سؤال اختياري) يشير ذلك المصطلح إلى قائمة قيم السلسلة مع الفصل بينها بمسافات والتي تحدِّد ما إذا كان خادم التفويض يطلب من المستخدم إعادة المصادقة والموافقة. في ما يلي القيم المحتمَلة:
  • none

    لا يعرض خادم التفويض أي شاشات مصادقة أو موافقة المستخدم، بل سيعرض رسالة خطأ إذا لم يكن المستخدم قد تمت مصادقته سابقًا ولم يضبط موافقة مسبقة للنطاقات المطلوبة. يمكنك استخدام none للتحقق من مصادقة و/أو موافقة حالية.

  • consent

    يطلب خادم التفويض من المستخدم الموافقة قبل عرض المعلومات للعميل.

  • select_account

    يطلب خادم التفويض من المستخدم اختيار حساب مستخدم. ويتيح هذا للمستخدم الذي لديه حسابات متعددة على خادم التفويض إمكانية الاختيار من بين الحسابات المتعددة التي قد تكون لديه جلسات حالية لها.

إذا لم يتم تحديد أي قيمة ولم يسبق للمستخدم منح الإذن بالوصول، ستظهر للمستخدم شاشة طلب الموافقة.

جارٍ التحقّق من الرمز المميّز للمعرّف

يجب التحقّق من صحة جميع الرموز المميّزة للمعرّفات على خادمك ما لم تكن تعرف أنّها واردة مباشرةً من Google. على سبيل المثال، يجب أن يتحقق الخادم من صحة أي رموز مميزة للأرقام التعريفية يتلقّاها من تطبيقات العميل.

في ما يلي الحالات الشائعة التي يمكنك فيها إرسال رموز مميزة للمعرّف إلى خادمك:

  • إرسال الرموز المميّزة للمعرّف مع الطلبات التي يجب مصادقتها تُطلعك الرموز المميّزة للمعرّف على المستخدم المحدّد الذي قدّم الطلب وعن البرنامج الذي تم منح الرمز المميّز للمعرّف له.

الرموز المميّزة لمستند التعريف حسّاسة ويمكن إساءة استخدامها في حال اعتراضها. يجب التأكد من التعامل مع هذه الرموز المميّزة بأمان عن طريق نقلها فقط عبر HTTPS وبيانات POST فقط أو ضمن عناوين الطلبات. في حال تخزين الرموز المميّزة للمعرّف على خادمك، يجب أيضًا تخزينها بشكلٍ آمن.

أحد العوامل التي تجعل الرموز المميّزة للمعرّف مفيدة هي أنّه يمكنك تمريرها حول مكونات مختلفة من تطبيقك. يمكن لهذه المكوّنات استخدام الرمز المميّز للمعرّف كآلية مصادقة خفيفة لمصادقة التطبيق والمستخدم. ولكن قبل أن تتمكّن من استخدام المعلومات في الرمز المميّز للمعرّف أو الاعتماد عليها كتأكيد على أنّ المستخدم قد أجرى المصادقة، يجب أن تتأكّد من صحتها.

يتطلّب إثبات صحة الرمز المميّز للمعرّف عدة خطوات:

  1. تأكَّد من أنّ جهة الإصدار قد وقّعت بشكل صحيح على الرمز المميّز المعرّف. يتم توقيع الرموز المميّزة الصادرة عن Google باستخدام إحدى الشهادات المتوفّرة على معرّف الموارد المنتظم (URI) المحدَّد في قيمة البيانات الوصفية للسمة jwks_uri في مستند "اقتراحات".
  2. تأكَّد من أنّ قيمة مطالبة iss في الرمز المميّز للمعرّف تساوي https://accounts.google.com أو accounts.google.com.
  3. تأكَّد من أنّ قيمة مطالبة aud في الرمز المميّز للمعرّف تساوي قيمة معرّف العميل لتطبيقك.
  4. تأكَّد من عدم انقضاء وقت انتهاء صلاحية (مطالبة واحدة (exp)) للرمز المميّز للمعرّف.
  5. إذا حدّدت قيمة مَعلمة 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:

  1. للامتثال لبنود OpenID، يجب تضمين قيم النطاق openid profile في طلب المصادقة.

    إذا كنت تريد تضمين عنوان البريد الإلكتروني للمستخدم، يمكنك تحديد قيمة نطاق إضافية وهي email. لتحديد كل من profile وemail، يمكنك تضمين المَعلمة التالية في عنوان URI لطلب المصادقة:

    scope=openid%20profile%20email
  2. أضِف رمز الدخول إلى عنوان التفويض وقدِّم طلب 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 من خلال التكامل مع أُطر العمل الرائجة:

الامتثال لاتصال OpenID

يتوافق نظام مصادقة OAuth 2.0 من Google مع الميزات المطلوبة لمواصفات OpenID Connect Core. أي برنامج تم تصميمه للعمل مع OpenID Connect يجب أن يتوافق مع هذه الخدمة (باستثناء كائن طلب OpenID).