اتصال 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) الخاص بإعادة التوجيه

يحدِّد معرّف الموارد المنتظم لإعادة التوجيه الذي تحدّده في 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 Identity Services و مكتبات عملاء Google، والتي تتوفّر لمجموعة متنوعة من منصّات برامج التشغيل.

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

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

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

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

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

مسار الخادم

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

1. إنشاء رمز مميّز لحالة مكافحة التزوير
2. إرسال طلب مصادقة إلى Google
3. تأكيد الرمز المميّز لحالة مكافحة التزوير
4. استبدال 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

الخطوة التالية هي إنشاء طلب GET باستخدام بروتوكول HTTPS مع مَعلمات معرّف الموارد المنتظم (URI) المناسبة. يُرجى ملاحظة استخدام HTTPS بدلاً من HTTP في جميع خطوات هذه العملية، إذ يتم رفض اتصالات HTTP. يجب استرداد عنوان URI الأساسي من مستند الاكتشاف باستخدام قيمة البيانات الوصفية authorization_endpoint. تفترض المناقشة التالية أنّه معرّف الموارد المنتظم الأساسي هو 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" لمستخدمي نطاق معيّن مرتبط بمؤسسة 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 المميّز للويب)، أي عنصر 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، أو على الأقل قد تتمكّن من ملء العديد من الحقول التي تحتاج إليها مسبقًا في نموذج التسجيل. بالإضافة إلى المعلومات الواردة في رمز التعريف، يمكنك الحصول على معلومات إضافية عن الملف الشخصي للمستخدم في نقاط نهاية ملفه الشخصي.

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

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

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

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

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

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

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

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

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

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

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

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

تتطلّب عملية التحقّق من صحة رمز تعريف الهوية عدة خطوات:

1. تأكَّد من أنّه تم توقيع رمز التعريف بشكل صحيح من قِبل جهة الإصدار. يتم توقيع الرموز المميّزة الصادرة عن Google باستخدام إحدى الشهادات المتوفّرة في معرّف الموارد المنتظم المحدّد في قيمة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. بعد ذلك، يمكنك إلغاء الإشارة إلى عنوان URL https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. إذا كان توقيع الرمز المميّز صالحًا، ستكون الاستجابة هي حمولة JWT في شكل كائن JSON تم فك تشفيره.

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

بما أنّ Google لا تغيّر مفاتيح التشفير العامة إلا بشكل غير متكرّر، يمكنك تخزينها مؤقتًا باستخدام توجيهات التخزين المؤقت في استجابة HTTP، ويمكنك في معظم الحالات إجراء التحقّق المحلي بكفاءة أكبر بكثير من استخدام نقطة نهاية tokeninfo. تتطلّب عملية التحقّق هذه retrieving and parsing certificates، وإجراء طلبات التشفير المناسبة لفحص التوقيع. لحسن الحظ، تتوفّر مكتبات تم تصحيح أخطاءها جيدًا بعدة لغات مختلفة لتنفيذ ذلك (راجِع jwt.io).

الحصول على معلومات الملف الشخصي للمستخدم

للحصول على معلومات إضافية عن الملف الشخصي للمستخدم، يمكنك استخدام رمز الأمان للوصول (الذي يتلقّاه تطبيقك أثناء مسار المصادقة) ومعيار OpenID Connect:

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

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

   scope=openid%20profile%20email

2. أضِف رمز الوصول إلى رأس التفويض وأرسِل طلب GET بروتوكول HTTPS إلى نقطة نهاية userinfo، والتي يجب استرجاعها من مستند الاكتشاف باستخدام قيمة metadata ‏userinfo_endpoint. يتضمّن ردّ userinfo معلومات عن المستخدم، كما هو موضّح في OpenID Connect Standard Claims وقيمة البيانات الوصفية claims_supported لمستند Discovery. قد يختار المستخدمون أو مؤسساتهم تقديم حقول معيّنة أو حجبها، لذا قد لا تحصل على معلومات عن كل حقل ضمن نطاقات الوصول المعتمَدة.

مستند "الحملات أثناء التصفّح"

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

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

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

لاستخدام خدمات OpenID Connect من Google، عليك تضمين عنوان URL الخاص بملف التنقّل (https://accounts.google.com/.well-known/openid-configuration) في تطبيقك. يُجلب تطبيقك المستند ويطبّق قواعد التخزين المؤقت في الاستجابة، ثم يسترجع عناوين URL لنقاط النهاية منه حسب الحاجة. على سبيل المثال، لمصادقة مستخدم، سيسترجع الرمز المبرمَج قيمة البيانات الوصفية authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth في المثال أدناه) كمعرّف موارد منتظم أساسي لطلبات المصادقة التي يتم إرسالها إلى 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 من خلال تخزين القيم من مستند الاكتشاف في ذاكرة التخزين المؤقت. يتم استخدام عناوين التخزين المؤقت العادية في HTTP ويجب الالتزام بها.

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

تُسهِّل مكتبات العملاء التالية تنفيذ OAuth 2.0 من خلال الدمج مع منصّات تنمية التطبيقات الشائعة:

• مكتبة برامج Google APIs للغة Java
• مكتبة عملاء Google APIs للغة Python
• مكتبة عملاء Google APIs لنظام ‎ .NET
• مكتبة برامج Google APIs للغة Ruby
• مكتبة برامج Google APIs لتطبيقات PHP
• مكتبة OAuth 2.0 لمجموعة أدوات الويب من Google
• Google Toolbox for Mac OAuth 2.0 Controllers

الامتثال لمعيار OpenID Connect

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