يمكنك السماح للمستخدمين بالمصادقة باستخدام Firebase من خلال Apple ID الخاص بهم عن طريق استخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase لتنفيذ عملية تسجيل الدخول الشاملة باستخدام OAuth 2.0.
قبل البدء
لتسجيل دخول المستخدمين باستخدام Apple، عليك أولاً إعداد ميزة "تسجيل الدخول باستخدام Apple" على موقع Apple الإلكتروني للمطوّرين، ثم تفعيل Apple كموفّر خدمة تسجيل الدخول لمشروع Firebase.
الانضمام إلى برنامج Apple Developer Program
لا يمكن ضبط ميزة "تسجيل الدخول باستخدام Apple" إلا من قِبل أعضاء برنامج Apple Developer.
ضبط ميزة "تسجيل الدخول باستخدام Apple"
في موقع Apple Developer الإلكتروني، اتّبِع الخطوات التالية:
-
اربط موقعك الإلكتروني بتطبيقك كما هو موضّح في القسم الأول من مقالة إعداد ميزة "تسجيل الدخول باستخدام Apple" للويب. عندما يُطلب منك ذلك، سجِّل عنوان URL التالي كعنوان URL للإرجاع:
https://YOUR_FIREBASE_PROJECT_ID.firebaseapp.com/__/auth/handler
يمكنك العثور على رقم تعريف مشروعك على Firebase في
الإعدادات > علامة التبويب الإعدادات العامة في وحدة تحكّم Firebase.عند الانتهاء، دوِّن معرّف الخدمة الجديد الذي ستحتاج إليه في القسم التالي.
- أنشئ مفتاحًا خاصًا لميزة "تسجيل الدخول باستخدام Apple". ستحتاج إلى المفتاح الخاص الجديد ورقم تعريف المفتاح في القسم التالي.
-
إذا كنت تستخدم أيًا من ميزات Firebase Authentication التي ترسل رسائل إلكترونية إلى المستخدمين، بما في ذلك تسجيل الدخول عبر رابط البريد الإلكتروني والتحقّق من عنوان البريد الإلكتروني وإبطال تغيير الحساب وغيرها، اضبط خدمة ترحيل البريد الإلكتروني الخاص من Apple وسجِّل
noreply@YOUR_FIREBASE_PROJECT_ID.firebaseapp.com(أو نطاق نموذج البريد الإلكتروني المخصّص) حتى تتمكّن Apple من ترحيل الرسائل الإلكترونية المُرسَلة من قِبل Firebase Authentication إلى عناوين البريد الإلكتروني المجهولة الهوية من Apple.
تفعيل Apple كموفّر خدمة تسجيل الدخول
- أضِف Firebase إلى مشروعك.
- في وحدة تحكّم Firebase، انتقِل إلى الأمان > المصادقة.
- في علامة التبويب طريقة تسجيل الدخول، فعِّل موفّر تسجيل الدخول Apple. حدِّد معرّف الخدمة الذي أنشأته في القسم السابق. في قسم إعدادات مسار رمز OAuth، حدِّد معرّف فريق Apple والمفتاح الخاص ومعرّف المفتاح الذي أنشأته في القسم السابق.
الامتثال لمتطلبات Apple بشأن البيانات المخفية الهوية
تتيح ميزة "تسجيل الدخول باستخدام Apple" للمستخدمين إخفاء هوية بياناتهم،
بما في ذلك عنوان بريدهم الإلكتروني، عند تسجيل الدخول. يحصل المستخدمون الذين يختارون هذا الخيار
على عناوين بريد إلكتروني في النطاق privaterelay.appleid.com. عند استخدام ميزة "تسجيل الدخول باستخدام Apple" في تطبيقك، عليك الالتزام بأي سياسات أو بنود مطبّقة على المطوّرين من Apple في ما يتعلق بمعرّفات Apple المجهولة الهوية هذه.
ويشمل ذلك الحصول على أي موافقة مطلوبة من المستخدم قبل ربط أي معلومات شخصية تحدّد الهوية بشكل مباشر بمعرّف Apple ID مجهول الهوية. عند استخدام "مصادقة Firebase"، قد يشمل ذلك الإجراءات التالية:
- ربط عنوان بريد إلكتروني بمعرّف Apple مخفي الهوية أو العكس
- ربط رقم هاتف بمعرّف Apple ID مخفي الهوية أو العكس
- ربط بيانات اعتماد اجتماعية غير مجهولة الهوية (Facebook وGoogle وما إلى ذلك) بمعرّف Apple مجهول الهوية أو العكس.
إنّ القائمة أعلاه ليست شاملة. يُرجى الرجوع إلى اتفاقية ترخيص برنامج Apple Developer Program في قسم "العضوية" (Membership) في حساب المطوّر للتأكّد من أنّ تطبيقك يستوفي متطلبات Apple.
التعامل مع عملية تسجيل الدخول باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase
إذا كنت بصدد إنشاء تطبيق ويب، فإن أسهل طريقة لمصادقة المستخدمين باستخدام Firebase من خلال حساباتهم على Apple هي معالجة مسار تسجيل الدخول بالكامل باستخدام حزمة تطوير البرامج (SDK) لـ Firebase JavaScript.
للتعامل مع عملية تسجيل الدخول باستخدام حزمة تطوير البرامج (SDK) لبرنامج Firebase JavaScript، اتّبِع الخطوات التالية:
أنشئ مثيلاً من OAuthProvider باستخدام معرّف مقدّم الخدمة المقابل apple.com.
Web
import { OAuthProvider } from "firebase/auth"; const provider = new OAuthProvider('apple.com');
Web
var provider = new firebase.auth.OAuthProvider('apple.com');
اختياري: يمكنك تحديد نطاقات OAuth 2.0 إضافية غير النطاقات التلقائية التي تريد طلبها من موفّر المصادقة.
Web
provider.addScope('email'); provider.addScope('name');
Web
provider.addScope('email'); provider.addScope('name');
عند تفعيل خيار حساب واحد لكل عنوان بريد إلكتروني، يطلب Firebase تلقائيًا نطاقات البريد الإلكتروني والاسم. في حال تغيير هذا الإعداد إلى حسابات متعددة لكل عنوان بريد إلكتروني، لن تطلب Firebase أي نطاقات من Apple ما لم تحدّدها.
اختياري: إذا أردت عرض شاشة تسجيل الدخول من Apple بلغة أخرى غير الإنجليزية، اضبط المَعلمة
locale. يُرجى الاطّلاع على مستندات ميزة "تسجيل الدخول باستخدام Apple" لمعرفة اللغات المتوافقة.Web
provider.setCustomParameters({ // Localize the Apple authentication screen in French. locale: 'fr' });
Web
provider.setCustomParameters({ // Localize the Apple authentication screen in French. locale: 'fr' });
المصادقة مع Firebase باستخدام عنصر موفّر OAuth يمكنك مطالبة المستخدمين بتسجيل الدخول باستخدام حساباتهم على Apple إما عن طريق فتح نافذة منبثقة أو عن طريق إعادة التوجيه إلى صفحة تسجيل الدخول. تُفضل طريقة إعادة التوجيه على الأجهزة المحمولة.
لتسجيل الدخول باستخدام نافذة منبثقة، يمكنك استدعاء
signInWithPopup():Web
import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth"; const auth = getAuth(); signInWithPopup(auth, provider) .then((result) => { // The signed-in user info. const user = result.user; // Apple credential const credential = OAuthProvider.credentialFromResult(result); const accessToken = credential.accessToken; const idToken = credential.idToken; // IdP data available using getAdditionalUserInfo(result) // ... }) .catch((error) => { // Handle Errors here. const errorCode = error.code; const errorMessage = error.message; // The email of the user's account used. const email = error.customData.email; // The credential that was used. const credential = OAuthProvider.credentialFromError(error); // ... });
Web
firebase .auth() .signInWithPopup(provider) .then((result) => { /** @type {firebase.auth.OAuthCredential} */ var credential = result.credential; // The signed-in user info. var user = result.user; // You can also get the Apple OAuth Access and ID Tokens. var accessToken = credential.accessToken; var idToken = credential.idToken; // IdP data available using getAdditionalUserInfo(result) // ... }) .catch((error) => { // Handle Errors here. var errorCode = error.code; var errorMessage = error.message; // The email of the user's account used. var email = error.email; // The firebase.auth.AuthCredential type that was used. var credential = error.credential; // ... });
لتسجيل الدخول من خلال إعادة التوجيه إلى صفحة تسجيل الدخول، يمكنك استدعاء
signInWithRedirect():
اتّبِع أفضل الممارسات عند استخدام
signInWithRedirectأوlinkWithRedirectأوreauthenticateWithRedirect.Web
import { getAuth, signInWithRedirect } from "firebase/auth"; const auth = getAuth(); signInWithRedirect(auth, provider);
Web
firebase.auth().signInWithRedirect(provider);
بعد أن يكمل المستخدم عملية تسجيل الدخول ويعود إلى الصفحة، يمكنك الحصول على نتيجة تسجيل الدخول من خلال استدعاء
getRedirectResult():Web
import { getAuth, getRedirectResult, OAuthProvider } from "firebase/auth"; // Result from Redirect auth flow. const auth = getAuth(); getRedirectResult(auth) .then((result) => { const credential = OAuthProvider.credentialFromResult(result); if (credential) { // You can also get the Apple OAuth Access and ID Tokens. const accessToken = credential.accessToken; const idToken = credential.idToken; } // The signed-in user info. const user = result.user; }) .catch((error) => { // Handle Errors here. const errorCode = error.code; const errorMessage = error.message; // The email of the user's account used. const email = error.customData.email; // The credential that was used. const credential = OAuthProvider.credentialFromError(error); // ... });
Web
// Result from Redirect auth flow. firebase .auth() .getRedirectResult() .then((result) => { if (result.credential) { /** @type {firebase.auth.OAuthCredential} */ var credential = result.credential; // You can get the Apple OAuth Access and ID Tokens. var accessToken = credential.accessToken; var idToken = credential.idToken; // IdP data available in result.additionalUserInfo.profile. // ... } // The signed-in user info. var user = result.user; }) .catch((error) => { // Handle Errors here. var errorCode = error.code; var errorMessage = error.message; // The email of the user's account used. var email = error.email; // The firebase.auth.AuthCredential type that was used. var credential = error.credential; // ... });
هذا هو المكان الذي يمكنك فيه أيضًا رصد الأخطاء ومعالجتها. للاطّلاع على قائمة برموز الأخطاء، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.
على عكس مقدّمي الخدمات الآخرين المتوافقين مع Firebase Auth، لا توفّر Apple عنوان URL للصورة.
بالإضافة إلى ذلك، عندما يختار المستخدم عدم مشاركة عنوان بريده الإلكتروني مع التطبيق، توفّر Apple عنوان بريد إلكتروني فريدًا لهذا المستخدم (بالصيغة
xyz@privaterelay.appleid.com) وتشاركه مع تطبيقك. إذا أعددت خدمة إعادة توجيه البريد الإلكتروني الخاص، ستعيد Apple توجيه الرسائل الإلكترونية المُرسَلة إلى العنوان المجهول الهوية إلى عنوان البريد الإلكتروني الحقيقي للمستخدم.لا تشارك Apple معلومات المستخدم، مثل الاسم المعروض، إلا مع التطبيقات التي يسجّل المستخدم الدخول إليها لأول مرة. عادةً ما تخزّن Firebase الاسم المعروض في المرة الأولى التي يسجّل فيها المستخدم الدخول باستخدام Apple، ويمكنك الحصول عليه من خلال
firebase.auth().currentUser.displayName. ومع ذلك، إذا كنت قد استخدمت Apple سابقًا لتسجيل دخول مستخدم إلى التطبيق بدون استخدام Firebase، فلن توفر Apple لـ Firebase الاسم المعروض للمستخدم.
إعادة المصادقة وربط الحساب
يمكن استخدام النمط نفسه مع reauthenticateWithPopup() وreauthenticateWithRedirect()، ويمكنك استخدامهما لاسترداد بيانات اعتماد جديدة للعمليات الحسّاسة التي تتطلّب تسجيل الدخول مؤخرًا:
Web
import { getAuth, reauthenticateWithPopup, OAuthProvider } from "firebase/auth"; // Result from Redirect auth flow. const auth = getAuth(); const provider = new OAuthProvider('apple.com'); reauthenticateWithPopup(auth.currentUser, provider) .then((result) => { // User is re-authenticated with fresh tokens minted and can perform // sensitive operations like account deletion, or updating their email // address or password. // The signed-in user info. const user = result.user; // You can also get the Apple OAuth Access and ID Tokens. const credential = OAuthProvider.credentialFromResult(result); const accessToken = credential.accessToken; const idToken = credential.idToken; // ... }) .catch((error) => { // Handle Errors here. const errorCode = error.code; const errorMessage = error.message; // The email of the user's account used. const email = error.customData.email; // The credential that was used. const credential = OAuthProvider.credentialFromError(error); // ... });
Web
const provider = new firebase.auth.OAuthProvider('apple.com'); firebase .auth() .currentUser .reauthenticateWithPopup(provider) .then((result) => { // User is re-authenticated with fresh tokens minted and can perform // sensitive operations like account deletion, or updating their email // address or password. /** @type {firebase.auth.OAuthCredential} */ var credential = result.credential; // The signed-in user info. var user = result.user; // You can also get the Apple OAuth Access and ID Tokens. var accessToken = credential.accessToken; var idToken = credential.idToken; // IdP data available in result.additionalUserInfo.profile. // ... }) .catch((error) => { // Handle Errors here. var errorCode = error.code; var errorMessage = error.message; // The email of the user's account used. var email = error.email; // The firebase.auth.AuthCredential type that was used. var credential = error.credential; // ... });
ويمكنك استخدام linkWithPopup() وlinkWithRedirect() لربط موفّري هوية مختلفين بالحسابات الحالية.
يُرجى العِلم أنّ Apple تطلب منك الحصول على موافقة صريحة من المستخدمين قبل ربط حساباتهم على Apple ببيانات أخرى.
على سبيل المثال، لربط حساب Facebook بحساب Firebase الحالي، استخدِم رمز الدخول الذي حصلت عليه من تسجيل دخول المستخدم إلى Facebook:
Web
import { getAuth, linkWithPopup, FacebookAuthProvider } from "firebase/auth"; const auth = getAuth(); const provider = new FacebookAuthProvider(); provider.addScope('user_birthday'); // Assuming the current user is an Apple user linking a Facebook provider. linkWithPopup(auth.currentUser, provider) .then((result) => { // Facebook credential is linked to the current Apple user. // ... // The user can now sign in to the same account // with either Apple or Facebook. }) .catch((error) => { // Handle error. });
Web
const provider = new firebase.auth.FacebookAuthProvider(); provider.addScope('user_birthday'); // Assuming the current user is an Apple user linking a Facebook provider. firebase.auth().currentUser.linkWithPopup(provider) .then((result) => { // Facebook credential is linked to the current Apple user. // Facebook additional data available in result.additionalUserInfo.profile, // Additional Facebook OAuth access token can also be retrieved. // result.credential.accessToken // The user can now sign in to the same account // with either Apple or Facebook. }) .catch((error) => { // Handle error. });
المصادقة باستخدام Firebase في إضافة Chrome
إذا كنت بصدد إنشاء تطبيق لإضافة Chrome، يُرجى الاطّلاع على دليل المستندات خارج الشاشة.
يُرجى العِلم أنّه لا يزال عليك إثبات ملكية النطاق الخاص لدى Apple، تمامًا مثل نطاق firebaseapp.com التلقائي:
http://auth.custom.example.com/.well-known/apple-developer-domain-association.txt
إبطال الرمز المميّز
تتطلب Apple أن تتيح التطبيقات التي تدعم إنشاء الحساب للمستخدمين بدء حذف حساباتهم داخل التطبيق، كما هو موضح في إرشادات مراجعة متجر التطبيقات
لاستيفاء هذا الشرط، اتّبِع الخطوات التالية:
تأكَّد من ملء قسمَي معرّف الخدمات وإعدادات مسار رمز OAuth في إعدادات مقدّم خدمة "تسجيل الدخول باستخدام Apple"، كما هو موضّح في قسم إعداد ميزة "تسجيل الدخول باستخدام Apple".
بما أنّ Firebase لا تخزّن رموز المستخدمين المميّزة عند إنشاء المستخدمين باستخدام ميزة "تسجيل الدخول باستخدام Apple"، عليك أن تطلب من المستخدم تسجيل الدخول مرة أخرى قبل إبطال رمزه المميّز وحذف الحساب.
بعد ذلك، يمكنك الحصول على رمز OAuth المميز للدخول من Apple من
OAuthCredential، واستخدامه لطلبrevokeAccessToken(auth, token)لإبطال رمز OAuth المميز للدخول من Apple.const provider = new OAuthProvider('apple.com'); provider.addScope('email'); provider.addScope('name'); const auth = getAuth(); signInWithPopup(auth, provider).then(result => { // Get the Apple OAuth access token. const credential = OAuthProvider.credentialFromResult(result); const accessToken = credential.accessToken; // Revoke the Apple OAuth access token. revokeAccessToken(auth, accessToken) .then(() => { // Token revoked. // Delete the user account. // ... }) .catch(error => { // An error happened. // ... }); });أخيرًا، احذف حساب المستخدم (وجميع البيانات المرتبطة به).
إجراء متقدّم: المصادقة باستخدام Firebase في Node.js
للمصادقة باستخدام Firebase في تطبيق Node.js، اتّبِع الخطوات التالية:
سجِّل دخول المستخدم باستخدام حسابه على Apple واحصل على الرمز المميّز لمعرّف Apple الخاص بالمستخدم. يمكنك تحقيق ذلك بعدة طرق. على سبيل المثال، إذا كان تطبيق Node.js يحتوي على واجهة أمامية للمتصفّح:
في الخلفية، أنشِئ سلسلة عشوائية ("قيمة عشوائية") واحتسِب تجزئة SHA256 الخاصة بها. الرقم الخاص هو قيمة تُستخدم لمرة واحدة للتحقّق من صحة رحلة ذهاب وعودة واحدة بين الخلفية وخوادم مصادقة Apple.
Web
const crypto = require("crypto"); const string_decoder = require("string_decoder"); // Generate a new random string for each sign-in const generateNonce = (length) => { const decoder = new string_decoder.StringDecoder("ascii"); const buf = Buffer.alloc(length); let nonce = ""; while (nonce.length < length) { crypto.randomFillSync(buf); nonce = decoder.write(buf); } return nonce.slice(0, length); }; const unhashedNonce = generateNonce(10); // SHA256-hashed nonce in hex const hashedNonceHex = crypto.createHash('sha256') .update(unhashedNonce).digest().toString('hex');
Web
const crypto = require("crypto"); const string_decoder = require("string_decoder"); // Generate a new random string for each sign-in const generateNonce = function(length) { const decoder = new string_decoder.StringDecoder("ascii"); const buf = Buffer.alloc(length); var nonce = ""; while (nonce.length < length) { crypto.randomFillSync(buf); nonce = decoder.write(buf); } return nonce.slice(0, length); }; const unhashedNonce = generateNonce(10); // SHA256-hashed nonce in hex const hashedNonceHex = crypto.createHash('sha256') .update(unhashedNonce).digest().toString('hex');
في صفحة تسجيل الدخول، حدِّد الرمز الفريد المشفّر في إعدادات "تسجيل الدخول باستخدام Apple":
<script src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js"></script> <div id="appleid-signin" data-color="black" data-border="true" data-type="sign in"></div> <script> AppleID.auth.init({ clientId: YOUR_APPLE_CLIENT_ID, scope: 'name email', redirectURI: URL_TO_YOUR_REDIRECT_HANDLER, // See the next step. state: '[STATE]', // Optional value that Apple will send back to you // so you can return users to the same context after // they sign in. nonce: HASHED_NONCE // The hashed nonce you generated in the previous step. }); </script>احصل على رمز Apple ID المميّز من استجابة المصادقة التي تم إرسالها من جهة الخادم:
app.post('/redirect', (req, res) => { const savedState = req.cookies.__session; const code = req.body.code; const state = req.body.state; const appleIdToken = req.body.id_token; if (savedState !== state || !code) { res.status(403).send('403: Permission denied'); } else { // Sign in with Firebase using appleIdToken. (See next step). } });
يمكنك أيضًا الاطّلاع على إعداد صفحة الويب لميزة "تسجيل الدخول باستخدام Apple" (Configuring Your Webpage for Sign In with Apple).
بعد الحصول على رمز Apple ID المميز للمستخدم، استخدِمه لإنشاء عنصر بيانات اعتماد، ثم سجِّل دخول المستخدم باستخدام بيانات الاعتماد:
Web
import { getAuth, signInWithCredential, OAuthProvider } from "firebase/auth"; const auth = getAuth(); // Build Firebase credential with the Apple ID token. const provider = new OAuthProvider('apple.com'); const authCredential = provider.credential({ idToken: appleIdToken, rawNonce: unhashedNonce, }); // Sign in with credential form the Apple user. signInWithCredential(auth, authCredential) .then((result) => { // User signed in. }) .catch((error) => { // An error occurred. If error.code == 'auth/missing-or-invalid-nonce', // make sure you're sending the SHA256-hashed nonce as a hex string // with your request to Apple. console.log(error); });
Web
// Build Firebase credential with the Apple ID token. const provider = new firebase.auth.OAuthProvider('apple.com'); const authCredential = provider.credential({ idToken: appleIdToken, rawNonce: unhashedNonce, }); // Sign in with credential form the Apple user. firebase.auth().signInWithCredential(authCredential) .then((result) => { // User signed in. }) .catch((error) => { // An error occurred. If error.code == 'auth/missing-or-invalid-nonce', // make sure you're sending the SHA256-hashed nonce as a hex string // with your request to Apple. console.log(error); });
الخطوات التالية
بعد أن يسجّل المستخدم الدخول للمرة الأولى، يتم إنشاء حساب مستخدم جديد وربطه ببيانات الاعتماد التي استخدمها لتسجيل الدخول، أي اسم المستخدم وكلمة المرور أو رقم الهاتف أو معلومات مزوّد المصادقة. يتم تخزين هذا الحساب الجديد كجزء من مشروع Firebase، ويمكن استخدامه لتحديد هوية المستخدم في كل تطبيق في مشروعك، بغض النظر عن كيفية تسجيل المستخدم الدخول.
-
في تطبيقاتك، الطريقة المقترَحة لمعرفة حالة مصادقة المستخدم هي ضبط مراقِب على عنصر
Auth. يمكنك بعد ذلك الحصول على معلومات الملف الشخصي الأساسية للمستخدم من الكائنUser. يُرجى الاطّلاع على إدارة المستخدمين. في قواعد الأمان في Firebase Realtime Database وCloud Storage، يمكنك الحصول على رقم تعريف المستخدم الفريد للمستخدم الذي سجّل الدخول من المتغيّر
auth، واستخدامه للتحكّم في البيانات التي يمكن للمستخدم الوصول إليها.
يمكنك السماح للمستخدمين بتسجيل الدخول إلى تطبيقك باستخدام عدة موفّري مصادقة من خلال ربط بيانات اعتماد موفّر المصادقة بحساب مستخدم حالي.
لتسجيل خروج مستخدم، يمكنك استدعاء
signOut:
Web
import { getAuth, signOut } from "firebase/auth"; const auth = getAuth(); signOut(auth).then(() => { // Sign-out successful. }).catch((error) => { // An error happened. });
Web
firebase.auth().signOut().then(() => { // Sign-out successful. }).catch((error) => { // An error happened. });