تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

تعرض شاشة موافقة المستخدم أيضًا معلومات العلامة التجارية، مثل اسم منتجك وشعاره وعنوان URL للصفحة الرئيسية. يمكنك التحكّم في معلومات العلامة التجارية في .

يعرض مربّع حوار الموافقة التالي ما سيظهر للمستخدم عندما يتضمّن الطلب مجموعة من نطاقات OAuth 2.0 و Google Drive. (تم إنشاء مربّع الحوار العام هذا باستخدام مساحة Google OAuth 2.0، لذا لا يتضمّن معلومات العلامة التجارية التي سيتم ضبطها في .)

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

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

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

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

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

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

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

مسار الخادم

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

إنشاء رمز مميّز لحالة مكافحة التزوير
إرسال طلب مصادقة إلى Google
تأكيد الرمز المميّز لحالة مكافحة التزوير
استبدال code برمزَي الدخول والتعريف
الحصول على معلومات المستخدم من الرمز المميّز للمعرّف
مصادقة المستخدم

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

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

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

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

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

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. استبدال `code` برمز الوصول ورمز التعريف

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

الحقول
`code`	رمز التفويض الذي يتم إرجاعه من الطلب الأوّلي.
`client_id`	معرّف العميل الذي تحصل عليه من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
`client_secret`	سر العميل الذي تحصل عليه من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
`redirect_uri`	معرّف موارد منتظم (URI) معتمَد لإعادة التوجيه لـ `client_id` المحدّد في ، كما هو موضّح في ضبط معرّف موارد منتظم (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 المميّز للويب)، أي عنصر 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" على الحقول التالية (المعروفة باسم المطالبات):

