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

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

To enable your project's consent screen:

  1. Open the Consent Screen page in the Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Fill out the form and click Save.

يعرض مربّع حوار الموافقة التالي ما سيراه المستخدم عند توفّر مجموعة من نطاقات 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 حرفًا أو نحو ذلك تم إنشاؤها باستخدام مولد رقم عشوائي عالي الجودة. والأخرى هي تجزئة يتم إنشاؤها عن طريق التوقيع على بعض متغيرات حالة الجلسة باستخدام مفتاح يبقى سريًا في الخلفية.

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

لغة 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" للغة جافا لاستخدام هذا النموذج.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

لغة Python

عليك تنزيل مكتبة برامج Google APIs للغة Python لاستخدام هذا النموذج.

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

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

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

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

  • client_id، والتي تحصل عليها من API Console Credentials page .
  • response_type، الذي يجب أن يكون code في طلب تدفق رمز التفويض الأساسي. (يمكنك الاطّلاع على مزيد من المعلومات على response_type.)
  • scope، والذي يجب أن يكون openid email في الطلب الأساسي. (اقرأ المزيد على scope.)
  • يجب أن تكون redirect_uri نقطة نهاية HTTP على خادمك، والتي ستتلقى الاستجابة من Google. يجب أن تتطابق القيمة تطابقًا تامًا مع أحد معرّفات الموارد المنتظمة (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:

لغة 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" للغة جافا لاستخدام هذا النموذج.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

لغة Python

عليك تنزيل مكتبة برامج Google APIs للغة Python لاستخدام هذا النموذج.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. تبادل code لرمز الدخول ورمز التعريف

تتضمّن الاستجابة معلَمة code، وهي رمز تفويض يُستخدَم لمرة واحدة ويمكن أن يتبادله الخادم للحصول على رمز دخول ورمز مميز للمعرّف. ويجري الخادم عملية التبادل هذه من خلال إرسال طلب HTTPS POST. يتم إرسال الطلب POST إلى نقطة نهاية الرمز المميّز، التي يجب استردادها من مستند أثناء التصفّح باستخدام قيمة البيانات الوصفية token_endpoint. تفترض المناقشة التالية أن نقطة النهاية هي https://oauth2.googleapis.com/token. ويجب أن يتضمّن الطلب المَعلمات التالية في نص POST:

الحقول
code رمز التفويض الذي يتم عرضه من الطلب الأولي.
client_id رقم تعريف العميل الذي تحصل عليه من API Console Credentials page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
client_secret سرّ العميل الذي تحصل عليه من API Console Credentials page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
redirect_uri تمثل هذه السمة معرّف الموارد المنتظم (URI) المُعتمَد لإعادة التوجيه في client_id المحدّد في API Console Credentials page، كما هو موضّح في ضبط معرّف الموارد المنتظم (URI) لإعادة التوجيه.
grant_type يجب أن يحتوي هذا الحقل على قيمة authorization_code، على النحو المحدّد في مواصفات OAuth 2.0.

قد يبدو الطلب الفعلي على النحو التالي:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

تحتوي الاستجابة الناجحة لهذا الطلب على الحقول التالية في مصفوفة JSON:

الحقول
access_token رمز مميز يمكن إرساله إلى واجهة برمجة تطبيقات Google.
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 على الحقول التالية (تُعرف باسم المطالبات):

Claim تم الإدخال الوصف
aud دائمًا الجمهور الذي تم تخصيص الرمز المميّز له ويجب أن يكون واحدًا من معرّفات عميل OAuth 2.0 لتطبيقك.
exp دائمًا وقت انتهاء الصلاحية الذي يجب بعده عدم قبول الرمز المميز للمعرّف. ويتم تمثيلها بتوقيت يونكس (عدد صحيح من الثواني).
iat دائمًا وقت إصدار الرمز المميّز للمعرّف. يتم تمثيله بتوقيت يونكس (عدد صحيح بالثواني).
iss دائمًا معرّف جهة إصدار المصدِّر للاستجابة. https://accounts.google.com أو accounts.google.com دائمًا للرموز المميّزة لرقم تعريف Google.
sub دائمًا معرّف المستخدم، وهو فريد بين جميع حسابات Google ولا يمكن إعادة استخدامه مطلقًا. يمكن أن يكون لحساب Google عدة عناوين بريد إلكتروني في أوقات مختلفة، ولكن لا يتم تغيير قيمة sub مطلقًا. استخدِم sub داخل التطبيق كمفتاح المعرّف الفريد للمستخدم. يجب ألا يزيد عدد أحرف ASCII عن 255 حرفًا كحد أقصى.
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 الاسم الكامل للمستخدم في نموذج قابل للعرض. يمكن تقديم هذه الرسالة عندما:
  • تضمّن نطاق الطلب السلسلة "الملف الشخصي"
  • يتم عرض الرمز المميّز للرقم التعريفي بعد إعادة تحميل الرمز المميّز.

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

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

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

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

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

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.

المعلمة مطلوب الوصف
client_id (مطلوب) سلسلة معرّف العميل التي حصلت عليها من API Console Credentials page، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
nonce (مطلوب) قيمة عشوائية ينشئها تطبيقك لتمكين الحماية من إعادة التشغيل.
response_type (مطلوب) إذا كانت القيمة هي code، يتم تشغيل تدفق رمز التفويض الأساسي، ما يتطلّب POST إلى نقطة نهاية الرمز المميز للحصول على الرموز المميزة. إذا كانت القيمة هي token id_token أو id_token token، يتم تشغيل تدفق ضمني، ما يتطلب استخدام JavaScript في معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه لاسترداد الرموز المميّزة من معرّف الموارد المنتظم (URI) #fragmentلمعرّف الموارد المنتظم (URI).
redirect_uri (مطلوب) تحدّد هذه السمة المكان الذي يتم إرسال الرد إليه. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم إعادة التوجيه المُصرَّح بها التي تم ضبطها في Credentials page API Console(بما في ذلك مخطّط HTTP أو HTTPS وحالة الأحرف واللاحقة "/").
scope (مطلوب)

يجب أن تبدأ معلمة النطاق بالقيمة openid ومن ثم تتضمّن قيمة profile أو قيمة email أو كلتيهما.

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

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

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

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

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

سلسلة معتمة يتم تحويلها بشكل دائري في البروتوكول، أي أنه يتم عرضها كمعلّمة URI في التدفق الأساسي وفي معرّف 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. في حال تحديد قيمة 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 أكثر سهولة من خلال الدمج مع أُطر العمل الشائعة:

امتثال OpenID Connect

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