توسيع نطاق مصادقة Firebase باستخدام وظائف الحظر

تتيح لك وظائف الحظر تنفيذ رمز مخصّص يُعدّل نتيجة تسجيل أحد المستخدمين أو تسجيل الدخول إلى تطبيقك. على سبيل المثال، يمكنك منع أحد المستخدمين من المصادقة إذا لم يستوفِ معايير معيّنة، أو تعديل معلومات أحد المستخدمين قبل إعادتها إلى تطبيق العميل.

قبل البدء

لاستخدام وظائف الحظر، يجب ترقية مشروعك على Firebase إلى الإصدار Firebase Authentication with Identity Platform. إذا لم تكن قد أجريت الترقية من قبل، عليك إجراء ذلك أولاً.

فهم دوال الحظر

ويمكنك تسجيل وظائف الحظر لحدثَين:

• beforeCreate: إجراءات يتم تشغيلها قبل حفظ مستخدم جديد في Firebase Authentication وقبل إرجاع رمز مميز إلى التطبيق العميل.

• beforeSignIn: يتم تشغيله بعد إثبات صحة بيانات اعتماد المستخدم، ولكن قبل أن يعرض Firebase Authentication رمزًا مميزًا للمعرّف إلى تطبيق العميل. في حال حذف أن تطبيقك يستخدم مصادقة متعددة العوامل، عندما يتحقق المستخدم من عامله الثاني. يُرجى العلم أنّ إنشاء مستخدم جديد يؤدي أيضًا إلى بدء beforeSignIn، بالإضافة إلى beforeCreate.

يجب أخذ النقاط التالية في الاعتبار عند استخدام دوال الحظر:

• يجب أن تستجيب الدالة في غضون 7 ثوانٍ. بعد 7 ثوانٍ، تعرض الدالة Firebase Authentication خطأً، ويتعذّر إتمام عملية العميل.

• يتم تمرير رموز استجابة HTTP غير 200 إلى تطبيقات العميل. التأكد من يتعامل رمز العميل مع أي أخطاء يمكن أن تعرضها الدالة.

• تنطبق الدوال على جميع المستخدمين في مشروعك، بما في ذلك أي مستخدمين مضمنة في المستأجر. يوفّر Firebase Authentication معلومات عن المستخدمين لوظيفة حسابك، بما في ذلك أي مستأجرين ينتمون إليهم، حتى تتمكّن من الردّ وفقًا لذلك.

• يؤدي ربط موفِّر هوية آخر بحساب إلى إعادة تشغيل أي موفّر هوية مسجَّل beforeSignIn.

• لا تؤدي المصادقة المجهولة والمخصّصة إلى تفعيل دوال الحظر.

تفعيل دالة حظر

لإدراج الرمز المخصّص في مسارات مصادقة المستخدمين، فعِّل ميزة الحظر الأخرى. بعد نشر دوال الحظر، يجب أن يكون الرمز المخصّص سيكتمل بنجاح للمصادقة وإنشاء المستخدم.

تنشر دالة حظر بالطريقة نفسها التي تنشر بها أي دالة. (يُرجى الاطّلاع على صفحة Cloud Functions البدء للحصول على التفاصيل). وباختصار:

1. اكتب Cloud Functions التي تعالج الحدث beforeCreate أو الحدث beforeSignIn أو كليهما.

   على سبيل المثال، للبدء، يمكنك إضافة دوال No-op التالية إلى index.js:

   const functions = require('firebase-functions/v1');
   
   exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
     // TODO
   });
   
   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     // TODO
   });
   

   لقد أغفلت الأمثلة أعلاه تنفيذ منطق المصادقة المخصّص. اطّلِع على الأقسام التالية للتعرّف على كيفية تنفيذ وظائف الحظر واطلاع على السيناريوهات الشائعة للحصول على أمثلة محدّدة.

2. نشر الدوال باستخدام واجهة سطر الأوامر Firebase:

   firebase deploy --only functions
   

   يجب إعادة نشر الدوال في كل مرة تقوم فيها بتحديثها.

الحصول على معلومات المستخدم والسياق

