عوامل تشغيل حظر المصادقة

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

قبل البدء

لاستخدام وظائف الحظر، يجب ترقية مشروع 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',
 }
});