اتصال OpenID

نقطة نهاية OpenID Connect الخاصة بـ Google معتمدة من OpenID.

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

إعداد OAuth 2.0

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

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

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

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

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

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

قم بتعيين عنوان URI لإعادة التوجيه

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

لإنشاء أو عرض أو تحرير عناوين URI المعاد توجيهها لبيانات اعتماد OAuth 2.0 ، قم بما يلي:

  1. Go to the Credentials page.
  2. في قسم معرفات عميل OAuth 2.0 من الصفحة ، انقر على بيانات الاعتماد.
  3. عرض أو تحرير عناوين URI المعاد توجيهها.

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

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

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

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

لتمكين شاشة الموافقة على مشروعك:

  1. افتح Consent Screen page في Google API Console .
  2. If prompted, select a project, or create a new one.
  3. املأ النموذج وانقر على حفظ .

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

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

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

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

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

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

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

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

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

تدفق الخادم

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

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

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

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

أحد الخيارات الجيدة لرمز الحالة هو سلسلة من 30 حرفًا أو نحو ذلك تم إنشاؤها باستخدام مولد رقم عشوائي عالي الجودة. آخر هو التجزئة التي تم إنشاؤها عن طريق توقيع بعض متغيرات حالة الجلسة الخاصة بك بمفتاح يتم الاحتفاظ به سراً في النهاية الخلفية الخاصة بك.

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

بي أتش بي

يجب عليك تنزيل مكتبة عميل 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
));

جافا

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

// 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);

بايثون

يجب عليك تنزيل مكتبة عميل 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 الأساسي من مستند Discovery باستخدام قيمة بيانات التعريف 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 شاشة الموافقة طلبًا للموافقة على إصدار عنوان البريد الإلكتروني للمستخدم لتطبيقك. (اقرأ المزيد على login_hint .)
  • استخدم معلمة hd لتحسين تدفق OpenID Connect لمستخدمي نطاق G Suite معين. (اقرأ المزيد 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:

بي أتش بي

يجب عليك تنزيل مكتبة عميل 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);
}

جافا

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

// 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.");
}

بايثون

يجب عليك تنزيل مكتبة عميل 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 API.
expires_in العمر المتبقي لرمز الوصول بالثواني.
id_token JWT التي تحتوي على معلومات هوية المستخدم التي تم توقيعها رقميًا بواسطة Google.
scope نطاقات الوصول الممنوحة بواسطة access_token التعبير عنها access_token سلاسل مفصولة بمسافات وحساسة لحالة الأحرف.
token_type يحدد نوع الرمز الذي تم إرجاعه. في هذا الوقت ، يكون لهذا الحقل دائمًا القيمة Bearer .
refresh_token (اختياري)

هذا الحقل موجود فقط إذا تم تعيين معلمة access_type على وضع عدم offline في طلب المصادقة . للحصول على التفاصيل ، راجع تحديث الرموز المميزة .

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

الرمز المميز للمعرف هو JWT (رمز ويب JSON) ، أي كائن JSON مشفر باستخدام Base64. عادةً ، من المهم أن تتحقق من صحة الرمز المميز للمعرف قبل استخدامه ، ولكن نظرًا لأنك تتواصل مباشرةً مع Google عبر قناة HTTPS خالية من الوسيط وتستخدم سر العميل للمصادقة على Google ، فيمكنك أن تكون واثقًا من أن الرمز المميز لك استقبال يأتي حقًا من Google وهو صالح. إذا قام الخادم الخاص بك بتمرير الرمز المميز للمعرف إلى مكونات أخرى لتطبيقك ، فمن المهم للغاية أن تقوم المكونات الأخرى بالتحقق من صحة الرمز المميز قبل استخدامه.

نظرًا لأن معظم مكتبات API تجمع بين التحقق من الصحة وعمل فك تشفير قيم base64url المشفرة وتحليل JSON بداخلها ، فمن المحتمل أن ينتهي بك الأمر بالتحقق من صحة الرمز المميز على أي حال أثناء وصولك إلى المطالبات في الرمز المميز للمعرف.

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

رمز المعرف هو كائن JSON يحتوي على مجموعة من أزواج الاسم / القيمة. فيما يلي مثال تمت تهيئته لسهولة القراءة:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

قد تحتوي Google ID Tokens على الحقول التالية (المعروفة باسم المطالبات ):

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

عند وجود مطالبات name ، يمكنك استخدامها لتحديث سجلات مستخدم التطبيق. لاحظ أن هذا الادعاء ليس مضمونًا أبدًا.

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

عند وجود مطالبات picture ، يمكنك استخدامها لتحديث سجلات مستخدم التطبيق الخاص بك. لاحظ أن هذا الادعاء ليس مضمونًا أبدًا.

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

عندما تكون مطالبات profile موجودة ، يمكنك استخدامها لتحديث سجلات مستخدم التطبيق الخاص بك. لاحظ أن هذا الادعاء ليس مضمونًا أبدًا.

6. توثيق المستخدم

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

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

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

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

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

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

تحديث الرموز

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

الاعتبارات:

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

