اتصال OpenID

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

إعداد OAuth 2.0

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

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

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

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

  1. Go to the Credentials page.
  2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

ضبط عنوان URL لإعادة التوجيه

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

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

لقطة شاشة لصفحة الموافقة

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

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

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

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

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

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

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

تدفق الخادم

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

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

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

تتمثل الخطوة التالية في إنشاء طلب 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 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 معرِّف العميل الذي تحصل عليه من 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 على الحقول التالية (المعروفة باسم المطالبات):

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

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

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

الوصول إلى Google APIs الأخرى

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

لا تعتمد على عملية تحسين واجهة المستخدم هذه للتحكم في الأشخاص الذين يمكنهم الوصول إلى تطبيقك، إذ يمكن تعديل الطلبات من جهة العميل. احرص على validate من أنّ الرمز المميّز للمعرّف الذي تم عرضه يتضمّن قيمة مطالبة 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 في الطلب، تأكَّد من أنّ الرمز المميّز للمعرّف يتضمّن مطالبة 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) لمستند 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"
  ]
}

قد يمكنك تجنب إرسال واستقبال عنوان URL لبروتوكول HTTP من خلال التخزين المؤقت للقيم من مستند Discovery. يتم استخدام رؤوس تخزين HTTP القياسية ويجب الالتزام بها.

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

تبسّط مكتبات العملاء التالية عملية استخدام OAuth 2.0 من خلال الدمج مع أُطر العمل الرائجة:

الامتثال لـ OpenID Connect

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