運用封鎖函式擴充 Firebase 驗證

封鎖函式可讓您執行自訂程式碼，藉此修改使用者註冊或登入應用程式的結果。舉例來說，您可以防止使用者在未符合特定條件時進行驗證，或是在將使用者資訊傳回至用戶端應用程式前更新該資訊。

事前準備

如要使用阻斷函式，您必須將 Firebase 專案升級至 Firebase Authentication with Identity Platform。如果尚未升級，請先升級。

瞭解封鎖函式

您可以為下列事件註冊封鎖函式：

• beforeCreate：在新使用者儲存至 Firebase Authentication 資料庫，以及權杖傳回至用戶端應用程式之前觸發。

• beforeSignIn：在使用者驗證憑證後，但在 Firebase Authentication 將 ID 權杖傳回至用戶端應用程式之前觸發。如果應用程式使用多重驗證，則在使用者驗證第二因素後觸發此函式。請注意，除了 beforeCreate 外，建立新使用者也會觸發 beforeSignIn。

• beforeEmail (僅限 Node.js)：在向使用者傳送電子郵件 (例如
  登入或重設密碼電子郵件) 之前觸發。

• beforeSms (僅限 Node.js)：在傳送簡訊給使用者之前觸發，例如多重驗證。

使用阻斷函式時，請注意下列事項：

• 您的函式必須在 7 秒內回應。7 秒後，Firebase Authentication 會傳回錯誤，且用戶端作業會失敗。

• 除了 200 以外的 HTTP 回應碼會傳遞至用戶端應用程式。請確認您的用戶端程式碼可處理函式傳回的任何錯誤。

• 函式會套用至專案中的所有使用者，包括任何租戶中包含的使用者。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 CLI 部署函式：

   firebase deploy --only functions
   

   每次更新函式時，都必須重新部署函式。

取得使用者和內容資訊

beforeSignIn 和 beforeCreate 事件會提供 User 和 EventContext 物件，其中包含使用者登入的相關資訊。您可以在程式碼中使用這些值，判斷是否允許作業繼續執行。

如需 User 物件上可用的屬性清單，請參閱 UserRecord API 參考資料。

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.
    }
  });

修改使用者

您可以允許作業繼續進行，但修改儲存在 Firebase Authentication 資料庫中並傳回至用戶端的 User 物件，而非封鎖註冊或登入嘗試。

如要修改使用者，請從事件處理常式傳回物件，其中包含要修改的欄位。您可以修改下列欄位：

• 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 會將這些 sessionClaims 與任何 beforeCreate 權利要求一併傳回，並進行合併。在合併時，如果 sessionClaims 鍵與 customClaims 中的鍵相符，系統會在權杖宣告中，將相符的 customClaims 覆寫為 sessionClaims 鍵。不過，覆寫的 customClaims 鍵仍會保留在資料庫中，供日後要求使用。

支援的 OAuth 憑證和資料

您可以將 OAuth 憑證和資料傳遞至來自不同身分識別提供者的封鎖函式。下表列出各個身分提供者支援的憑證和資料：

重新整理權杖

如要在阻斷函式中使用重新整理權杖，您必須先在 Firebase 主控台的「阻斷函式」頁面上選取核取方塊。

直接使用 OAuth 憑證 (例如 ID 權杖或存取權杖) 登入時，任何身分識別提供者都不會傳回更新權杖。在這種情況下，相同的用戶端 OAuth 憑證會傳遞至封鎖函式。

以下各節將說明各個身分識別工具類型，以及這些類型支援的憑證和資料。

一般 OIDC 供應商

使用者透過一般 OIDC 提供者登入時，系統會傳遞下列憑證：

• ID 權杖：如果選取 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 登入時，系統會傳遞下列憑證：

• ID 權杖
• 存取權杖
• 重新整理權杖：只有在要求下列自訂參數時才會提供：
  • 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 登入時，系統會傳遞下列憑證：

• ID 權杖
• 存取權杖
• 重新整理權杖：如果選取 offline_access 範圍，就會傳遞至封鎖函式。

範例：

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

Yahoo

使用者透過 Yahoo 登入時，系統會傳遞下列憑證，但不會傳遞任何自訂參數或範圍：

• ID 權杖
• 存取權杖
• 更新權杖

LinkedIn

使用者透過 LinkedIn 登入時，系統會傳遞下列憑證：

• 存取權杖

Apple

使用者透過 Apple 登入時，系統會傳遞下列憑證，但不會傳遞任何自訂參數或範圍：

• ID 權杖
• 存取權杖
• 更新權杖

常見情境

以下範例說明阻斷函式的常見用途：

只允許特定網域的註冊

以下範例說明如何防止未屬於 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 日曆 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',
 }
});