المطالبة	تم الإدخال	الوصف
`aud`	دائمًا	شريحة الجمهور المستهدفة برمز التعريف هذا. يجب أن يكون أحد معرّفات العميل في OAuth 2.0 لتطبيقك.
`exp`	دائمًا	وقت انتهاء الصلاحية الذي لا يجب قبول الرمز المميّز للمعرّف بعده يتم تمثيله باستخدام وقت يونكس (ثواني صحيحة).
`iat`	دائمًا	وقت إصدار رمز التعريف يتم تمثيله بوقت نظام التشغيل يونكس (ثواني صحيحة).
`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 `client_id` مختلفًا من OAuth 2.0 ولكنهما يتشاركان مشروع Google APIs نفسه.
`email`		عنوان البريد الإلكتروني للمستخدِم لا يتم توفيره إلا إذا تضمّن طلبك النطاق `email` قد لا تكون قيمة هذه المطالبة فريدة لهذا الحساب وقد تتغيّر بمرور الوقت، لذا يجب عدم استخدام هذه القيمة كمعرّف أساسي للربط بسجلّ المستخدم. لا يمكنك أيضًا الاعتماد على نطاق المطالبة `email` لتحديد هوية مستخدمي Google Workspace أو مؤسسات Cloud، بل استخدِم المطالبة `hd` بدلاً من ذلك.
`email_verified`		صحيح إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم، وخطأ في غير ذلك.
`family_name`		الألقاب أو أسماء العائلة للمستخدم قد يتم تقديم هذه السمة عند توفّر مطالبة `name`.
`given_name`		الاسم الأول أو الأسماء الأولى للمستخدم قد يتم تقديم هذه السمة عند توفّر مطالبة `name`.
`hd`		النطاق المرتبط بمؤسسة المستخدم على Google Workspace أو Cloud لا يتم توفيرها إلا إذا كان المستخدم ينتمي إلى مؤسسة على Google Cloud. يجب وضع علامة في مربّع الاختيار بجانب هذه المطالبة عند تقييد الوصول إلى مورد معيّن على أعضاء نطاقات معيّنة فقط. يشير عدم توفّر هذه المطالبة إلى أنّ الحساب لا ينتمي إلى نطاق مستضاف على Google.
`locale`		لغة المستخدم، التي يتم تمثيلها بعلامة لغة BCP 47 قد يتم تقديم هذه السمة عند تقديم مطالبة `name`.
`name`		الاسم الكامل للمستخدم بتنسيق قابل للعرض يمكن تقديم هذه السمة في الحالات التالية: يتضمّن نطاق الطلب السلسلة "profile". يتم عرض الرمز المميّز للمعرّف من خلال إعادة تحميل الرمز المميّز عند توفّر `name` مطالبة، يمكنك استخدامها لتعديل سجلّات مستخدمي تطبيقك. يُرجى العِلم أنّه لا يمكن ضمان توفّر هذه المطالبة.
`nonce`		قيمة `nonce` التي يقدّمها تطبيقك في طلب المصادقة. عليك فرض الحماية من هجمات إعادة التشغيل من خلال التأكّد من عرضه مرة واحدة فقط.
`picture`		عنوان URL لصورة الملف الشخصي للمستخدم يمكن تقديم هذه السمة في الحالات التالية: يتضمّن نطاق الطلب السلسلة "profile". يتم عرض الرمز المميّز للمعرّف من خلال إعادة تحميل الرمز المميّز عند توفّر `picture` مطالبة، يمكنك استخدامها لتعديل سجلّات مستخدمي تطبيقك. يُرجى العِلم أنّه لا يمكن ضمان توفّر هذه المطالبة.
`profile`		عنوان URL لصفحة الملف الشخصي للمستخدم. يمكن تقديم هذه السمة في الحالات التالية: يتضمّن نطاق الطلب السلسلة "profile". يتم عرض الرمز المميّز للمعرّف من خلال إعادة تحميل الرمز المميّز عند توفّر `profile` مطالبة، يمكنك استخدامها لتعديل سجلّات مستخدمي تطبيقك. يُرجى العِلم أنّه لا يمكن ضمان توفّر هذه المطالبة.

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.

المَعلمة	مطلوب	الوصف
`client_id`	(مطلوب)	سلسلة معرّف العميل التي تحصل عليها من ، كما هو موضّح في الحصول على بيانات اعتماد OAuth 2.0.
`nonce`	(مطلوب)	قيمة عشوائية ينشئها تطبيقك لتفعيل ميزة "الحماية من إعادة التشغيل"
`response_type`	(مطلوب)	إذا كانت القيمة هي `code`، يتمّ إطلاق مسار رمز التفويض الأساسي، ما يتطلّب `POST` إلى نقطة نهاية الرمز المميّز للحصول على الرموز المميّزة. إذا كانت القيمة هي `token id_token` أو `id_token token`، يتمّ بدء عملية ضمنية، ما يتطلّب استخدام JavaScript في معرّف الموارد المنتظم لإعادة التوجيه لاسترداد الرموز المميّزة من معرّف URI `#fragment`.
`redirect_uri`	(مطلوب)	لتحديد الوجهة التي يتم إرسال الرد إليها. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم عمليات إعادة التوجيه المعتمَدة التي تحدّدها في (بما في ذلك مخطّط 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 أو مستندات واجهة برمجة تطبيقات Google التي تريد استخدامها.
`state`	(اختياري، ولكن ننصح به بشدة)	سلسلة مبهمة يتم إعادة توجيهها في البروتوكول، أي يتم عرضها كمَعلمة معرّف الموارد المنتظم (URI) في العملية الأساسية، وفي معرّف`#fragment` معرّف الموارد المنتظم (URI) في العملية الضمنية. يمكن أن يكون `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 فقط أو ضمن رؤوس الطلبات فقط. إذا كنت تخزّن الرموز المميّزة لتعريف المستخدمين على خادمك، يجب أيضًا تخزينها بأمان.

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

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

تأكَّد من أنّه تم توقيع رمز التعريف بشكل صحيح من قِبل جهة الإصدار. يتم توقيع الرموز المميّزة الصادرة عن Google باستخدام إحدى الشهادات المتوفّرة في معرّف الموارد المنتظم المحدّد في قيمةjwks_uri للبيانات الوصفية في مستند الاكتشاف.
تأكَّد من أنّ قيمة المطالبة iss في رمز التعريف تساوي https://accounts.google.com أو accounts.google.com.
تأكَّد من أنّ قيمة المطالبة aud في رمز التعريف تساوي الرقم التعريفي للعميل في تطبيقك.
تأكَّد من أنّ وقت انتهاء صلاحية الرمز المميّز للتعريف (المطالبة exp) لم يمرّ.
إذا حدّدت قيمة مَعلمة 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:

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

إذا كنت تريد تضمين عنوان البريد الإلكتروني للمستخدم، يمكنك تحديد قيمة إضافية لنطاق البريد الإلكتروني وهي email. لتحديد كل من profile وemail، يمكنك تضمين المَعلمة التالية في عنوان URL لطلب المصادقة:
```
scope=openid%20profile%20email
```
أضِف رمز الوصول إلى رأس التفويض وأرسِل طلب 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 من خلال الدمج مع منصّات تنمية التطبيقات الشائعة:

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

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

اتصال OpenID

إعداد OAuth 2.0

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

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

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

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

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

مسار الخادم

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

PHP

Java

Python

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

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

PHP

Java

Python

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. استبدال `code` برمز الوصول ورمز التعريف