لمزيد من المعلومات ، راجع تحديث رمز وصول (وصول دون اتصال) .

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

لمزيد من المعلومات حول معلمة prompt ، راجع prompt في جدول معلمات URI للمصادقة .

معلمات URI للمصادقة

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

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

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

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

إذا كانت قيمة نطاق email موجودة ، فإن الرمز المميز للمعرف يتضمن مطالبات email email_verified email .

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

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

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

سلسلة غير شفافة يتم تعثرها في البروتوكول ؛ وهذا يعني أنه يتم إرجاعه كمعامل URI في التدفق الأساسي ، وفي معرف URI #fragment في التدفق الضمني.

يمكن أن تكون state مفيدة لربط الطلبات والاستجابات. نظرًا لأنه يمكن تخمين redirect_uri ، فإن استخدام قيمة state يمكن أن يزيد من ضمانك بأن الاتصال الوارد هو نتيجة طلب مصادقة بدأه تطبيقك. إذا قمت بإنشاء سلسلة عشوائية أو قمت بتشفير تجزئة بعض حالات العميل (على سبيل المثال ، ملف تعريف الارتباط) في متغير state هذا ، فيمكنك التحقق من صحة الاستجابة لضمان بالإضافة إلى ذلك أن الطلب والاستجابة نشأت في نفس المتصفح. يوفر هذا الحماية ضد الهجمات مثل تزوير الطلبات عبر المواقع.

access_type (اختياري) القيم المسموح بها هي offline و online . تم توثيق التأثير في الوصول دون اتصال ؛ في حالة طلب رمز وصول ، لا يتلقى العميل رمزًا للتحديث ما لم يتم تحديد قيمة offline .
display (اختياري) قيمة سلسلة ASCII لتحديد كيفية قيام خادم التفويض بعرض صفحات واجهة المستخدم الخاصة بالمصادقة والموافقة. يتم تحديد القيم التالية وقبولها بواسطة خوادم Google ، ولكن ليس لها أي تأثير على سلوكها: page ، popup ، touch ، wap .
hd (اختياري)

تعمل معلمة hd (النطاق المستضاف) على تبسيط عملية تسجيل الدخول لحسابات G Suite المستضافة. بتضمين نطاق مستخدم G Suite (على سبيل المثال ، mycollege.edu ) ، يمكنك الإشارة إلى أنه يجب تحسين واجهة مستخدم اختيار الحساب للحسابات في هذا النطاق. لتحسين حسابات G Suite بشكل عام بدلاً من نطاق واحد فقط ، عيِّن قيمة علامة النجمة ( * ): hd=* .

لا تعتمد على تحسين واجهة المستخدم هذا للتحكم في من يمكنه الوصول إلى تطبيقك ، حيث يمكن تعديل الطلبات من جانب العميل. تأكد من التحقق من أن رمز المعرف الذي تم إرجاعه له قيمة مطالبة hd تطابق ما تتوقعه (على سبيل المثال ، mycolledge.edu ). على عكس معلمة الطلب ، يتم تضمين مطالبة ID token hd ضمن رمز أمان مميز من Google ، لذلك يمكن الوثوق بالقيمة.

include_granted_scopes (اختياري) إذا تم توفير هذه المعلمة بالقيمة true ، وتم منح طلب التفويض ، فسوف يتضمن التفويض أي تراخيص سابقة مُنحت لمجموعة المستخدم / التطبيق هذه للنطاقات الأخرى ؛ انظر التفويض المتزايد .

لاحظ أنه لا يمكنك إجراء تفويض متزايد من خلال تدفق التطبيقات المثبتة.

login_hint (اختياري) عندما يعرف تطبيقك المستخدم الذي يحاول المصادقة عليه ، يمكنه توفير هذه المعلمة كتلميح لخادم المصادقة. يؤدي تمرير هذا التلميح إلى إيقاف محدد الحساب وإما أن يملأ مربع البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول ، أو يحدد الجلسة المناسبة (إذا كان المستخدم يستخدم تسجيل الدخول المتعدد ) ، مما قد يساعدك في تجنب المشكلات التي تحدث إذا كان تطبيقك يسجل في حساب مستخدم خاطئ. يمكن أن تكون القيمة إما عنوان بريد إلكتروني أو سلسلة sub ، والتي تعادل معرف Google للمستخدم.
prompt (اختياري) قائمة بقيم السلسلة مفصولة بمسافات تحدد ما إذا كان خادم التفويض يطالب المستخدم بإعادة المصادقة والموافقة. القيم الممكنة هي:
  • none

    لا يعرض خادم التفويض أي شاشات للمصادقة أو موافقة المستخدم ؛ سيعرض خطأ إذا لم يكن المستخدم قد تمت مصادقته بالفعل ولم يكن لديه موافقة مسبقة التكوين للنطاقات المطلوبة. لا يمكنك استخدام none للتحقق من المصادقة و / أو الموافقة الحالية.

  • consent

    يطالب خادم التفويض المستخدم بالموافقة قبل إعادة المعلومات إلى العميل.

  • select_account

    يطالب خادم التفويض المستخدم بتحديد حساب مستخدم. يسمح هذا للمستخدم الذي لديه حسابات متعددة في خادم التفويض بالاختيار من بين الحسابات المتعددة التي قد يكون لديهم جلسات حالية لها.

