توضّح هذه الصفحة كيفية تنفيذ Google لمواصفات OpenID Connect كموفّر خدمة، كما تقدّم المرجع الفني لنقاط نهاية OIDC من Google. تحدّد مواصفات OpenID Connect (OIDC) Core 1.0 البروتوكول الخاص بمصادقة المستخدمين والحصول على معلومات الهوية.
لا يهدف هذا المرجع إلى تقديم تعليمات مفصّلة حول كيفية تنفيذ OIDC، وللحصول على تفاصيل التنفيذ، يُرجى الاطّلاع على دليل اتصال OpenID.
مستند الاستكشاف
يحتوي مستند الاستكشاف على بيانات وصفية حول إعدادات OpenID Connect من Google، كما هو محدّد في مواصفات OpenID Connect Discovery 1.0.
عنوان URL: https://accounts.google.com/.well-known/openid-configuration
طريقة الطلب المتوافقة: GET
نص الاستجابة
يتم عرض حقول الاستجابة في عنصر JSON في نص استجابة HTTP لطلب GET الذي أرسله الطالب إلى https://accounts.google.com/.well-known/openid-configuration.
| الحقل | النوع | الوصف |
|---|---|---|
issuer |
string |
معرّف جهة الإصدار عنوان URL حساس لحالة الأحرف ويستخدم المخطط https. القيمة الحديثة هي https://accounts.google.com، ولكن يتم عرض accounts.google.com أيضًا في عمليات التنفيذ القديمة. |
authorization_endpoint |
string |
عنوان URL لنقطة نهاية التفويض. |
device_authorization_endpoint |
string |
عنوان URL لنقطة نهاية تفويض الجهاز. |
token_endpoint |
string |
تمثّل هذه السمة عنوان URL لنقطة نهاية الرمز المميز. |
userinfo_endpoint |
string |
عنوان URL لنقطة نهاية UserInfo |
revocation_endpoint |
string |
تمثّل هذه السمة عنوان URL لنقطة نهاية الإبطال. |
jwks_uri |
string |
عنوان URL لمستند مجموعة مفاتيح الويب JSON (JWKS). |
response_types_supported |
array |
قائمة بقيم response_type المسموح بها |
response_modes_supported |
array |
قائمة بقيم response_mode المسموح بها |
authorization_response_iss_parameter_supported |
boolean |
قيمة منطقية تشير إلى إمكانية استخدام RFC 9207. |
subject_types_supported |
array |
قائمة بأنواع معرّفات المواضيع المتوافقة. |
id_token_signing_alg_values_supported |
array |
قائمة بالخوارزميات المتوافقة لتوقيع رمز التعريف. |
scopes_supported |
array |
قائمة بقِيَم النطاق المسموح بها |
claims_supported |
array |
قائمة بالمطالبات المتوافقة |
token_endpoint_auth_methods_supported |
array |
قائمة بطُرق المصادقة المتوافقة مع نقطة نهاية الرمز المميز. |
code_challenge_methods_supported |
array |
قائمة بطُرق تحدّي الرمز المتوافقة مع PKCE |
grant_types_supported |
array |
قائمة بأنواع منح الإذن باستخدام OAuth 2.0 المتوافقة. |
الرمز المميّز لبطاقة التعريف (المطالبات)
قيمة id_token التي يتم عرضها في الردود هي رمز JSON المميّز للويب (JWT) موقّع رقميًا، ويجب التحقّق منه باستخدام مواد التشفير التي يتم الحصول عليها من jwks_uri الواردة في مستند Discovery. يوضّح الجدول التالي محتوى حمولة الرمز المميّز للمعرّف الذي تم فك ترميزه.
| المطالبة | النوع | الوصف |
|---|---|---|
iss |
string |
مطلوبة. معرّف الجهة المصدرة للردّ عادةً ما يتم عرض https://accounts.google.com، ولكن يتم عرض accounts.google.com أيضًا في عمليات التنفيذ القديمة. |
sub |
string |
مطلوبة. معرّف للمستخدم، وهو معرّف فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. يمكن أن يتضمّن حساب Google عناوين بريد إلكتروني متعدّدة في أوقات مختلفة، ولكن لا يتم تغيير القيمة sub أبدًا. استخدِم sub داخل تطبيقك كمفتاح المعرّف الفريد للمستخدم. الحد الأقصى للطول هو 255 حرفًا من أحرف ASCII مع مراعاة حالة الأحرف. |
azp |
string |
معرّف العميل الخاص مقدّم العرض المفوّض، والذي تم الحصول عليه من وحدة تحكّم Google Cloud لا تكون هذه المطالبة مطلوبة إلا عندما لا يكون الطرف الذي يطلب رمز التعريف المميز هو نفسه الجمهور المستهدف لرمز التعريف المميز. |
aud |
string |
مطلوبة. الجمهور المستهدَف من خلال رمز التعريف المميز. هذا هو معرّف العميل لتطبيقك، ويمكنك الحصول عليه من وحدة تحكّم Google Cloud. |
iat |
integer |
مطلوبة. الوقت الذي تم فيه إصدار رمز التعريف يتم تمثيله في وقت حقبة Unix (ثوانٍ صحيحة). |
exp |
integer |
مطلوبة. وقت انتهاء الصلاحية الذي يجب عدم قبول الرمز المميّز للمعرّف بعده أو عنده يتم تمثيله في وقت حقبة Unix (ثوانٍ صحيحة). |
nonce |
string |
قيمة nonce التي يقدّمها تطبيقك في طلب المصادقة يجب الحماية من هجمات إعادة الإرسال من خلال عرض هذه القيمة مرة واحدة فقط. |
auth_time |
integer |
الوقت الذي تمت فيه مصادقة المستخدم، وهو رقم JSON يمثّل عدد الثواني التي انقضت منذ بداية حقبة يونكس (1 يناير 1970، الساعة 00:00:00 بالتوقيت العالمي المتفق عليه). يتم توفيرها عند تضمين مطالبة auth_time في المَعلمة claims لطلب المصادقة. |
at_hash |
string |
تجزئة رمز الدخول توفير عملية التحقّق من أنّ رمز الدخول مرتبط برمز التعريف إذا تم إصدار رمز التعريف المميّز مع القيمة access_token في مسار الخادم، يتم دائمًا تضمين هذه المطالبة. |
email |
string |
عنوان البريد الإلكتروني للمستخدِم يتم توفير هذا الحقل فقط إذا تضمّن طلبك النطاق email. قد لا تكون قيمة هذا الادعاء فريدة لهذا الحساب وقد تتغير بمرور الوقت، لذا يجب عدم استخدام هذه القيمة كمعرّف أساسي للربط بسجلّ المستخدم. لا يمكنك أيضًا الاعتماد على نطاق مطالبة email لتحديد مستخدمي مؤسسات Google Workspace أو Cloud، بل استخدِم مطالبة hd بدلاً من ذلك. تحذير: لا تستخدِم عنوان البريد الإلكتروني كمعرّف لأنّه يمكن أن يتضمّن حساب Google عناوين بريد إلكتروني متعددة في أوقات مختلفة. استخدِم دائمًا الحقل sub كمعرّف للمستخدم. |
email_verified |
boolean |
تكون القيمة "صحيح" إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم، و"خطأ" في الحالات الأخرى. |
name |
string |
الاسم الكامل للمستخدم، بتنسيق قابل للعرض قد يتم توفيرها عندما يتضمّن نطاق الطلب السلسلة profile أو عندما يتم عرض الرمز المميز لتعريف الهوية من عملية إعادة تحميل الرمز المميز. |
picture |
string |
تمثّل هذه السمة عنوان URL لصورة الملف الشخصي للمستخدم. قد يتم توفيرها عندما يتضمّن نطاق الطلب السلسلة profile أو عندما يتم عرض الرمز المميز لتعريف الهوية من عملية إعادة تحميل الرمز المميز. |
given_name |
string |
الاسم الأول للمستخدم. يمكن تقديم هذه السمة عند توفّر مطالبة name. |
family_name |
string |
اسم العائلة للمستخدم. يمكن تقديم هذه السمة عند توفّر مطالبة name. |
hd |
string |
النطاق المرتبط بمؤسسة Google Workspace أو Cloud الخاصة بالمستخدم يتم توفيرها فقط إذا كان المستخدم ينتمي إلى مؤسسة Google Cloud. يجب التحقّق من هذا الادعاء عند حصر الوصول إلى أحد الموارد على أعضاء نطاقات معيّنة فقط. يشير عدم توفّر هذا الادعاء إلى أنّ الحساب لا ينتمي إلى نطاق مستضاف على Google. |
نقطة نهاية التفويض
يتم استخدام نقطة نهاية التفويض لمصادقة المستخدم والحصول على رمز تفويض أو رموز مميزة.
عنوان URL: https://accounts.google.com/o/oauth2/v2/auth
طرق الطلب المتوافقة: GET وPOST
مَعلمات الطلب
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
client_id |
string |
مطلوب | سلسلة معرّف العميل التي تحصل عليها من وحدة تحكّم Google Cloud |
nonce |
string |
اختياري | قيمة عشوائية ينشئها تطبيقك وتتيح الحماية من إعادة الإرسال. مطلوب فقط عند طلب رمز مميّز للمعرّف (عندما يتضمّن response_type id_token). |
response_type |
string |
مطلوب | تحدّد هذه السمة مسار الاستخدام. إذا كانت القيمة code، يتم بدء مسار رمز التفويض، ما يتطلّب إرسال POST إلى نقطة نهاية الرمز المميز للحصول على الرموز المميزة. إذا كانت القيمة token أو id_token أو token id_token أو id_token token، يتم تشغيل تدفق ضمني، ما يتطلّب استخدام JavaScript في معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه لاسترداد الرموز المميزة من جزء معرّف الموارد المنتظم (URI). ننصح بشدة بعدم استخدام token بأي شكل من الأشكال لأنّه يعرّض رموز الدخول المميزة في عنوان URL، وهذه القيمة محظورة في OAuth 2.1. |
response_mode |
string |
اختياري | تحدّد هذه السمة طريقة تسليم "رد التفويض". إذا كانت قيمة response_type هي code، تكون القيمة التلقائية هي query. بالنسبة إلى أنواع الاستجابات الأخرى، يكون الإعداد التلقائي هو fragment. القيم المسموح بها: query وfragment وform_post. |
redirect_uri |
string |
مطلوب | تحدّد هذه السمة المكان الذي يتم إرسال الردّ إليه. يجب أن تتطابق قيمة هذه المَعلمة تمامًا مع إحدى قيم إعادة التوجيه المسموح بها التي تحدّدها في وحدة تحكّم Google Cloud (بما في ذلك نظام HTTP أو HTTPS، وحالة الأحرف، وعلامة "/" اللاحقة، إن وُجدت). يجب أن تتّبع معرّفات الموارد المنتظمة (URI) لإعادة التوجيه ومصادر JavaScript المسموح بها قواعد التحقّق الموضّحة في مستند التحقّق من صحة معرّف الموارد المنتظم (URI) في OAuth 2.0. |
scope |
string |
مطلوب | قائمة غير مرتبة بالنطاقات، مع الفصل بينها بمسافات يجب أن تتضمّن القائمة القيمة openid ثم القيمة profile أو القيمة email أو كلتيهما. يمكنك أيضًا تضمين نطاقات غير OIDC. في حال توفُّر قيمة النطاق profile، قد يتضمّن رمز التعريف (ولكن ليس مضمونًا) مطالبات profile التلقائية للمستخدم. في حال توفُّر قيمة النطاق email، يتضمّن الرمز المميّز لتعريف الهوية المطالبات email وemail_verified. لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات OAuth 2.0. |
state |
string |
خيار ننصح به | سلسلة مبهمة يتم إرسالها في البروتوكول، أي يتم عرضها كمعلَمة URI في مسار رمز التفويض، وفي جزء URI في التدفّق الضمني. يمكن أن يكون state مفيدًا في ربط الطلبات بالردود. بما أنّه يمكن تخمين redirect_uri، يمكن أن يؤدي استخدام قيمة state إلى زيادة ضمان أنّ الاتصال الوارد هو نتيجة لطلب مصادقة بدأه تطبيقك، ما يوفّر الحماية من الهجمات، مثل تزوير الطلبات على مستوى المواقع الإلكترونية. |
access_type |
string |
اختياري | القيمتان المسموح بإدراجهما هما offline وonline. إذا كان تطبيقك بحاجة إلى إعادة تحميل رموز الدخول عندما لا يكون المستخدم متواجدًا على المتصفّح، استخدِم offline. هذه القيمة مطلوبة لعرض رمز مميز لإعادة التحميل. |
hd |
string |
اختياري | تبسيط عملية تسجيل الدخول إلى الحسابات التي تملكها مؤسسة Google Cloud من خلال تضمين نطاق مؤسسة Google Cloud (مثل mycollege.edu)، يمكنك الإشارة إلى أنّه يجب تحسين واجهة مستخدم اختيار الحساب للحسابات في هذا النطاق. لتحسين الأداء لحسابات المؤسسات على Google Cloud بشكل عام بدلاً من نطاق مؤسسة واحد على Google Cloud فقط، اضبط القيمة على علامة نجمة (*): hd=*. |
login_hint |
string |
اختياري | عندما يعرف تطبيقك المستخدم الذي يحاول مصادقته، يمكنه تقديم هذه المَعلمة كتلميح إلى خادم المصادقة. يؤدي تمرير هذه الإشارة إلى إيقاف أداة اختيار الحساب وتعبئة مربّع البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو اختيار الجلسة المناسبة، ما يساعدك في تجنُّب المشاكل التي تحدث إذا سجّل تطبيقك الدخول إلى حساب المستخدم غير الصحيح. يمكن أن تكون القيمة إما عنوان بريد إلكتروني أو السلسلة sub، وهي تعادل معرّف المستخدم على Google. |
prompt |
string |
اختياري | قائمة مفصولة بمسافات تتضمّن قيم السلسلة التي تحدّد ما إذا كان خادم التفويض يطلب من المستخدم إعادة المصادقة والموافقة. القيم المحتملة: none (بدون واجهة مستخدم)، consent (طلب الموافقة)، select_account (طلب اختيار حساب). |
hl |
string |
اختياري | علامة لغة BCP 47 تُستخدَم لتحديد لغة العرض لشاشات تسجيل الدخول واختيار الحساب والموافقة. ننصح بعدم استخدام هذه المَعلمة، لأنّ إعدادات المتصفّح والإعدادات المفضّلة في حساب Google تشكّل عادةً مؤشرات أفضل للغة المفضّلة لدى المستخدم. |
include_granted_scopes |
boolean |
اختياري | في حال توفير هذه المَعلمة بالقيمة true، وتم منح طلب التفويض، سيتضمّن التفويض أي تفويضات سابقة تم منحها لمجموعة المستخدم/التطبيق هذه لنطاقات أخرى. راجِع التفويض التزايدي. |
claims |
object |
اختياري | تُستخدَم مَعلمة المطالبات لتحديد حقل اختياري واحد أو أكثر لتضمينه في استجابة UserInfo أو رمز التعريف. لطلب auth_time، استخدِم claims={\"id_token\":{\"auth_time\":{\"essential\":true}}}. |
مَعلمات الردّ
يتم تسليم استجابة التفويض إلى معرّف الموارد المنتظم لإعادة التوجيه الخاص بالعميل (redirect_uri) باستخدام عملية إعادة توجيه GET عبر HTTP. يتم إلحاق مَعلمات الرد بعنوان URI لإعادة التوجيه في سلسلة طلب البحث أو جزء من عنوان URL، وذلك استنادًا إلى response_type وresponse_mode.
| المَعلمة | النوع | الوصف |
|---|---|---|
iss |
string |
معرّف جهة الإصدار وفقًا RFC 9207، يتم دائمًا عرض هذه المَعلمة وضبطها على https://accounts.google.com. |
code |
string |
رمز التفويض الذي يمكن استبداله برمز دخول ورمز تعريف |
state |
string |
القيمة نفسها التي تمّ استخدامها في المَعلمة state في الطلب |
id_token |
string |
رمز JSON المميّز للويب (JWT) يحتوي على معلومات الهوية الخاصة بالمستخدم |
access_token |
string |
رمز الدخول الذي يمكن إرساله إلى إحدى واجهات Google API |
token_type |
string |
تمثّل هذه السمة نوع الرمز المميّز الذي يتم عرضه. Bearer دائمًا |
expires_in |
integer |
تمثّل هذه السمة مدة صلاحية رمز الدخول بالثواني، وذلك بالنسبة إلى وقت إصدار الرمز. |
scope |
string |
نطاقات الوصول التي يمنحها code أو access_token معبَّر عنها كقائمة من السلاسل المفصولة بمسافات والمراعية لحالة الأحرف |
error |
string |
رمز خطأ في حال تعذّر تنفيذ الطلب |
error_description |
string |
وصف للخطأ في حال تعذّر تنفيذ الطلب |
الردود التي تتضمّن أخطاء
بالنسبة إلى نقطة نهاية التفويض، يتم إرجاع الأخطاء إلى redirect_uri العميل كمعلَمات في سلسلة طلب البحث أو جزء من عنوان URL، أو يتم عرضها للمستخدم كصفحة خطأ تستضيفها Google.
الأخطاء التي تمت إعادة توجيهها
قد يتم عرض رموز الخطأ التالية في redirect_uri:
| خطأ | الوصف |
|---|---|
access_denied |
رفض المستخدم أو خادم التفويض الطلب. |
invalid_request |
يفتقر الطلب إلى معلَمة مطلوبة، أو يتضمّن قيمة معلَمة غير صالحة، أو يتضمّن معلَمة أكثر من مرة، أو يكون مكتوبًا بشكلٍ غير صحيح. |
unauthorized_client |
العميل غير مُصرَّح له بطلب رمز تفويض باستخدام هذه الطريقة. |
unsupported_response_type |
لا يتيح خادم التفويض الحصول على رمز تفويض باستخدام هذه الطريقة. |
invalid_scope |
النطاق المطلوب غير صالح أو غير معروف أو تمت صياغته بشكل غير صحيح. |
الأخطاء التي تظهر للمستخدم
في بعض الحالات، مثل عندما يكون client_id أو redirect_uri غير صالحَين، لا يمكن لخادم التفويض إعادة توجيه المستخدم بأمان إلى تطبيقك.
في هذه الحالات، يتم عرض صفحة خطأ مباشرةً للمستخدم.
| خطأ | الوصف |
|---|---|
admin_policy_enforced |
لا يمكن لحساب Google منح الإذن بواحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف حسابات Google Workspace. راجِع مقالة مساعدة مشرف Google Workspace لمزيد من المعلومات حول كيفية حظر مشرف حسابات Google Workspace للوصول إلى أن يتم منح معرّف عميل OAuth إذن الوصول بشكل صريح. |
disallowed_useragent |
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن لا تسمح به سياسات OAuth 2.0 من Google. |
org_internal |
معرّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من الوصول إلى حسابات Google في مؤسسة Google Cloud معيّنة. |
deleted_client |
تم حذف عميل OAuth المستخدَم لتقديم الطلب. يمكن أن تتم عملية الحذف يدويًا أو تلقائيًا في حالة العملاء غير النشطين. |
invalid_grant |
المَعلمة code_challenge غير صالحة أو غير متوفّرة عند استخدام PKCE. عند إعادة تحميل رمز الدخول أو استخدام التفويض التدريجي، قد تكون صلاحية الرمز قد انتهت أو تم إبطاله أو حذف حساب المستخدم أو إيقافه. |
redirect_uri_mismatch |
لا يتطابق redirect_uri الذي تم تمريره في الطلب مع معرّف الموارد المنتظم (URI) لإعادة التوجيه المصرّح به لمعرّف العميل. راجِع معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه في Google Cloud Console. قد يحدث هذا الخطأ أيضًا إذا كان الطلب يستخدم مسار OAuth المتوقّف نهائيًا خارج النطاق. |
invalid_client |
لم يتم منح الإذن لهذا العميل بالمصدر الذي تم إرسال الطلب منه، أو أنّ إعدادات العميل غير صحيحة، أو أنّ سر عميل OAuth غير صحيح. |
origin_mismatch |
لا يتطابق المخطط أو النطاق أو المنفذ أو جميعها في JavaScript الذي ينشئ طلب التفويض مع معرّف الموارد المنتظم (URI) لمصدر JavaScript المسموح به والمُسجّل لمعرّف عميل OAuth. راجِع مصادر JavaScript المعتمدة في وحدة تحكّم Google Cloud. |
invalid_request |
حدث خطأ في الطلب. قد يرجع ذلك إلى طلب غير صالح أو مَعلمات مطلوبة غير متوفّرة أو استخدام طريقة لمنح الإذن لا تسمح بها Google. |
نقطة نهاية الرمز المميز
يتم استخدام نقطة نهاية الرمز المميز لتبديل رمز التفويض برمز دخول ورمز تعريف.
عنوان URL: https://oauth2.googleapis.com/token
طريقة الطلب المتوافقة: POST
مَعلمات الطلب (منح رمز التفويض)
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
code |
string |
مطلوب | رمز التفويض الذي تم تلقّيه من نقطة نهاية التفويض |
client_id |
string |
مطلوب | معرّف العميل لتطبيقك، والذي يتم الحصول عليه من وحدة تحكّم Google Cloud |
client_secret |
string |
مطلوب | سر العميل لتطبيقك، الذي تم الحصول عليه من وحدة تحكّم Google Cloud |
redirect_uri |
string |
مطلوب | معرّف الموارد المنتظم (URI) لإعادة التوجيه المستخدَم في طلب التفويض الأوّلي. يجب أن تتّبع معرّفات الموارد المنتظمة (URI) لإعادة التوجيه ومصادر JavaScript المسموح بها قواعد التحقّق الموضّحة في مستند التحقّق من صحة معرّف الموارد المنتظم (URI) في OAuth 2.0. |
grant_type |
string |
مطلوب | يجب ضبط الحقل على authorization_code. |
مَعلمات الطلب (عملية ربط الجهاز)
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
client_id |
string |
مطلوب | معرّف العميل لتطبيقك، والذي يتم الحصول عليه من وحدة تحكّم Google Cloud |
client_secret |
string |
مطلوب | سر العميل لتطبيقك، الذي تم الحصول عليه من وحدة تحكّم Google Cloud |
device_code |
string |
مطلوب | device_code التي تعرضها نقطة نهاية تفويض الجهاز |
grant_type |
string |
مطلوب | يجب ضبط الحقل على urn:ietf:params:oauth:grant-type:device_code. |
مَعلمات الطلب (إعادة تحميل رمز الدخول)
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
client_id |
string |
مطلوب | معرّف العميل لتطبيقك، والذي يتم الحصول عليه من وحدة تحكّم Google Cloud |
client_secret |
string |
مطلوب | سر العميل لتطبيقك، الذي تم الحصول عليه من وحدة تحكّم Google Cloud |
grant_type |
string |
مطلوب | يجب ضبطها على refresh_token كما هو محدّد في مواصفات اتصال OpenID ورموز التحديث. |
refresh_token |
string |
مطلوب | الرمز المميز لإعادة التحميل الذي تم إرجاعه من عملية تبادل رمز التفويض |
scope |
string |
اختياري | قائمة بالنطاقات المطلوبة للرمز المميز الجديد للوصول، مع الفصل بينها بمسافات يجب أن تكون النطاقات المطلوبة مجموعة فرعية من النطاقات التي تم منحها في طلب التفويض الأصلي. |
نص الاستجابة
يتم عرض حقول الاستجابة في عنصر JSON في نص استجابة HTTP لطلب POST الذي أرسله الطالب إلى https://oauth2.googleapis.com/token.
| الحقل | النوع | الوصف |
|---|---|---|
access_token |
string |
رمز الدخول الذي يمكن إرساله إلى إحدى واجهات Google API |
expires_in |
integer |
تعرض هذه السمة مدة صلاحية رمز الدخول بالثواني، مقارنةً بوقت إصدار الرمز المميز. |
id_token |
string |
رمز JSON المميّز للويب (JWT) يحتوي على معلومات الهوية الخاصة بالمستخدم يتم عرض هذا الرمز المميز أثناء عملية تبديل رمز التفويض الأولي، ويمكن عرضه أيضًا أثناء طلب رمز التحديث المميز إذا تم منح النطاق openid. |
scope |
string |
نطاقات الوصول التي يمنحها access_token معبَّر عنها كقائمة من السلاسل الحساسة لحالة الأحرف والمفصولة بمسافات |
token_type |
string |
تمثّل هذه السمة نوع الرمز المميّز الذي يتم عرضه. Bearer دائمًا |
refresh_token |
string |
(اختياري) رمز مميّز يمكن استخدامه للحصول على رموز دخول جديدة. لا يتم عرض هذا الحقل إلا في عملية تبادل رمز التفويض الأولية إذا تم طلب access_type=offline. |
refresh_token_expires_in |
integer |
(اختياري) مدة الصلاحية المتبقية لرمز الدخول المميز في ثوانٍ لا يتم ضبط هذه القيمة إلا عندما يمنح المستخدم إذن الوصول المستند إلى الوقت. |
ردود الأخطاء
في حال تعذُّر تنفيذ الطلب، يعرض خادم التفويض عنصر JSON يتضمّن الحقول التالية:
| الحقل | النوع | الوصف |
|---|---|---|
error |
string |
رمز خطأ |
error_description |
string |
وصف للخطأ في حال تعذّر تنفيذ الطلب |
يوضّح الجدول التالي رموز الأخطاء المحتملة ورموز حالة HTTP المرتبطة بها:
| خطأ | رمز حالة HTTP | الوصف |
|---|---|---|
invalid_request |
400 |
لا يتضمّن الطلب مَعلمة مطلوبة أو يتضمّن قيمة مَعلمة غير صالحة أو تمت صياغته بشكل غير صحيح. |
invalid_client |
401 |
تعذّرت مصادقة العميل. على سبيل المثال، يكون client_id أو client_secret غير صالحَين، أو يكون نوع العميل غير صحيح. |
invalid_grant |
400 |
رمز التفويض أو رمز التحديث أو رمز الجهاز المقدَّم غير صالح أو انتهت صلاحيته أو تم إبطاله أو لا يتطابق مع معرّف الموارد المنتظم لإعادة التوجيه المستخدَم في طلب التفويض. |
unauthorized_client |
400 |
العميل الذي تمت مصادقته غير مسموح له باستخدام نوع منح الإذن هذا. |
unsupported_grant_type |
400 |
نوع منح التفويض غير متاح من قِبل خادم التفويض. |
invalid_scope |
400 |
النطاق المطلوب غير صالح أو غير معروف أو تمت صياغته بشكل غير صحيح. |
authorization_pending |
428 |
(تدفّق الجهاز) لم يكمل المستخدم بعد تدفّق التفويض. |
slow_down |
429 |
(Device Flow) يرسل الجهاز طلبات الاستقصاء بشكل متكرّر أكثر من اللازم. |
access_denied |
403 |
(سير عمل الجهاز) رفض المستخدم منح إذن الوصول إلى الجهاز. |
expired_token |
400 |
(عملية ربط الجهاز) انتهت صلاحية device_code. |
admin_policy_enforced |
400 |
لا يمكن للمستخدم منح الإذن بالنطاقات المطلوبة بسبب السياسات التي يفرضها مشرف حسابات Google Workspace. |
org_internal |
403 |
معرّف العميل هو جزء من مشروع يحدّ من الوصول إلى مؤسسة معيّنة على Google Cloud. |
نقطة نهاية تفويض الجهاز
يتم استخدام نقطة نهاية "تفويض الجهاز" في مسار OAuth 2.0 للأجهزة للحصول على رمز مستخدم وعنوان URL للتحقّق من الأجهزة التي تتضمّن إمكانات إدخال محدودة.
عنوان URL: https://oauth2.googleapis.com/device/code
طريقة الطلب المتوافقة: POST
مَعلمات الطلب
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
client_id |
string |
مطلوب | معرّف العميل لتطبيقك، والذي يتم الحصول عليه من وحدة تحكّم Google Cloud |
scope |
string |
مطلوب | قائمة مفصولة بمسافات تتضمّن النطاقات التي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. |
نص الاستجابة
الردّ هو عنصر JSON يحتوي على الحقول التالية:
| الحقل | النوع | الوصف |
|---|---|---|
device_code |
string |
قيمة تحدّدها Google بشكلٍ فريد للتعرّف على الجهاز الذي يشغّل التطبيق الذي يطلب الحصول على إذن. |
user_code |
string |
قيمة حساسة لحالة الأحرف تحدّد لـ Google النطاقات التي يطلب التطبيق الوصول إليها. ستطلب واجهة المستخدم من المستخدم إدخال هذه القيمة على جهاز منفصل يتضمّن إمكانات إدخال أكثر ثراءً. |
verification_url |
string |
عنوان URL يجب أن ينتقل إليه المستخدم على جهاز منفصل لإدخال user_code ومنح إذن الوصول إلى تطبيقك أو رفضه |
expires_in |
integer |
تمثّل هذه السمة المدة الزمنية بالثواني التي يكون فيها كل من device_code وuser_code صالحًا. |
interval |
integer |
تمثّل هذه السمة المدة الزمنية بالثواني التي يجب أن ينتظرها جهازك بين طلبات الاستطلاع. |
نقطة نهاية الإبطال
تسمح نقطة نهاية الإبطال لتطبيقك بإبطال رمز دخول أو رمز مميز لإعادة التحميل.
عنوان URL: https://oauth2.googleapis.com/revoke
طريقة الطلب المتوافقة: POST
مَعلمات الطلب
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
token |
string |
مطلوب | رمز الدخول المميز أو رمز إعادة التحميل الذي تريد إبطاله |
نص الاستجابة
في حال نجاح عملية الإبطال، تكون الاستجابة عبارة عن HTTP 200 OK فارغ. في حال تعذُّر الإبطال، يتم عرض استجابة خطأ في عنصر JSON.
| الحقل | النوع | الوصف |
|---|---|---|
error |
string |
رمز خطأ في حال تعذّر تنفيذ الطلب |
error_description |
string |
وصف للخطأ في حال تعذّر تنفيذ الطلب |
يوضّح الجدول التالي رموز الأخطاء المحتملة:
| خطأ | الوصف |
|---|---|
invalid_token |
انتهت صلاحية الرمز المميّز المقدَّم في الطلب أو تم إبطاله. |
invalid_request |
لا يتضمّن الطلب مَعلمة مطلوبة أو يتضمّن قيمة مَعلمة غير صالحة أو تمت صياغته بشكل غير صحيح. |
نقطة نهاية UserInfo
تعرض نقطة نهاية UserInfo معلومات الملف الشخصي للمستخدم الذي تمّت مصادقته.
عنوان URL: https://openidconnect.googleapis.com/v1/userinfo
طرق الطلب المتوافقة: GET وPOST
عناوين الطلبات
| العنوان | الوصف |
|---|---|
Authorization |
مطلوبة. يجب ضبط الحقل على Bearer: access_token. |
نص الاستجابة
يتم عرض حقول الاستجابة في عنصر JSON في نص استجابة HTTP لطلب GET أو POST الذي أرسله الطالب إلى https://openidconnect.googleapis.com/v1/userinfo.
| الحقل | النوع | الوصف |
|---|---|---|
sub |
string |
مطلوبة. معرّف للمستخدم، وهو معرّف فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. سلسلة حساسة لحالة الأحرف لا تتجاوز 255 حرفًا |
name |
string |
الاسم الكامل للمستخدم، بتنسيق قابل للعرض |
given_name |
string |
الاسم الأول للمستخدم. |
family_name |
string |
اسم العائلة للمستخدم. |
picture |
string |
تمثّل هذه السمة عنوان URL لصورة الملف الشخصي للمستخدم. |
email |
string |
عنوان البريد الإلكتروني للمستخدِم |
email_verified |
boolean |
تُستخدَم لتحديد ما إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم. |
hd |
string |
النطاق المستضاف المرتبط بمؤسسة Google Workspace أو Cloud الخاصة بالمستخدم |
نقطة نهاية Tokeninfo
نقطة النهاية tokeninfo هي عملية تنفيذ خاصة بـ Google تُستخدَم للتحقّق من صحة رمز مميز لأغراض تصحيح الأخطاء.
عنوان URL: https://oauth2.googleapis.com/tokeninfo
طرق الطلب المتوافقة: GET وPOST
مَعلمات الطلب
| المَعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
id_token |
string |
مطلوب | الرمز المميز لبطاقة التعريف المطلوب التحقّق من صحته. |
نص الاستجابة
يتم عرض حقول الاستجابة في عنصر JSON في نص استجابة HTTP لطلب GET أو POST الذي أرسله الطالب إلى https://oauth2.googleapis.com/tokeninfo.
| الحقل | النوع | الوصف |
|---|---|---|
iss |
string |
معرّف جهة الإصدار https://accounts.google.com دائمًا |
sub |
string |
معرّف للمستخدم، وهو معرّف فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. |
aud |
string |
الجمهور المستهدَف من خلال رمز التعريف المميز. هذا هو معرّف العميل لتطبيقك، ويمكنك الحصول عليه من وحدة تحكّم Google Cloud. |
iat |
integer |
الوقت الذي تم فيه إصدار رمز JWT يتم تمثيله على شكل عدد الثواني منذ 1970-01-01T0:0:0Z كما تم قياسه بالتوقيت العالمي المتفق عليه. |
exp |
integer |
تمثّل هذه السمة وقت انتهاء الصلاحية الذي يجب عدم قبول الرمز المميّز للمعرّف بعده للمعالجة. يتم تمثيله على شكل عدد الثواني منذ 1970-01-01T0:0:0Z كما تم قياسه بالتوقيت العالمي المتفق عليه. |
email |
string |
عنوان البريد الإلكتروني للمستخدِم |
email_verified |
string |
تُستخدَم لتحديد ما إذا تم إثبات ملكية عنوان البريد الإلكتروني للمستخدم. القيمة هي السلسلة "true" أو "false". |
access_type |
string |
نوع إذن الوصول المطلوب في طلب التفويض الأصلي |
azp |
string |
معرّف العميل الخاص مقدّم العرض المفوّض، والذي تم الحصول عليه من وحدة تحكّم Google Cloud |
scope |
string |
قائمة النطاقات الممنوحة للرمز المميز، مع الفصل بينها بمسافات |
alg |
string |
الخوارزمية المستخدَمة لتوقيع الرمز المميّز لتعريف الهوية |
kid |
string |
رقم تعريف المفتاح المستخدَم لتوقيع الرمز المميز لتعريف الهوية. |
typ |
string |
نوع الرمز المميّز. JWT دائمًا |