טריגרים לחסימת אימות

פונקציות חסימה מאפשרות להריץ קוד מותאם אישית שמשנה את התוצאה של רישום משתמש או כניסה של משתמש לאפליקציה. לדוגמה, אפשר למנוע ממשתמש לבצע אימות אם הוא לא עומד בקריטריונים מסוימים, או לעדכן את הפרטים של משתמש לפני שהם מוחזרים לאפליקציית הלקוח.

לפני שמתחילים

כדי להשתמש בפונקציות חסימה צריך לשדרג את פרויקט 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 פונקציה מסוג no-op, כמו בדוגמה הבאה:

   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. פורסים את הפונקציות באמצעות CLI של Firebase:

   firebase deploy --only functions
   

   צריך לפרוס מחדש את הפונקציות בכל פעם שמעדכנים אותן.

אחזור פרטי משתמשים והקשר

האירועים beforeSignIn ו-beforeCreate מספקים אובייקטים מסוג User ו-EventContext שמכילים מידע על המשתמש שנכנס לחשבון. אפשר להשתמש בערכים האלה בקוד כדי לקבוע אם לאפשר לפעולה להמשיך.

רשימה של המאפיינים הזמינים באובייקט User מפורטת בחומר העזר בנושא API של 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';
  };
});

אם רושמים handler של אירועים גם ל-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.
• אסימון גישה: מסופק אם בוחרים בתהליך הקוד. חשוב לזכור שכרגע יש תמיכה בזרימת הקוד רק דרך ה-API ל-REST.
• Refresh token: אסימון שמסופק אם נבחר ההיקף offline_access.

דוגמה:

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

Google

כשמשתמש נכנס באמצעות חשבון Google, פרטי הכניסה הבאים מועברים:

• אסימון מזהה
• אסימון גישה
• Refresh token: הנתון הזה מסופק רק אם מבקשים את הפרמטרים המותאמים אישית הבאים:
  • 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, ולהשתמש בו כדי לבצע קריאה לממשקי ה-API של יומן 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 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',
 }
});