اتصال OpenID

يمكن استخدام واجهات برمجة التطبيقات 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 وتعيين عنوان 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. انقر فوق اسم بيانات الاعتماد الخاصة بك أو رمز القلم الرصاص ( create ). معرف العميل الخاص بك وسرك موجودان في أعلى الصفحة.

تعيين معرف الموارد المنتظم (URI) لإعادة التوجيه

يحدِّد معرّف الموارد المنتظم (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.

تقدّم أيضًا شاشة طلب موافقة المستخدم معلومات عن العلامة التجارية، مثل اسم المنتج والشعار وعنوان 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 في الطلب. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة المرح في Google OAuth 2.0، لذا لا يتضمّن معلومات العلامة التجارية التي سيتم ضبطها في API Console).

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

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

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

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

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

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

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

تدفق الخادم

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

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

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

يجب حماية أمان المستخدمين من خلال منع هجمات تزييف الطلبات. تتمثل الخطوة الأولى في إنشاء رمز مميز فريد للجلسة يحافظ على الحالة بين تطبيقك وعميل المستخدم. وبعد ذلك، تتم مطابقة هذا الرمز المميز للجلسة الفريدة مع استجابة المصادقة التي تعرضها خدمة تسجيل الدخول إلى Google OAuth للتحقق من أن المستخدم يقدم الطلب وليس مهاجمًا ضارًا. ويُشار لهذه الرموز المميزة غالبًا باسم الرموز المميزة لتزييف الطلبات من عدة مواقع (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 Cloud. (يمكنك الاطّلاع على مزيد من المعلومات على hd.)

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

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 ID على الحقول التالية (تُعرف باسم المطالبات):

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

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

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

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

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

الدخول إلى واجهات برمجة تطبيقات أخرى من Google

ومن بين مزايا استخدام OAuth 2.0 للمصادقة أن تطبيقك يمكن أن يحصل على إذن لاستخدام واجهات برمجة تطبيقات أخرى من Google نيابةً عن المستخدم (مثل 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 parameters في الطلب، تحقَّق من أنّ الرمز المميّز للمعرّف يتضمّن مطالبة 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:

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

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

لتبسيط عمليات التنفيذ وزيادة المرونة، يسمح "اتصال OpenID" باستخدام "مستند اكتشاف"، وهو مستند JSON الموجود في موقع معروف يحتوي على أزواج المفتاح/القيمة التي توفر تفاصيل حول تهيئة موفر اتصال OpenID، بما في ذلك معرفات الموارد المنتظمة (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"
  ]
}

قد تتمكّن من تجنُّب نقل البيانات ذهابًا وإيابًا عبر بروتوكول HTTP عن طريق تخزين القيم من مستند Discovery مؤقتًا. يتم استخدام رؤوس التخزين المؤقت لبروتوكول HTTP القياسية ويجب احترامها.

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

تجعل مكتبات البرامج التالية تنفيذ بروتوكول OAuth 2.0 أكثر سهولة من خلال الدمج مع أُطر العمل الشائعة:

• مكتبة عميل "Google APIs" للغة جافا
• مكتبة عميل "Google APIs" للغة Python
• مكتبة برامج "Google APIs" لنظام .NET
• مكتبة برامج "واجهات Google API" للغة Ruby
• مكتبة عميل "Google APIs" للغة PHP
• مكتبة OAuth 2.0 لمجموعة أدوات الويب من Google
• وحدات تحكّم Google في وحدات تحكّم Mac OAuth 2.0

امتثال OpenID Connect

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