محرک‌های مسدودکننده تأیید هویت (نسل اول)

توابع مسدودکننده به شما امکان می‌دهند کد سفارشی را اجرا کنید که نتیجه ثبت نام یا ورود کاربر به برنامه شما را تغییر می‌دهد. به عنوان مثال، می‌توانید در صورت عدم رعایت معیارهای خاص، از احراز هویت کاربر جلوگیری کنید، یا اطلاعات کاربر را قبل از بازگرداندن آن به برنامه کلاینت خود به‌روزرسانی کنید.

قبل از اینکه شروع کنی

برای استفاده از توابع مسدودکننده، باید پروژه Firebase خود را به Firebase Authentication with Identity Platform ارتقا دهید. اگر قبلاً آن را ارتقا نداده‌اید، ابتدا این کار را انجام دهید.

درک توابع مسدود کننده

می‌توانید توابع مسدودکننده را برای این رویدادها ثبت کنید:

• beforeCreate : قبل از ذخیره شدن یک کاربر جدید در پایگاه داده Firebase Authentication و قبل از بازگرداندن توکن به برنامه کلاینت شما، فعال می‌شود.

• beforeSignIn : پس از تأیید اعتبار کاربر فعال می‌شود، اما قبل از Firebase Authentication یک توکن شناسه به برنامه کلاینت شما برمی‌گرداند. اگر برنامه شما از تأیید اعتبار چند عاملی استفاده می‌کند، این تابع پس از تأیید عامل دوم توسط کاربر فعال می‌شود. توجه داشته باشید که ایجاد یک کاربر جدید علاوه بر beforeCreate ، beforeSignIn نیز فعال می‌کند.

• beforeEmail (فقط Node.js) : قبل از ارسال ایمیل (برای مثال،) فعال می‌شود.
  ایمیل ورود به سیستم یا بازنشانی رمز عبور) برای کاربر ارسال می‌شود.

• beforeSms (فقط Node.js) : قبل از ارسال پیامک به کاربر، برای مواردی مانند احراز هویت چند عاملی، فعال می‌شود.

هنگام استفاده از توابع مسدود کننده، موارد زیر را در نظر داشته باشید:

• تابع شما باید ظرف ۷ ثانیه پاسخ دهد. پس از ۷ ثانیه، Firebase Authentication خطایی برمی‌گرداند و عملیات کلاینت با شکست مواجه می‌شود.

• کدهای پاسخ HTTP غیر از 200 به برنامه‌های کلاینت شما ارسال می‌شوند. مطمئن شوید که کد کلاینت شما هرگونه خطایی را که تابع شما می‌تواند برگرداند، مدیریت می‌کند.

• توابع برای همه کاربران پروژه شما، از جمله هر کاربر موجود در یک مستاجر ، اعمال می‌شوند. Firebase Authentication اطلاعاتی در مورد کاربران تابع شما، از جمله هر مستاجری که به آن تعلق دارند، ارائه می‌دهد، بنابراین می‌توانید بر اساس آن پاسخ دهید.

• پیوند دادن یک ارائه‌دهنده هویت دیگر به یک حساب کاربری، هرگونه تابع beforeSignIn ثبت‌شده را دوباره فعال می‌کند.

• احراز هویت ناشناس و سفارشی، توابع مسدودسازی را فعال نمی‌کنند.

یک تابع مسدودکننده مستقر کنید

برای وارد کردن کد سفارشی خود در جریان‌های احراز هویت کاربر، توابع مسدودکننده را مستقر کنید. پس از استقرار توابع مسدودکننده، کد سفارشی شما باید با موفقیت تکمیل شود تا احراز هویت و ایجاد کاربر با موفقیت انجام شود.

شما یک تابع مسدودکننده را به همان روشی که هر تابع دیگری را مستقر می‌کنید، مستقر می‌کنید. (برای جزئیات بیشتر به صفحه شروع به کار Cloud Functions مراجعه کنید.) به طور خلاصه:

1. تابعی بنویسید که رویداد مورد نظر را مدیریت کند.

   برای مثال، برای شروع، می‌توانید یک تابع no-op مانند زیر به 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 CLI مستقر کنید:

   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}"`);
  }
});

صرف نظر از اینکه از پیام پیش‌فرض یا سفارشی استفاده می‌کنید، توابع ابری خطا را پوشش می‌دهند و آن را به عنوان یک خطای داخلی به کلاینت برمی‌گردانند. برای مثال:

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 ذخیره شده و به کلاینت بازگردانده می‌شود، تغییر دهید.

برای تغییر یک کاربر، یک شیء از event handler خود که حاوی فیلدهای مورد نظر برای تغییر است، برگردانید. می‌توانید فیلدهای زیر را تغییر دهید:

• 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 یک event handler ثبت می‌کنید، توجه داشته باشید که beforeSignIn پس از beforeCreate اجرا می‌شود. فیلدهای کاربری که در beforeCreate به‌روزرسانی شده‌اند، در beforeSignIn قابل مشاهده هستند. اگر در هر دو رویداد handler، فیلدی غیر از sessionClaims تنظیم کنید، مقدار تنظیم شده در beforeSignIn روی مقدار تنظیم شده در beforeCreate بازنویسی می‌شود. فقط برای sessionClaims ، آنها به توکن‌های درخواستی جلسه فعلی منتقل می‌شوند، اما در پایگاه داده ذخیره یا نگهداری نمی‌شوند.