يعرض الحدثان beforeSignIn وbeforeCreate User وEventContext. الكائنات التي تحتوي على معلومات حول تسجيل دخول المستخدم. استخدِم هذه القيم. في التعليمات البرمجية لتحديد ما إذا كان يجب السماح بمتابعة العملية.

للحصول على قائمة بالسمات المتاحة في عنصر User، اطّلِع على مرجع واجهة برمجة التطبيقات UserRecord.

يحتوي عنصر EventContext على السمات التالية:

حظر التسجيل أو تسجيل الدخول

لحظر عملية تسجيل أو محاولة تسجيل دخول، يُرجى وضع HttpsError في الأخرى. على سبيل المثال:

throw new functions.auth.HttpsError('permission-denied');

يسرد الجدول التالي الأخطاء التي يمكنك إثارتها، إلى جانب رسالة الخطأ التلقائية:

يمكنك أيضًا تحديد رسالة خطأ مخصَّصة:

throw new functions.auth.HttpsError('permission-denied', 'Unauthorized request origin!');

يوضّح المثال التالي كيفية حظر المستخدمين الذين لا ينتمون إلى نطاق معيّن من التسجيل في تطبيقك:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  // (If the user is authenticating within a tenant context, the tenant ID can be determined from
  // user.tenantId or from context.resource, e.g. 'projects/project-id/tenant/tenant-id-1')

  // Only users of a specific domain can sign up.
  if (user.email.indexOf('@acme.com') === -1) {
    throw new functions.auth.HttpsError('invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

بغض النظر عمّا إذا كنت تستخدم رسالة تلقائية أو مخصَّصة تلفّ الدالة Cloud Functions الخطأ وتعيده إلى العميل على أنّه خطأ داخلي. على سبيل المثال:

throw new functions.auth.HttpsError('invalid-argument', `Unauthorized email [email protected]}`);

من المفترض أن يرصد تطبيقك الخطأ، وأن يتعامل معه وفقًا لذلك. على سبيل المثال:

// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().createUserWithEmailAndPassword('johndoe@example.com', 'password')
  .then((result) => {
    result.user.getIdTokenResult()
  })
  .then((idTokenResult) => {
    console.log(idTokenResult.claim.admin);
  })
  .catch((error) => {
    if (error.code !== 'auth/internal-error' && error.message.indexOf('Cloud Function') !== -1) {
      // Display error.
    } else {
      // Registration succeeds.
    }
  });

تعديل مستخدم

بدلاً من حظر محاولة التسجيل أو تسجيل الدخول، يمكنك السماح باستمرار العملية، ولكن مع تعديل عنصر User الذي يتم حفظه في قاعدة بيانات Firebase Authentication وإعادته إلى العميل.

لتعديل مستخدم، يمكنك إرجاع كائن من معالج الأحداث يحتوي على الحقول المطلوب تعديلها. يمكنك تعديل الحقول التالية:

• displayName
• disabled
• emailVerified
• photoUrl
• customClaims
• sessionClaims (beforeSignIn فقط)

باستثناء sessionClaims، يتم حفظ جميع الحقول المعدَّلة في قاعدة بيانات Firebase Authentication، ما يعني أنّه يتم تضمينها في رمز هِتم الاستجابة وتبقى محفوظة بين جلسات المستخدمين.

يوضّح المثال التالي كيفية ضبط اسم معروض تلقائي:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  return {
    // If no display name is provided, set it to "Guest".
    displayName: user.displayName || 'Guest';
  };
});

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

على سبيل المثال، إذا تم ضبط أي سمة sessionClaims، سيعرض beforeSignIn القيمة. بأي مطالبة بـ beforeCreate، وسيتم دمجها. عند دمجهما، إذا كان مفتاح sessionClaims يتطابق مع مفتاح في customClaims، سيتم استبدال customClaims المطابق في مطالبات الرموز المميّزة باستخدام مفتاحsessionClaims . ومع ذلك، سيظل مفتاح customClaims الذي تم إخفاؤه مستمرًا في قاعدة البيانات للطلبات المستقبلية.

بيانات اعتماد OAuth والبيانات المتوافقة

يمكنك تمرير بيانات اعتماد OAuth والبيانات إلى وظائف الحظر من مقدمي هوية مختلفين. يوضح الجدول التالي بيانات الاعتماد والبيانات متاحة لكل موفّر هوية:

