اتصال OpenID

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

إعداد OAuth 2.0

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

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

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

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

أو اعرض معرف العميل وسر العميل من صفحة بيانات الاعتماد في API Console :

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

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

تحدّد معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه الذي تحدّده في 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 API الأخرى.

تقدّم أيضًا شاشة طلب موافقة المستخدم معلومات عن العلامة التجارية، مثل اسم منتجك وشعاره وعنوان 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 APIs. وتشمل الأمثلة خدمات Google Identity و مكتبات برامج Google المتوفّرة لمجموعة متنوعة من الأنظمة الأساسية.

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

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

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

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

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

مسار الخادم

تأكّد من إعداد تطبيقك على 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. يجب استرداد عنوان URL الأساسي من مستند أثناء التصفّح باستخدام قيمة البيانات الوصفية authorization_endpoint. تفترض المناقشة التالية أن معرف الموارد المنتظم (URI) الأساسي هو https://accounts.google.com/o/oauth2/v2/auth.

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

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

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

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

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

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

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

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

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

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

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

مطالبة تم الإدخال الوصف
aud دائمًا الجمهور المخصّص له هذا الرمز المميّز للمعرّف. ويجب أن يكون أحد معرّفات عملاء OAuth 2.0 لتطبيقك.
exp دائمًا وقت انتهاء الصلاحية الذي يجب بعده عدم قبول الرمز المميَّز للمعرّف. ويتم تمثيله بتوقيت يونكس (عدد صحيح صحيح).
iat دائمًا الوقت الذي تمّ فيه إصدار الرمز المميّز للمعرّف. ويتم تمثيله بوقت Unix (عدد صحيح صحيح).
iss دائمًا معرّف جهة الإصدار لجهة إصدار الرد. عليك دائمًا https://accounts.google.com أو accounts.google.com للرموز المميزة لرقم تعريف Google.
sub دائمًا معرّف المستخدم الفريد من بين جميع حسابات Google ولا يمكن إعادة استخدامه مطلقًا. يمكن أن يتضمّن حساب Google عدة عناوين بريد إلكتروني في أوقات مختلفة، ولكن لا يتم تغيير قيمة sub مطلقًا. يمكنك استخدام sub ضمن تطبيقك كمفتاح المعرّف الفريد للمستخدم. الحد الأقصى للطول هو 255 حرفًا حساسًا لحالة الأحرف (ASCII).
at_hash تجزئة رمز الدخول تحقّق من صحة ربط رمز الدخول بالرمز المميّز للهوية. إذا تم إصدار الرمز المميّز للمعرّف باستخدام access_token في مسار الخادم، يتم تضمين هذه المطالبة دائمًا. يمكن استخدام هذه المطالبة كآلية بديلة للحماية من تزوير الطلبات من مواقع إلكترونية مختلفة، ولكن إذا اتّبعت الخطوة 1 والخطوة 3، ليس من الضروري التحقّق من رمز الدخول.
azp client_id للمقدِّم المفوَّض. تكون هذه المطالبة مطلوبة فقط عندما يكون الطرف الذي يطلب الرمز المميّز للمعرّف مختلفًا عن جمهور الرمز المميّز للمعرّف. وقد تكون هذه هي الحالة في Google للتطبيقات المختلطة حيث يكون لتطبيق الويب وتطبيق Android OAuth 2.0 client_id مختلف ولكن يشتركان في مشروع Google APIs نفسه.
email عنوان البريد الإلكتروني للمستخدم. وقد لا تكون هذه القيمة فريدة لهذا المستخدم وغير مناسبة للاستخدام كمفتاح أساسي. لا يتم توفير هذه السمة إلا إذا كان نطاقك يتضمن قيمة النطاق email.
email_verified صحيح إذا تم التحقق من عنوان البريد الإلكتروني للمستخدم، أو كان خطأ.
family_name اسم المستخدم أو أسماء العائلة. يمكن تقديم هذه الشكوى عند تلقّي مطالبة بشأن name.
given_name اسم المستخدم أو الأسماء الأولى أو الأسماء الأولى. يمكن تقديم هذه الشكوى عند تلقّي مطالبة بشأن name.
hd النطاق المرتبط بمؤسسة Google Cloud للمستخدم. لا يتم تقديمه إلا إذا كان المستخدم ينتمي إلى مؤسسة Google Cloud.
locale لغة المستخدم وتمثلها علامة لغة BCP 47. يمكن تقديم هذه الشكوى في حال تقديم مطالبة بشأن name.
name الاسم الكامل للمستخدم في شكل قابل للعرض. وقد يتم توفير ما يلي عند:
  • تَضَمَّنْ مَدَى طَلَبِ الطَّلَبِ الْخَتَامَة &&;;profile;profile"
  • يتم عرض الرمز المميّز للمعرّف من عملية إعادة تحميل الرمز المميّز.

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

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

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

profile عنوان URL لصفحة الملف الشخصي للمستخدم. وقد يتم توفير ما يلي عند:
  • تَضَمَّنْ مَدَى طَلَبِ الطَّلَبِ الْخَتَامَة &&;;profile;profile"
  • يتم عرض الرمز المميّز للمعرّف من عملية إعادة تحميل الرمز المميّز.

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

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

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

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

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

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

الوصول إلى واجهات Google API الأخرى

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

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

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

الاعتبارات:

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

لمزيد من المعلومات، راجِع إعادة تحميل رمز الدخول (بلا إنترنت).

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

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

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

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

المعلمة مطلوبة الوصف
client_id (مطلوب) سلسلة معرّف العميل التي تحصل عليها من API Console Credentials page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
nonce (مطلوب) قيمة عشوائية تم إنشاؤها من خلال تطبيقك تمكّن الحماية من إعادة التشغيل.
response_type (مطلوب) إذا كانت القيمة هي code، شغِّل تدفق رمز التفويض الأساسي، والذي يتطلب من POST الحصول على نقطة نهاية الرمز المميز للحصول على الرموز المميزة. وإذا كانت القيمة هي token id_token أو id_token token، سيتم تشغيل تدفق ضمني، ما يتطلب استخدام JavaScript في معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه لاسترداد الرموز المميّزة من معرّف الموارد المنتظم (URI)#fragment.
redirect_uri (مطلوب) يحدِّد هذا الإعداد الوجهة التي يتم إرسال الرد إليها. ويجب أن تتطابق قيمة هذه المعلَمة تمامًا مع إحدى قيم إعادة التوجيه المصرّح بها التي حدّدتها في API ConsoleCredentials page (بما في ذلك نظام HTTP أو HTTPS، والحالة، واللاحقة &#39؛/&#39، إن وجدت).
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 أو مستندات واجهة برمجة التطبيقات من Google التي تريد استخدامها.

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

سلسلة غير واضحة يتم قطعها بشكل مستدير في البروتوكول، أي عرضها كمعلّمة معرف موارد منتظم (URI) في التدفق الأساسي، وفي معرّف الموارد المنتظم (URI) #fragment في المسار الضمني.

يمكن أن تكون السمة 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=*.

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

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

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

امتثال OpenID Connect

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