إذا لم يتم تحديد أي قيمة ولم يكن المستخدم قد أذن بالوصول مسبقًا ، فسيظهر للمستخدم شاشة الموافقة.

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

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

فيما يلي المواقف الشائعة التي قد ترسل فيها رموز معرف إلى الخادم الخاص بك:

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

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

الشيء الوحيد الذي يجعل رموز ID مفيدة هو حقيقة أنه يمكنك تمريرها حول مكونات مختلفة من تطبيقك. يمكن أن تستخدم هذه المكونات رمزًا مميزًا للمعرف كآلية مصادقة خفيفة الوزن لمصادقة التطبيق والمستخدم. ولكن قبل أن تتمكن من استخدام المعلومات الموجودة في الرمز المميز للمعرف أو الاعتماد عليها كتأكيد على مصادقة المستخدم ، يجب عليك التحقق من صحتها.

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

  1. تحقق من أن رمز المعرف قد تم توقيعه بشكل صحيح من قبل المُصدر. يتم توقيع الرموز المميزة الصادرة عن Google باستخدام إحدى الشهادات الموجودة في URI المحدد في قيمة البيانات الوصفية jwks_uri Discovery .
  2. تحقق من أن قيمة iss المطالبة في الرمز المميز ID تساوي https://accounts.google.com أو accounts.google.com .
  3. تحقق من أن قيمة مطالبة aud في الرمز المميز للمعرف تساوي معرّف عميل التطبيق الخاص بك.
  4. تحقق من أن وقت الاستحقاق ( exp المطالبة) من الرمز المميز ID لم يجتز.
  5. إذا حددت قيمة معلمة hd في الطلب ، فتأكد من أن رمز المعرف المميز به مطالبة hd تطابق نطاق مستضاف مقبول في G Suite.

تتضمن الخطوات من 2 إلى 5 مقارنات بين السلسلة والتاريخ فقط وهي واضحة تمامًا ، لذلك لن نفصلها هنا.

الخطوة الأولى أكثر تعقيدًا وتتضمن فحص التوقيع المشفر. لأغراض تصحيح الأخطاء ، يمكنك استخدام نقطة نهاية tokeninfo من Google للمقارنة بالمعالجة المحلية tokeninfo على الخادم أو الجهاز الخاص بك. افترض أن قيمة الرمز المميز للمعرف الخاص بك هي XYZ123 . ثم تقوم https://oauth2.googleapis.com/tokeninfo?id_token= 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 بيانات claims_supported الخاصة claims_supported من مستند الاكتشاف. قد يختار المستخدمون أو مؤسساتهم توفير حقول معينة أو حجبها ، لذلك قد لا تحصل على معلومات لكل حقل لنطاقات الوصول المصرح بها.

وثيقة الاكتشاف

يتطلب بروتوكول OpenID Connect استخدام نقاط نهاية متعددة لمصادقة المستخدمين ، ولطلب الموارد بما في ذلك الرموز المميزة ومعلومات المستخدم والمفاتيح العامة.

لتبسيط عمليات التنفيذ وزيادة المرونة ، يسمح OpenID Connect باستخدام "مستند الاكتشاف" ، وهو مستند JSON موجود في موقع معروف جيدًا يحتوي على أزواج قيمة المفتاح والتي توفر تفاصيل حول تكوين موفر OpenID Connect ، بما في ذلك URIs الخاصة بالتخويل ونقاط نهاية الرمز المميز والإلغاء ومعلومات المستخدم والمفاتيح العامة. يمكن استرداد مستند اكتشاف خدمة OpenID Connect من Google من:

https://accounts.google.com/.well-known/openid-configuration

لاستخدام خدمات OpenID Connect من Google ، يجب عليك كتابة كود URI الخاص بوثيقة Discovery ( https://accounts.google.com/.well-known/openid-configuration ) في تطبيقك. يجلب تطبيقك المستند ، ويطبق قواعد التخزين المؤقت في الاستجابة ، ثم يسترد URIs منه حسب الحاجة. على سبيل المثال ، لمصادقة مستخدم ، ستسترد شفرتك قيمة البيانات الوصفية لنقطة authorization_endpoint ( https://accounts.google.com/o/oauth2/v2/auth في المثال أدناه) باعتبارها URI الأساسي لطلبات المصادقة التي يتم إرسالها إلى جوجل.

هنا مثال على مثل هذه الوثيقة ؛ أسماء الحقول هي تلك المحددة في OpenID Connect Discovery 1.0 (راجع هذا المستند للتعرف على معانيها). القيم توضيحية بحتة وقد تتغير ، على الرغم من نسخها من إصدار حديث من مستند Google Discovery الفعلي:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

قد تتمكن من تجنب HTTP ذهابًا وإيابًا عن طريق تخزين القيم من مستند الاكتشاف مؤقتًا. يتم استخدام رؤوس التخزين المؤقت HTTP القياسية ويجب احترامها.

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

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

التوافق مع OpenID Connect

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