برای مثال، اگر هر sessionClaims تنظیم شده باشد، beforeSignIn آنها را به همراه هرگونه Claim beforeCreate برمی‌گرداند و ادغام می‌شوند. وقتی ادغام می‌شوند، اگر کلید sessionClaims با کلیدی در customClaims مطابقت داشته باشد، customClaims منطبق در ادعاهای توکن توسط کلید sessionClaims بازنویسی می‌شود. با این حال، کلید customClaims overwitten همچنان برای درخواست‌های آینده در پایگاه داده باقی خواهد ماند.

اعتبارنامه‌ها و داده‌های OAuth پشتیبانی‌شده

شما می‌توانید اعتبارنامه‌ها و داده‌های OAuth را به توابع مسدودکننده از ارائه‌دهندگان هویت مختلف ارسال کنید. جدول زیر نشان می‌دهد که چه اعتبارنامه‌ها و داده‌هایی برای هر ارائه‌دهنده هویت پشتیبانی می‌شوند:

توکن‌های تازه‌سازی

برای استفاده از توکن رفرش در یک تابع مسدودکننده، ابتدا باید کادر انتخاب را در صفحه توابع مسدودکننده کنسول Firebase انتخاب کنید.

هنگام ورود مستقیم به سیستم با یک اعتبارنامه OAuth، مانند یک توکن شناسه یا توکن دسترسی، هیچ ارائه‌دهنده هویتی توکن‌های Refresh را برنمی‌گرداند. در این شرایط، همان اعتبارنامه 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);

گوگل

وقتی کاربری با گوگل وارد سیستم می‌شود، اطلاعات زیر ارسال می‌شود:

• توکن شناسایی
• توکن دسترسی
• نشانه به‌روزرسانی : فقط در صورتی ارائه می‌شود که پارامترهای سفارشی زیر درخواست شوند:
  • access_type=offline
  • prompt=consent ، اگر کاربر قبلاً رضایت داده باشد و هیچ محدوده جدیدی درخواست نشده باشد

مثال:

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

درباره توکن‌های به‌روزرسانی گوگل بیشتر بدانید.

فیسبوک

وقتی کاربری با فیس‌بوک وارد سیستم می‌شود، اطلاعات زیر منتقل می‌شود:

• توکن دسترسی : یک توکن دسترسی برگردانده می‌شود که می‌تواند با توکن دسترسی دیگری مبادله شود. درباره انواع مختلف توکن‌های دسترسی پشتیبانی شده توسط فیس‌بوک و نحوه مبادله آنها با توکن‌های با طول عمر بالا بیشتر بدانید.

گیت‌هاب

وقتی کاربری با GitHub وارد سیستم می‌شود، اعتبارنامه زیر ارسال می‌شود:

• توکن دسترسی : تا زمانی که لغو نشود، منقضی نمی‌شود.

مایکروسافت

وقتی کاربری با مایکروسافت وارد سیستم می‌شود، اطلاعات احراز هویت زیر ارسال می‌شود:

• توکن شناسایی
• توکن دسترسی
• توکن به‌روزرسانی : در صورت انتخاب محدوده‌ی offline_access ، به تابع مسدودکننده ارسال می‌شود.

مثال:

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

یاهو

وقتی کاربری با یاهو وارد سیستم می‌شود، اطلاعات احراز هویت زیر بدون هیچ پارامتر یا محدوده سفارشی ارسال می‌شود:

• توکن شناسایی
• توکن دسترسی
• توکن تازه‌سازی

لینکدین

وقتی کاربری با لینکدین وارد سیستم می‌شود، اطلاعات زیر به او منتقل می‌شود:

• توکن دسترسی

اپل

وقتی کاربری با اپل وارد سیستم می‌شود، اطلاعات احراز هویت زیر بدون هیچ پارامتر یا محدوده سفارشی ارسال می‌شود:

• توکن شناسایی
• توکن دسترسی
• توکن تازه‌سازی

سناریوهای رایج

مثال‌های زیر برخی از موارد استفاده رایج برای توابع مسدودکننده را نشان می‌دهند:

فقط اجازه ثبت نام از یک دامنه خاص

مثال زیر نحوه جلوگیری از ثبت نام کاربرانی که عضو دامنه 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!');
  }
});

تنظیم ادعاهای سفارشی و جلسه‌ای

مثال زیر نحوه تنظیم custom و session claims را نشان می‌دهد:

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. از session claims برای ردیابی آدرس IP که کاربر با آن وارد سیستم می‌شود استفاده کنید:

   نود جی اس

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

2. وقتی کاربری تلاش می‌کند به منابعی که نیاز به احراز هویت با Firebase Authentication دارند دسترسی پیدا کند، آدرس IP موجود در درخواست را با IP استفاده شده برای ورود به سیستم مقایسه کنید:

   نود جی اس

   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 ارائه‌دهنده هویت کاربر

مثال زیر نحوه دریافت یک توکن به‌روزرسانی برای کاربری که با حساب گوگل وارد سیستم شده است و استفاده از آن برای فراخوانی APIهای تقویم گوگل را نشان می‌دهد. توکن به‌روزرسانی برای دسترسی آفلاین ذخیره می‌شود.

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 با احراز هویت Firebase، به بخش «فعال کردن reCAPTCHA Enterprise» مراجعه کنید.

توابع مسدودکننده می‌توانند برای مجاز یا مسدود کردن جریان‌ها بر اساس عوامل سفارشی استفاده شوند و در نتیجه نتیجه ارائه شده توسط 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',
 }
});