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

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

قبل البدء

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

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

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

• ‫beforeCreate: يتم تشغيله قبل حفظ مستخدم جديد في قاعدة بيانات Firebase Authentication، وقبل عرض رمز مميّز في تطبيق العميل.

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

• ‫beforeEmail (Node.js فقط): يتم تشغيل هذه العوامل قبل إرسال رسالة إلكترونية إلى المستخدم (على سبيل المثال،
  رسالة إلكترونية لتسجيل الدخول أو إعادة ضبط كلمة المرور).

• ‫beforeSms (Node.js فقط): يتم تشغيله قبل إرسال رسالة SMS إلى مستخدم، وذلك في حالات مثل مصادقة متعدّدة العوامل.

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

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

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

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

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

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

نشر وظيفة حظر

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

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

1. اكتب دالة تعالج الحدث المستهدَف.

   على سبيل المثال، للبدء، يمكنك إضافة دالة لا تؤدي إلى أيّ إجراء مثل التالية إلى index.js:

   const functions = require('firebase-functions/v1');
   
   exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
     // TODO
   });
   
   The above example has omitted the implementation of custom auth logic. See
   the following sections to learn how to implement your blocking functions and
   [Common scenarios](#common-scenarios) for specific examples.
   

1. يمكنك نشر دوالّك باستخدام 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 user@evil.com}`);

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

// 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 API.
• رمز مميّز لإعادة التحميل: يتم توفيره في حال اختيار نطاق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 Authentication.

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

const functions = require("firebase-functions/v1");
exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
 if (
   context.smsType === "SIGN_IN_OR_SIGN_UP" &&
   context.additionalUserInfo.phoneNumber.includes('+91')
 ) {
   return {
     recaptchaActionOverride: "ALLOW",
   };
 }

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

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