إعادة تحميل الرموز المميّزة

لاستخدام رمز مميز للتحديث في دالة حظر، يجب أولاً تحديد مربّع الاختيار في صفحة وظائف الحظر في وحدة تحكُّم Firebase.

لن يعرض أي موفِّر للهوية الرموز المميّزة لإعادة التحميل أثناء تسجيل الدخول. مباشرةً باستخدام بيانات اعتماد OAuth، مثل الرمز المميز للمعرف أو رمز الدخول. في هذه الدورة، سيتم تمرير بيانات اعتماد OAuth نفسها من جهة العميل إلى دليل الأخرى.

تصف الأقسام التالية كل أنواع مزوّدي الهوية ومقاييس الاعتماد والبيانات المتوافقة معهم.

موفِّرو OIDC العامون

عندما يسجّل المستخدم الدخول باستخدام موفِّر OIDC عام، ستظهر بيانات الاعتماد التالية سيتم تمريره:

• معرّف الرمز المميّز: يتم توفيره في حال اختيار عملية id_token.
• رمز الدخول: يتم توفيره عند اختيار مسار الرمز. لاحظ أن الكود البيانات المتاحة حاليًا فقط عبر واجهة برمجة تطبيقات REST.
• الرمز المميّز لإعادة التحميل: يتم توفيره في حال نطاق offline_access .

مثال:

const provider = new firebase.auth.OAuthProvider('oidc.my-provider');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);

Google

عندما يسجّل أحد المستخدمين الدخول باستخدام حساب Google، سيتم تمرير بيانات الاعتماد التالية:

• الرمز المميّز للمعرّف
• رمز الدخول
• الرمز المميّز لإعادة التحميل: لا يتم تقديمه إلا إذا كانت المَعلمات المخصّصة التالية هي تم طلبه:
  • access_type=offline
  • prompt=consent، إذا وافق المستخدم سابقًا ولم يكن تم طلب نطاق جديد

مثال:

const provider = new firebase.auth.GoogleAuthProvider();
provider.setCustomParameters({
  'access_type': 'offline',
  'prompt': 'consent'
});
firebase.auth().signInWithPopup(provider);

مزيد من المعلومات حول الرموز المميّزة لتحديث Google

Facebook

عندما يسجّل أحد المستخدمين الدخول من خلال Facebook، سيتم اجتياز بيانات الاعتماد التالية:

• رمز الدخول: يتم عرض رمز دخول يمكن استبداله برمز دخول آخر. اطّلِع على مزيد من المعلومات عن الأنواع المختلفة من الرموز المميّزة للوصول التي يتيح استخدامها Facebook وكيفية استبدالها ب رموز مميّزة صالحة لفترة طويلة.

GitHub

عندما يسجّل المستخدم الدخول من خلال GitHub، سيتم اجتياز بيانات الاعتماد التالية:

• رمز الدخول: لا تنتهي صلاحيته ما لم يتم إبطاله.

Microsoft

عندما يسجّل أحد المستخدمين الدخول باستخدام Microsoft، سيتم تمرير بيانات الاعتماد التالية:

• الرمز المميّز للتعريف
• رمز الدخول
• الرمز المميز لإعادة التحميل: يتم تمريره إلى دالة الحظر إذا كانت نطاق offline_access .

مثال:

const provider = new firebase.auth.OAuthProvider('microsoft.com');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);

Yahoo

عندما يسجّل أحد المستخدمين الدخول باستخدام Yahoo، سيتم تمرير بيانات الاعتماد التالية بدون أي مَعلمات أو نطاقات مخصّصة:

• الرمز المميّز للتعريف
• رمز الدخول
• إعادة تحميل الرمز المميّز

LinkedIn

عندما يسجّل أحد المستخدمين الدخول من خلال LinkedIn، سيتم تمرير بيانات الاعتماد التالية:

• رمز الدخول

Apple

عندما يسجّل المستخدم الدخول باستخدام Apple، سيتم تمرير بيانات الاعتماد التالية بدون أي مَعلمات أو نطاقات مخصّصة:

• الرمز المميّز للمعرّف
• رمز الدخول
• إعادة تحميل الرمز المميّز

السيناريوهات الشائعة

