اتصال OpenID

يمكن استخدام واجهات برمجة تطبيقات OAuth 2.0 من Google لكل من المصادقة والترخيص. ويوضّح هذا المستند تنفيذ OAuth 2.0 للمصادقة، والذي يتوافق مع مواصفات OpenID Connect، وهو معتمد من OpenID. تسري المستندات الواردة في استخدام OAuth 2.0 للوصول إلى Google APIs أيضًا على هذه الخدمة. إذا أردت استكشاف هذا البروتوكول بشكل تفاعلي، ننصحك بمساحة المرح Google OAuth 2.0. للحصول على مساعدة بشأن Stack Overflow، ضَع علامة "google-oauth" على أسئلتك.

إعداد OAuth 2.0

قبل أن يتمكّن تطبيقك من استخدام نظام مصادقة OAuth 2.0 من Google لتسجيل دخول المستخدم، عليك إعداد مشروع في Google API Console للحصول على بيانات اعتماد OAuth 2.0، وضبط معرّف موارد منتظم (URI) لإعادة التوجيه، وتخصيص (اختياريًا) معلومات العلامة التجارية التي تظهر للمستخدمين على شاشة موافقة المستخدم. يمكنك أيضًا استخدام API Console لإنشاء حساب خدمة وتفعيل الفوترة وإعداد الفلترة وتنفيذ مهام أخرى. لمزيد من التفاصيل، يمكنك الاطّلاع على مساعدةGoogle API Console.

الحصول على بيانات اعتماد OAuth 2.0

تحتاج إلى بيانات اعتماد OAuth 2.0، بما في ذلك معرِّف العميل وسر العميل، لمصادقة المستخدمين والوصول إلى واجهات برمجة تطبيقات Google.

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

1. Go to the Credentials page.
2. Click the name of your credential or the pencil (create) icon. Your client ID and secret are at the top of the page.

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

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

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

1. Go to the Credentials page.
2. In the OAuth 2.0 client IDs section of the page, click a credential.
3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

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

بالنسبة إلى المستخدمين، تتضمن تجربة مصادقة 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 Connect وهي مصممة للاستخدام في مشاركة تأكيدات الهوية على الإنترنت.

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

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

تدفق الخادم

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

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

1- إنشاء رمز مميّز لحالة مكافحة التزييف

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

من بين الخيارات الجيدة للرمز المميّز للحالة سلسلة مكوّنة من 30 حرفًا أو نحو ذلك يتم إنشاؤها باستخدام أداة إنشاء أرقام عشوائية عالية الجودة. والتجزئة الأخرى هي تجزئة يتم إنشاؤها عن طريق توقيع بعض متغيرات حالة الجلسة باستخدام مفتاح يبقى سريًا في الخلفية.

يوضح الرمز التالي إنشاء رموز مميّزة فريدة للجلسة.

// 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
));

// 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);

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. إرسال طلب مصادقة إلى Google

تتمثل الخطوة التالية في إنشاء طلب HTTPS GET باستخدام معلمات URI المناسبة. ضَع في اعتبارك استخدام بروتوكول HTTPS بدلاً من HTTP في جميع خطوات هذه العملية، لأنّه يتم رفض اتصالات HTTP. يجب استرداد معرّف الموارد المنتظم (URI) الأساسي من مستند "اقتراحات" باستخدام قيمة البيانات الوصفية authorization_endpoint. تفترض المناقشة التالية أن معرّف الموارد المنتظم (URI) الأساسي هو https://accounts.google.com/o/oauth2/v2/auth.

بالنسبة إلى الطلب الأساسي، حدِّد المَعلمات التالية:

• client_id، التي تحصل عليها من API Console Credentials page .
• response_type، والذي يجب أن يكون code في طلب مسار رمز التفويض الأساسي. (يمكنك الاطّلاع على مزيد من المعلومات على response_type.)
• scope، والذي يجب أن يكون openid email في الطلب الأساسي. (اطّلِع على مزيد من المعلومات على scope.)
• يجب أن يكون redirect_uri نقطة نهاية HTTP على خادمك الذي سيتلقّى استجابة من Google. يجب أن تتطابق القيمة تمامًا مع أحد معرِّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبرنامج OAuth 2.0، والذي ضبطته في API Console Credentials page. وإذا كانت هذه القيمة لا تتطابق مع معرّف موارد منتظم (URI) مُعتمَد، سيتعذّر تنفيذ الطلب وسيظهر خطأ redirect_uri_mismatch.
• يجب أن تتضمن state قيمة الرمز المميز الفريد للجلسة المتعلق بمكافحة التزييف، بالإضافة إلى أي معلومات أخرى لازمة لاستعادة السياق عند عودة المستخدم إلى تطبيقك، مثل عنوان URL للبدء. (اطّلِع على مزيد من المعلومات على state.)
• nonce هي قيمة عشوائية ينشئها تطبيقك وتوفّر الحماية من إعادة التشغيل عند توفّرها.
• يمكن أن يكون login_hint عنوان البريد الإلكتروني للمستخدم أو سلسلة sub، التي تعادل رقم تعريف Google للمستخدم. إذا لم تدخِل login_hint وكان المستخدم مسجّلاً الدخول حاليًا، ستتضمّن شاشة الموافقة طلبًا للموافقة على إصدار عنوان البريد الإلكتروني للمستخدم في تطبيقك. (يمكنك الاطّلاع على مزيد من المعلومات على login_hint.)
• يمكنك استخدام المَعلمة hd لتحسين مسار "ربط OpenID" لمستخدمي نطاق معيّن مرتبط بمؤسسة على Google Workspace أو Cloud (يمكنك الاطّلاع على مزيد من المعلومات على hd).

