لمحة عن هذا الدرس التطبيقي حول الترميز
1. نظرة عامة
في هذا الدرس التطبيقي حول الترميز، سننشئ صفحة ويب بسيطة لتسجيل دخول المستخدم. ستستخدم مكتبة JavaScript لخدمات هوية Google لعرض زر "تسجيل الدخول باستخدام حساب Google" وتخصيصه.
المُعطيات
- كيفية إضافة زر "تسجيل الدخول باستخدام حساب Google" إلى صفحة ويب
- كيفية إعداد تطبيق ويب OAuth 2.0
- طريقة فك ترميز الرمز المميّز للمعرّف
- كيفية تخصيص زر "تسجيل الدخول باستخدام حساب Google"
المتطلبات
- محرر نصوص ومكان لاستضافة صفحة ويب والبيئات التي سنتناولها في هذا الدرس التطبيقي حول الترميز:
- إذا كان يتم تشغيله محليًا في وحدة طرفية على جهازك
- باستخدام منصة مثل Glitch.
- مشروع على Google Cloud ويمكنك استخدام مشروعك الحالي أو إنشاء مشروع جديد. يتوفّر حساب ومشروع على Google Cloud Platform مجانًا.
- معرفة أساسية بلغة HTML وCSS وJavaScript وأدوات مطوري البرامج في Chrome (أو ما يعادلها).
لنبدأ الآن.
2. إنشاء صفحة تسجيل الدخول الخاصة بك
أضِف نموذج الرمز هذا إلى ملف باسم "index.html". يمكنك إجراء ذلك على جهازك باستخدام محرِّر النصوص المفضّل لديك أو باستخدام منصة مثل Glitch.
<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://accounts.google.com/gsi/client" async></script>
<script>
function decodeJWT(token) {
let base64Url = token.split(".")[1];
let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
let jsonPayload = decodeURIComponent(
atob(base64)
.split("")
.map(function (c) {
return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
})
.join("")
);
return JSON.parse(jsonPayload);
}
function handleCredentialResponse(response) {
console.log("Encoded JWT ID token: " + response.credential);
const responsePayload = decodeJWT(response.credential);
console.log("Decoded JWT ID token fields:");
console.log(" Full Name: " + responsePayload.name);
console.log(" Given Name: " + responsePayload.given_name);
console.log(" Family Name: " + responsePayload.family_name);
console.log(" Unique ID: " + responsePayload.sub);
console.log(" Profile image URL: " + responsePayload.picture);
console.log(" Email: " + responsePayload.email);
}
</script>
</head>
<body>
<!-- g_id_onload contains Google Identity Services settings -->
<div
id="g_id_onload"
data-auto_prompt="false"
data-callback="handleCredentialResponse"
data-client_id="PUT_YOUR_WEB_CLIENT_ID_HERE"
></div>
<!-- g_id_signin places the button on a page and supports customization -->
<div class="g_id_signin"></div>
</body>
</html>
هذه الرمز هي عبارة عن خليط من HTML وJavaScript، وتؤدي إلى عدد من الأشياء:
- تضبط مكتبة "خدمات هوية Google" هذه باستخدام
g_id_onload، - يعرض زر "تسجيل الدخول باستخدام حساب Google" باستخدام
g_id_signin - إضافة معالج دالة معاودة الاتصال بلغة JavaScript يُسمى
handleCredentialResponseلتلقّي بيانات اعتماد تسجيل دخول المستخدم من Google decodeJWTلتحويل بيانات اعتماد رمز JSON المميّز للويب (JWT) إلى تنسيق JSON عادي فقط.
قد يبدو الأمر مختلفًا بعض الشيء في تطبيق data-client_id="PUT_YOUR_WEB_CLIENT_ID_HERE".
في الوقت الحالي، ما عليك سوى تجاهله، وسنعود إليه بعد قليل.
3. عرض صفحة الويب
سنناقش بيئتَين لعرض index.html على المتصفّح:
- تشغيل خادم ويب محليًا على جهازك
- منصة بعيدة مثل Glitch.
اختَر الطريقة التي تناسبك. بعد الإعداد، سنستخدم عنوان URL لإعداد برنامج ويب OAuth.
محليًا من جهازك
تأكد من تثبيت Python3 على النظام لديك. يختلف الإعداد حسب نظام التشغيل والنظام الأساسي، فابدأ بـ إعداد Python واستخدامه إذا كنت بحاجة إلى تثبيت Python على جهازك.
ابدأ تشغيل خادم الويب Python في الدليل الذي يحتوي على index.html:
$ python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
لنفترض أن هناك خادم ويب يستمع الآن إلى الاتصالات عبر المنفذ 8000، وهو جاهز لعرض صفحة تسجيل الدخول. عنوان URL هو
http://localhost:8000
استخدام نظام أساسي بعيد
إذا اخترت تعديل صفحة تسجيل الدخول واستضافتها باستخدام ميزة Glitch (أو ما يعادلها)، من المفترَض أن تتمكّن من فتح index.html إما في جزء المعاينة أو علامة تبويب جديدة في المتصفّح.
عنوان URL الذي ستستخدمه عادةً هو اسم المشروع الذي أدخلته عند إعداد مشروع glich.com. على سبيل المثال، إذا كان اسم مشروع أعطال الشاشة gis-example، سيكون عنوان URL هو https://gis-example.glitch.me. بالطبع، ستكون قد اخترت اسم مشروع مختلفًا ولا يمكنك إعادة استخدام هذا الاسم. عنوان URL هو
https://<var>your-project-name</var>.glitch.me
تحميل الصفحة
يُرجى الانتظار قليلاً...
علينا أولاً إنشاء برنامج ويب OAuth 2.0 وإعداده.
انسخ عنوان URL أو دوِّنه، حيث يتم استخدامه في الخطوة التالية.
4. إعداد برنامج ويب OAuth
لنبدأ في ضبط بروتوكول OAuth حتى يتمكن المستخدمون من تسجيل الدخول.
- انقر على هذا الرابط لإنشاء عميل ويب OAuth 2.0. إذا لزم الأمر، سيساعدك المعالج في إنشاء مشروع جديد على Google Cloud وإعداده.
- اختَر تطبيق الويب من القائمة المنسدلة نوع التطبيق.
- اضغط على الزر إضافة معرّف موارد منتظم (URI) ضمن مصادر JavaScript المعتمَدة.
- أدخِل عنوان URL الذي يستضيف
index.htmlمن الخطوة 3 عرض صفحة الويب.مستضاف على جهازك المحلي
مستضافة على نظام أساسي بعيد
- اضغط على إنشاء
- انسخ معرِّف العميل الجديد.
تتبقى نقطة أخيرة
علينا الرجوع وتحديث "index.html" لاستخدام Client-ID الجديد. في المحرّر، استبدِل PUT_YOUR_WEB_CLIENT_ID_HERE بمعرِّف العميل الجديد. يظهر معرّف العميل على النحو التالي: 1234567890-abc123def456.apps.googleusercontent.com.
لنسجّل الدخول.
5. تسجيل الدخول
أولاً، افتح وحدة تحكم المطوّرين في متصفحك، وسيتم تسجيل أي أخطاء وبيانات اعتماد الرمز المميز لمعرّف JWT من Google هنا.
اضغط على زر "تسجيل الدخول باستخدام حساب Google".
قد يختلف ما سيحدث بعد ذلك قليلاً:
- إذا كنت مسجّلاً الدخول حاليًا إلى أكثر من حساب واحد على Google، سيُطلب منك اختيار الحساب الذي ستستخدمه لتسجيل الدخول إلى تطبيق الويب هذا.
- إذا كانت هذه هي المرة الأولى التي تسجّل فيها الدخول إلى تطبيق الويب هذا، ستظهر لك رسالة تطلب منك الموافقة.
بعد اختيار حساب وتقديم موافقتك، تردّ Google بعد ذلك باستخدام JWT. تتلقّى دالة معاودة الاتصال handleCredentialResponse التي يتم تشغيلها في المتصفِّح JWT.
في هذا الدرس التطبيقي حول الترميز، سيتم فك ترميز محتوى JWT وطباعته، وفي تطبيق ويب خاص بالإنتاج، يمكنك التحقّق من رمز JWT الذي تم فك ترميزه واستخدامه لتنفيذ إجراء أكثر فائدة، مثل إنشاء حساب جديد على النظام الأساسي للخلفية أو إنشاء جلسة جديدة للمستخدم.
6. فحص الرمز المميّز لمعرّف JWT
يتم تسجيل JWT المشفر في وحدة تحكم المطوّرين. بعد فك ترميز JWT، يتم أيضًا تسجيل بعض حقول الرمز المميز للمعرّف شائعة الاستخدام في وحدة التحكم.
يمكنك استخدام أدوات على الإنترنت مثل jwt.io لفك ترميز JWT.
بدلاً من ذلك، يمكنك أيضًا استخدام jq في الوحدة الطرفية لفك ترميز رسالة JWT وعرضها (قد تحتاج إلى استخدام أداة إدارة الحِزم لتثبيت jq). أولاً، الصق سلسلة JWT المشفرة في علامتي الاقتباس المزدوجة:
$ JWT="eyJhbGciOiJSUzI1Ni ... Hecz6Wm4Q"
ثم استخدِم هذا الأمر لفك ترميزه
$ echo $JWT | jq -R 'split(".") | .[0],.[1] | @base64d | fromjson'
{
"alg": "RS256",
"kid": "c7e04465649ffa606557650c7e65f0a87ae00fe8",
"typ": "JWT"
}
{
"iss": "https://accounts.google.com",
"azp": "123456789012-s0meRand0mStR1nG.apps.googleusercontent.com",
"aud": "123456789012-s0meRand0mStR1nG.apps.googleusercontent.com",
"sub": "2718281828459045",
"email": "example@example.com",
"email_verified": true,
"nbf": 1744645148,
"name": "Brian Daugherty",
"picture": "https://lh3.googleusercontent.com/a/08a898b88ca4d6407be652d8",
"given_name": "Brian",
"family_name": "Daugherty",
"iat": 1744645448,
"exp": 1744649048,
"jti": "52cd32984b30e178aa88bc2e75e63e055a461fcf"
}
يجب أن تكون بعض المفاتيح والقيم مثل البريد الإلكتروني والاسم والصورة سهلة الفهم إلى حد ما. ويتم استخدام القيم الأخرى للتحقّق من JWT قبل استخدامه. يتضمن الحصول على معلومات المستخدم من الرمز المميز لرقم التعريف مزيدًا من المعلومات حول ما تعنيه جميع الحقول.
7. تخصيص الزر
يتم وضع زر تسجيل الدخول التلقائي على الصفحة على هذا النحو
<div class="g_id_signin"></div>
وسيظهر لك هذا الزر
ولكن ربما تريد تغيير اللون أو الحجم أو النص ليتناسب مع مظهر موقعك الإلكتروني.
لنغيّر لون الزر إلى اللون الأزرق ونطلب منك بدلاً من ذلك الاشتراك من خلال Google.
افتح index.html وحدِّد موقع العنصر g_id_signin وأضِف السمتَين data-theme="filled_blue" وdata-text="signup_with":
<div
class="g_id_signin"
data-theme="filled_blue"
data-text="signup_with"
></div>
بعد حفظ الصفحة وإعادة تحميلها، سيظهر لك زر أزرق يتضمّن النص الجديد.
ويمكنك تخصيص الزر بشكل أكبر، والاطّلاع على سمات البيانات المرئية للحصول على قائمة كاملة بالخيارات.
8. موارد إضافية
تهانينا!
لقد أضفت زر "تسجيل الدخول باستخدام حساب Google" إلى صفحة ويب، وضبطت برنامج ويب OAuth 2.0، وفك ترميز الرمز المميّز لمعرّف JWT، وتعلّمت كيفية تخصيص شكل الزر.
قد تساعدك هذه الروابط في معرفة الخطوات التالية:
- HTML API لخدمات Google Identity
- JavaScript API لخدمات Google Identity
- كيفية الإعداد ميزة "تسجيل الدخول باستخدام حساب Google للويب"
- إثبات ملكية رمز مميَّز لمعرّف Google
- يمكنك الاطّلاع على مزيد من المعلومات عن مشاريع Google Cloud هنا.
- طرق مصادقة Google Identity