توضح الأمثلة التالية بعض حالات الاستخدام الشائعة لدوال الحظر:

السماح بالتسجيل من نطاق معيّن فقط

يوضح المثال التالي كيفية منع المستخدمين الذين ليسوا جزءًا من نطاق واحد (example.com) بعد التسجيل باستخدام تطبيقك:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (!user.email || user.email.indexOf('@example.com') === -1) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

حظر تسجيل المستخدمين الذين لديهم عناوين بريد إلكتروني لم يتم التحقق منها

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

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unverified email "${user.email}"`);
  }
});

طلب إثبات ملكية عنوان البريد الإلكتروني عند التسجيل

يوضّح المثال التالي كيفية مطالبة المستخدم بإثبات ملكية بريده الإلكتروني بعد التسجيل:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  const locale = context.locale;
  if (user.email && !user.emailVerified) {
    // Send custom email verification on sign-up.
    return admin.auth().generateEmailVerificationLink(user.email).then((link) => {
      return sendCustomVerificationEmail(user.email, link, locale);
    });
  }
});

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
 if (user.email && !user.emailVerified) {
   throw new functions.auth.HttpsError(
     'invalid-argument', `"${user.email}" needs to be verified before access is granted.`);
  }
});

التعامل مع رسائل إلكترونية معيّنة لموفّري الهوية على أنّها تم إثبات ملكيتها

يوضّح المثال التالي كيفية التعامل مع عناوين البريد الإلكتروني للمستخدمين من مقدّمي هوية معيّنين على أنّها عناوين تم إثبات ملكيتها:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified && context.eventType.indexOf(':facebook.com') !== -1) {
    return {
      emailVerified: true,
    };
  }
});

حظر تسجيل الدخول من عناوين IP معينة

في ما يلي مثال يوضح كيفية حظر تسجيل الدخول من نطاقات عناوين IP معيّنة:

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
  if (isSuspiciousIpAddress(context.ipAddress)) {
    throw new functions.auth.HttpsError(
      'permission-denied', 'Unauthorized access!');
  }
});

تعيين المطالبات المخصّصة ومطالبات الجلسة

يوضّح المثال التالي كيفية تحديد المطالبات المخصّصة والمطالبات بالجلسة:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (context.credential &&
      context.credential.providerId === 'saml.my-provider-id') {
    return {
      // Employee ID does not change so save in persistent claims (stored in
      // Auth DB).
      customClaims: {
        eid: context.credential.claims.employeeid,
      },
      // Copy role and groups to token claims. These will not be persisted.
      sessionClaims: {
        role: context.credential.claims.role,
        groups: context.credential.claims.groups,
      }
    }
  }
});

تتبُّع عناوين IP لرصد الأنشطة المريبة

يمكنك منع سرقة الرمز المميّز من خلال تتبُّع عنوان IP الذي يسجّل المستخدم الدخول منه، ومقارنته بعنوان IP في الطلبات اللاحقة. إذا لم يطلب الطلب تبدو مريبة — على سبيل المثال، تأتي عناوين IP من مواقع جغرافية المناطق — يمكنك أن تطلب من المستخدم تسجيل الدخول مرة أخرى.

1. استخدِم المطالبات بالجلسة لتتبُّع عنوان IP الذي يسجّل المستخدم الدخول به:

   Node.js

   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     return {
       sessionClaims: {
         signInIpAddress: context.ipAddress,
       },
     };
   });
   

2. عندما يحاول أحد المستخدمين الوصول إلى الموارد التي تتطلب المصادقة مع Firebase Authentication، يُرجى مقارنة عنوان IP في الطلب بعنوان IP المُستخدَم. لتسجيل الدخول:

   Node.js

   app.post('/getRestrictedData', (req, res) => {
     // Get the ID token passed.
     const idToken = req.body.idToken;
     // Verify the ID token, check if revoked and decode its payload.
     admin.auth().verifyIdToken(idToken, true).then((claims) => {
       // Get request IP address
       const requestIpAddress = req.connection.remoteAddress;
       // Get sign-in IP address.
       const signInIpAddress = claims.signInIpAddress;
       // Check if the request IP address origin is suspicious relative to
       // the session IP addresses. The current request timestamp and the
       // auth_time of the ID token can provide additional signals of abuse,
       // especially if the IP address suddenly changed. If there was a sudden
       // geographical change in a short period of time, then it will give
       // stronger signals of possible abuse.
       if (!isSuspiciousIpAddressChange(signInIpAddress, requestIpAddress)) {
         // Suspicious IP address change. Require re-authentication.
         // You can also revoke all user sessions by calling:
         // admin.auth().revokeRefreshTokens(claims.sub).
         res.status(401).send({error: 'Unauthorized access. Please login again!'});
       } else {
         // Access is valid. Try to return data.
         getData(claims).then(data => {
           res.end(JSON.stringify(data);
         }, error => {
           res.status(500).send({ error: 'Server error!' })
         });
       }
     });
   });
   

فحص صور المستخدمين

يوضّح المثال التالي كيفية تنقيح بيانات المستخدمين صور الملف الشخصي:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.photoURL) {
    return isPhotoAppropriate(user.photoURL)
      .then((status) => {
        if (!status) {
          // Sanitize inappropriate photos by replacing them with guest photos.
          // Users could also be blocked from sign-up, disabled, etc.
          return {
            photoUrl: PLACEHOLDER_GUEST_PHOTO_URL,
          };
        }
      });
});

لمعرفة المزيد من المعلومات عن كيفية رصد الصور وتعقيمها، يُرجى الاطّلاع على مستندات Cloud Vision

الوصول إلى بيانات اعتماد OAuth لموفِّر هوية المستخدم

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

const {OAuth2Client} = require('google-auth-library');
const {google} = require('googleapis');
// ...
// Initialize Google OAuth client.
const keys = require('./oauth2.keys.json');
const oAuth2Client = new OAuth2Client(
  keys.web.client_id,
  keys.web.client_secret
);

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (context.credential &&
      context.credential.providerId === 'google.com') {
    // Store the refresh token for later offline use.
    // These will only be returned if refresh tokens credentials are included
    // (enabled by Cloud console).
    return saveUserRefreshToken(
        user.uid,
        context.credential.refreshToken,
        'google.com'
      )
      .then(() => {
        // Blocking the function is not required. The function can resolve while
        // this operation continues to run in the background.
        return new Promise((resolve, reject) => {
          // For this operation to succeed, the appropriate OAuth scope should be requested
          // on sign in with Google, client-side. In this case:
          // https://www.googleapis.com/auth/calendar
          // You can check granted_scopes from within:
          // context.additionalUserInfo.profile.granted_scopes (space joined list of scopes).

          // Set access token/refresh token.
          oAuth2Client.setCredentials({
            access_token: context.credential.accessToken,
            refresh_token: context.credential.refreshToken,
          });
          const calendar = google.calendar('v3');
          // Setup Onboarding event on user's calendar.
          const event = {/** ... */};
          calendar.events.insert({
            auth: oauth2client,
            calendarId: 'primary',
            resource: event,
          }, (err, event) => {
            // Do not fail. This is a best effort approach.
            resolve();
          });
      });
    })
  }
});

تجاهُل بيان reCAPTCHA Enterprise لعملية المستخدم

يوضّح المثال التالي كيفية إلغاء بيان reCAPTCHA Enterprise لمسارات المستخدمين المتوافقة.

يُرجى مراجعة المقالة تفعيل reCAPTCHA Enterprise للاطّلاع على مزيد من المعلومات حول دمج reCAPTCHA Enterprise مع مصادقة Firebase.

يمكن استخدام دوال الحظر للسماح بتدفقات أو حظرها استنادًا إلى عوامل مخصَّصة، وبالتالي إلغاء النتيجة المقدَّمة من reCAPTCHA Enterprise.

 const {
   auth,
 } = require("firebase-functions/v1");

exports.checkrecaptchaV1 = auth.user().beforeSignIn((userRecord, context) => {
 // Allow users with a specific email domain to sign in regardless of their recaptcha score.
 if (userRecord.email && userRecord.email.indexOf('@acme.com') === -1) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Allow users to sign in with recaptcha score greater than 0.5
 if (context.additionalUserInfo.recaptchaScore > 0.5) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Block all others.
 return {
   recaptchaActionOverride: 'BLOCK',
 };
});