في ما يلي مثال على معرّف موارد منتظم (URI) كامل لمصادقة OpenID Connect، مع إدراج فواصل أسطر والمسافات لتسهيل القراءة:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

3. تأكيد الرمز المميّز لحالة مكافحة التزوير

يتم إرسال الردّ إلى redirect_uri الذي حدّدته في الطلب. يتم عرض جميع الردود في سلسلة طلب البحث، كما هو موضّح أدناه:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

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

يوضح الرمز التالي تأكيد الرموز المميزة للجلسة التي أنشأتها في الخطوة 1:

// 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);
}

// 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.");
}

# 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:

قد يبدو الطلب الفعلي كما يلي:

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:

5. الحصول على معلومات المستخدم من الرمز المميز للمعرّف

الرمز المميّز للمعرّف هو رمز JWT (المعروف اختصارًا باسم JSON Web Token)، وهو كائن JSON بترميز Base64 موقّع بطريقة مشفّرة. من الضروري في العادة إثبات صحة الرمز المميّز للمعرّف قبل استخدامه، ولكن بما أنّك تتواصل مباشرةً مع Google عبر قناة HTTPS خالية من الوسيط وتستخدم سر العميل للمصادقة على Google، يمكنك أن تكون واثقًا من أنّ الرمز المميّز الذي تتلقّاه صادر من Google وهو صالح. إذا أرسل خادمك الرمز المميّز للمعرّف إلى مكوّنات أخرى من تطبيقك، من المهم للغاية أن تعمل المكونات الأخرى على التحقّق من الرمز المميّز قبل استخدامه.

وبما أنّ معظم مكتبات واجهة برمجة التطبيقات تجمع بين عملية التحقّق وفك ترميز القيم بترميز base64url وتحليل JSON داخله، من المحتمل أن ينتهي بك الأمر إلى التحقّق من صحة الرمز المميّز على أي حال عند الوصول إلى المطالبات في الرمز المميّز للمعرّف.

حمولة الرمز المميز للمعرّف

الرمز المميّز للمعرّف هو كائن JSON يحتوي على مجموعة من أزواج الاسم/القيمة. في ما يلي مثال تم تنسيقه لتسهيل القراءة:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

قد تحتوي الرموز المميّزة لمعرّف Google على الحقول التالية (المعروفة باسم المطالبات):

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

بعد الحصول على معلومات المستخدِم من الرمز المميّز للمعرّف، عليك الاستعلام عن قاعدة بيانات مستخدمي تطبيقك. إذا كان المستخدم موجودًا من قبل في قاعدة البيانات، يجب بدء جلسة تطبيق لذلك المستخدم إذا تم استيفاء جميع متطلبات تسجيل الدخول من خلال استجابة Google API.

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

مواضيع متقدمة

تشرح الأقسام التالية واجهة برمجة التطبيقات OAuth 2.0 الخاصة بـ Google بمزيد من التفصيل. هذه المعلومات مخصّصة للمطوّرين الذين لديهم متطلبات متقدمة متعلقة بالمصادقة والتفويض.

الوصول إلى Google APIs الأخرى

وتتمثّل إحدى مزايا استخدام OAuth 2.0 في المصادقة على إمكانية حصول تطبيقك على إذن لاستخدام Google APIs أخرى بالنيابة عن المستخدم (مثل YouTube أو Google Drive أو "تقويم Google" أو "جهات اتصال Google") في الوقت نفسه الذي تصادق فيه على المستخدم. لإجراء ذلك، يمكنك تضمين النطاقات الأخرى التي تحتاجها في طلب المصادقة الذي ترسله إلى Google. على سبيل المثال، لإضافة الفئة العمرية للمستخدم إلى طلب المصادقة، يجب ضبط معلَمة النطاق openid email https://www.googleapis.com/auth/profile.agerange.read. سيُطلب من المستخدم بشكل مناسب على شاشة الموافقة. يسمح لك رمز الدخول الذي تتلقّاه من Google بالوصول إلى جميع واجهات برمجة التطبيقات المرتبطة بنطاقات الوصول التي طلبتها وتم منحك إياها.

الرموز المميّزة لإعادة التحميل

في طلب الوصول إلى واجهة برمجة التطبيقات، يمكنك طلب الرمز المميّز لإعادة التحميل ليتم عرضه أثناء تبادل code. يوفّر الرمز المميّز لإعادة التحميل إمكانية الوصول المستمر إلى Google APIs بينما لا يكون المستخدم متاحًا في تطبيقك. لطلب الرمز المميّز لإعادة التحميل، أضِف ضبط المَعلمة access_type على offline في طلب المصادقة.

نقاط يجب أخذها في الاعتبار:

• احرِص على تخزين الرمز المميّز لإعادة التحميل بأمان ودائم، لأنّه لا يمكنك الحصول على الرمز المميّز لإعادة التحميل إلا في المرة الأولى التي تُجري فيها عملية تبادل الرموز.
• هناك حدود لعدد الرموز المميّزة لإعادة التحميل التي يتم إصدارها: حد أقصى لكل مجموعة عميل/مستخدم وحد آخر لكل مستخدم في جميع البرامج. إذا طلب تطبيقك عددًا كبيرًا جدًا من الرموز المميّزة لإعادة التحميل، قد يتخطّى هذه الحدود، وفي تلك الحالة ستتوقف الرموز المميّزة لإعادة التحميل القديمة عن العمل.

لمزيد من المعلومات، يمكنك الاطّلاع على إعادة تحميل رمز الدخول (الوصول بلا إنترنت).

طلب إعادة الموافقة

يمكنك أن تطلب من المستخدم إعادة تفويض تطبيقك من خلال ضبط معلَمة prompt على consent في طلب المصادقة. عند تضمين prompt=consent، يتم عرض شاشة الموافقة في كل مرة يطلب فيها تطبيقك إذنًا بنطاقات الوصول، حتى إذا سبق أن تم منح جميع النطاقات لمشروعك على Google APIs. لهذا السبب، لا تُدرِج prompt=consent إلا عند الضرورة.

لمزيد من المعلومات عن المَعلمة prompt، اطّلِع على prompt في جدول مَعلمات معرّف الموارد المنتظم (URI) للمصادقة.

معلمات معرّف الموارد المنتظم (URI) للمصادقة

يقدّم الجدول التالي أوصافًا أكثر اكتمالاً للمعلَمات التي تقبلها واجهة برمجة التطبيقات لمصادقة OAuth 2.0 من Google.

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

يجب التحقّق من صحة جميع الرموز المميّزة الخاصة بمعرّفات الهوية على خادمك، إلا إذا كنت تعرف أنّها مصدرها 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_endpoint. يتضمّن الردّ على userinfo معلومات عن المستخدم، على النحو الموضّح في OpenID Connect Standard Claims وقيمة البيانات الوصفية claims_supported في مستند "اقتراحات". قد يختار المستخدمون أو مؤسساتهم توفير حقول معيّنة أو حجزها، لذلك قد لا تحصل على معلومات عن كل حقل لنطاقات الوصول المصرَّح بها.

مستند "اقتراحات"

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

لتبسيط عمليات التنفيذ وزيادة المرونة، يتيح OpenID Connect استخدام "مستند الاستكشاف"، وهو مستند JSON يتم العثور عليه في موقع معروف يحتوي على أزواج المفتاح/القيمة التي تقدّم تفاصيل حول ضبط موفِّر خدمة OpenID Connect، بما في ذلك معرِّفات الموارد المنتظمة (URI) للتفويض والرمز المميّز والإبطال ومعلومات المستخدم ونقاط نهاية المفاتيح العامة. يمكن استرداد مستند Discovery لخدمة OpenID Connect من Google من:

https://accounts.google.com/.well-known/openid-configuration

لاستخدام خدمات OpenID Connect من Google، يجب ترميز معرف الموارد المنتظم (URI) لمستند Discovery (https://accounts.google.com/.well-known/openid-configuration) برمجيًا في تطبيقك. يجلب تطبيقك المستند ويطبّق قواعد التخزين المؤقت في الاستجابة، ثم يسترد منه معرّفات الموارد المنتظمة (URI) لنقطة النهاية حسب الحاجة. على سبيل المثال، لمصادقة مستخدم، سيسترد الرمز قيمة البيانات الوصفية authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth في المثال أدناه) باعتبارها معرّف الموارد المنتظم (URI) الأساسي لطلبات المصادقة التي يتم إرسالها إلى Google.

في ما يلي مثال على هذا المستند، فأسماء الحقول هي الأسماء المحدّدة في OpenID Connect Discovery 1.0 (يُرجى الرجوع إلى ذلك المستند لمعرفة معانيه). القيم توضيحية بحتة وقد تتغير، على الرغم من نسخها من نسخة حديثة من مستند Google Discovery الفعلي:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

قد يمكنك تجنب إرسال واستقبال عنوان URL لبروتوكول HTTP من خلال التخزين المؤقت للقيم من مستند Discovery. يتم استخدام رؤوس تخزين HTTP القياسية ويجب الالتزام بها.

مكتبات العملاء

تبسّط مكتبات العملاء التالية عملية استخدام OAuth 2.0 من خلال الدمج مع أُطر العمل الرائجة:

• مكتبة برامج 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 Connect

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