使用 FirebaseUI 建立登入頁面

如要搭配 Identity-Aware Proxy (IAP) 使用外部身分，應用程式需要登入頁面。IAP 會將使用者重新導向至此頁面，要求他們驗證身分，才能存取安全資源。

本文將說明如何使用 FirebaseUI (開放原始碼 JavaScript 程式庫) 建構驗證頁面。FirebaseUI 提供可自訂的元素，有助於減少樣板程式碼，並處理使用者透過各種身分識別資訊提供者登入的流程。

如要加快開始使用，請讓 IAP 代管 UI。這樣一來，您就能嘗試使用外部身分，而不必編寫任何額外的程式碼。如要處理更進階的情況，您也可以自行從頭開始建構登入頁面。這個選項較為複雜，但可讓您全面控管驗證流程和使用者體驗。

事前準備

啟用外部身分，並在設定期間選取「我會自行提供 UI」選項。

安裝程式庫

請安裝 gcip-iap、firebase 和 firebaseui 程式庫。gcip-iap 模組會擷取應用程式、IAP 和 Identity Platform 之間的通訊。firebase 和 firebaseui 程式庫提供驗證 UI 的建構模塊。

npm install firebase --save
npm install firebaseui --save
npm install gcip-iap --save

請注意，您無法使用 CDN 提供 gcip-iap 模組。

接著，您就可以在來源檔案中 import 模組。請使用 SDK 版本適用的正確匯入方式：

gcip-iap v0.1.4 或更早版本

// Import firebase modules.
import * as firebase from "firebase/app";
import "firebase/auth";
// Import firebaseui module.
import * as firebaseui from 'firebaseui'
// Import gcip-iap module.
import * as ciap from 'gcip-iap';

gcip-iap 1.0.0 以上版本

自 1.0.0 版起，gcip-iap 需要 firebase v9 以上版本的對等依附元件。如果您要遷移至 gcip-iap v1.0.0 以上版本，請完成下列操作：

• 請將 package.json 檔案中的 firebase 和 firebaseui 版本分別更新為 v9.6.0 以上版本和 v6.0.0 以上版本。
• 更新 firebase 匯入陳述式，如下所示：

// Import firebase modules.
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
// Import firebaseui module.
import * as firebaseui from 'firebaseui'
// Import gcip-iap module.

不需要額外變更程式碼。

如需其他安裝選項 (包括使用本地化版本的程式庫)，請參閱 GitHub 上的操作說明。

設定應用程式

FirebaseUI 會使用設定物件，指定用於驗證的租用戶和供應者。完整設定可能會非常長，可能會像這樣：

// The project configuration.
const configs = {
  // Configuration for project identified by API key API_KEY1.
  API_KEY1: {
    authDomain: 'project-id1.firebaseapp.com',
    // Decide whether to ask user for identifier to figure out
    // what tenant to select or whether to present all the tenants to select from.
    displayMode: 'optionFirst', // Or identifierFirst
    // The terms of service URL and privacy policy URL for the page
    // where the user select tenant or enter email for tenant/provider
    // matching.
    tosUrl: 'http://localhost/tos',
    privacyPolicyUrl: 'http://localhost/privacypolicy',
    callbacks: {
      // The callback to trigger when the selection tenant page
      // or enter email for tenant matching page is shown.
      selectTenantUiShown: () => {
        // Show title and additional display info.
      },
      // The callback to trigger when the sign-in page
      // is shown.
      signInUiShown: (tenantId) => {
        // Show tenant title and additional display info.
      },
      beforeSignInSuccess: (user) => {
        // Do additional processing on user before sign-in is
        // complete.
        return Promise.resolve(user);
      }
    },
    tenants: {
      // Tenant configuration for tenant ID tenantId1.
      tenantId1: {
        // Full label, display name, button color and icon URL of the
        // tenant selection button. Only needed if you are
        // using the option first option.
        fullLabel: 'ACME Portal',
        displayName: 'ACME',
        buttonColor: '#2F2F2F',
        iconUrl: '<icon-url-of-sign-in-button>',
         // Sign-in providers enabled for tenantId1.
        signInOptions: [
          // Microsoft sign-in.
          {
            provider: 'microsoft.com',
            providerName: 'Microsoft',
            buttonColor: '#2F2F2F',
            iconUrl: '<icon-url-of-sign-in-button>',
            loginHintKey: 'login_hint'
          },
          // Email/password sign-in.
          {
            provider: 'password',
            // Do not require display name on sign up.
            requireDisplayName: false,
            disableSignUp: {
              // Disable user from signing up with email providers.
              status: true,
              adminEmail: '[e-mail]',
              helpLink: 'https://www.example.com/trouble_signing_in'
            }
          },
          // SAML provider. (multiple SAML providers can be passed)
          {
            provider: 'saml.my-provider1',
            providerName: 'SAML provider',
            fullLabel: 'Employee Login',
            buttonColor: '#4666FF',
            iconUrl: 'https://www.example.com/photos/my_idp/saml.png'
          },
        ],
        // If there is only one sign-in provider eligible for the user,
        // whether to show the provider selection page.
        immediateFederatedRedirect: true,
        signInFlow: 'redirect', // Or popup
        // The terms of service URL and privacy policy URL for the sign-in page
        // specific to each tenant.
        tosUrl: 'http://localhost/tenant1/tos',
        privacyPolicyUrl: 'http://localhost/tenant1/privacypolicy'
      },
      // Tenant configuration for tenant ID tenantId2.
      tenantId2: {
        fullLabel: 'OCP Portal',
        displayName: 'OCP',
        buttonColor: '#2F2F2F',
        iconUrl: '<icon-url-of-sign-in-button>',
        // Tenant2 supports a SAML, OIDC and Email/password sign-in.
        signInOptions: [
          // Email/password sign-in.
          {
            provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
            // Do not require display name on sign up.
            requireDisplayName: false
          },
          // SAML provider. (multiple SAML providers can be passed)
          {
            provider: 'saml.my-provider2',
            providerName: 'SAML provider',
            fullLabel: 'Contractor Portal',
            buttonColor: '#4666FF',
            iconUrl: 'https://www.example.com/photos/my_idp/saml.png'
          },
          // OIDC provider. (multiple OIDC providers can be passed)
          {
            provider: 'oidc.my-provider1',
            providerName: 'OIDC provider',
            buttonColor: '#4666FF',
            iconUrl: 'https://www.example.com/photos/my_idp/oidc.png'
          },
        ],
      },
      // Tenant configuration for tenant ID tenantId3.
      tenantId3: {
        fullLabel: 'Tenant3 Portal',
        displayName: 'Tenant3',
        buttonColor: '#007bff',
        iconUrl: '<icon-url-of-sign-in-button>',
        // Tenant3 supports a Google and Email/password sign-in.
        signInOptions: [
          // Email/password sign-in.
          {
            provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
            // Do not require display name on sign up.
            requireDisplayName: false
          },
          // Google provider.
          {
            provider: 'google.com',
            scopes: ['scope1', 'scope2', 'https://example.com/scope3'],
            loginHintKey: 'login_hint',
            customParameters: {
              prompt: 'consent',
            },
          },
        ],
        // Sets the adminRestrictedOperation configuration for providers
        // including federated, email/password, email link and phone number.
        adminRestrictedOperation: {
          status: true,
          adminEmail: '[e-mail]',
          helpLink: 'https://www.example.com/trouble_signing_in'
        }
      },
    },
  },
};

以下各節將說明如何設定部分特定於 IAP 的欄位。如需其他欄位設定的範例，請參閱上述程式碼片段或 GitHub 上的 FirebaseUI 說明文件。

設定 API 金鑰

一般設定會先從專案的 API 金鑰開始：

// The project configuration.
const configs = {
  // Configuration for API_KEY.
  API_KEY: {
    // Config goes here
  }
}

在大多數情況下，您只需要指定一個 API 金鑰。不過，如果您想在多個專案中使用單一驗證網址，可以加入多個 API 金鑰：

const configs = {
  API_KEY1: {
    // Config goes here
  },
  API_KEY2: {
    // Config goes here
  },
}

取得驗證網域

將 authdomain 欄位設為已佈建的網域，以利聯合登入。您可以從 Google Cloud 控制台的 Identity Platform 頁面擷取這個欄位。

指定租戶 ID

設定需要使用者可用於驗證的租用戶和提供者清單。

每個租用戶都會以 ID 做為識別。如果您使用專案層級驗證 (沒有租用戶)，請改用特殊的 _ 識別碼做為 API 金鑰。例如：

const configs = {
  // Configuration for project identified by API key API_KEY1.
  API_KEY1: {
    tenants: {
      // Project-level IdPs flow.
      _: {
        // Tenant config goes here
      },
      // Single tenant flow.
      1036546636501: {
        // Tenant config goes here
      }
    }
  }
}

您也可以使用 * 運算子指定萬用字元租用戶設定。如果找不到相符的 ID，系統會使用這個租用戶做為備用方案。

設定租用戶供應器

每個租用戶都有自己的供應者，這些供應者會在 signInOptions 欄位中指定：

tenantId1: {
  signInOptions: [
    // Options go here
  ]
}

如要瞭解如何設定供應商，請參閱 FirebaseUI 說明文件中的「設定登入供應商」。

除了 FirebaseUI 說明文件中概略說明的步驟之外，還有幾個特定於 IAP 的欄位，取決於您選擇的租用戶選取模式。如要進一步瞭解這些欄位，請參閱下一節。

選擇租戶選取模式

使用者可以透過兩種方式選取租用戶：選項優先模式或ID 優先模式。

在選項模式中，使用者會先從清單中選取租用戶，然後輸入使用者名稱和密碼。在 ID 模式中，使用者會先輸入電子郵件地址。系統會自動選取第一個租用戶，其中的 ID 提供者與電子郵件網域相符。

如要使用選項模式，請將 displayMode 設為 optionFirst。接著，您需要為每個租用戶的按鈕提供設定資訊，包括 displayName、buttonColor 和 iconUrl。您也可以提供選用的 fullLabel，用於覆寫整個按鈕標籤，而非只覆寫顯示名稱。

以下是設定為使用選項模式的租用戶範例：

tenantId1: {
  fullLabel: 'ACME Portal',
  displayName: 'ACME',
  buttonColor: '#2F2F2F',
  iconUrl: '<icon-url-of-sign-in-button>',
  // ...

如要使用 ID 模式，每個登入選項都必須指定 hd 欄位，指出所支援的網域。這可以是正規表示式 (例如 /@example\.com$/) 或網域字串 (例如 example.com)。

下方程式碼顯示租用戶已設定為使用 ID 模式：

tenantId1: {
  signInOptions: [
    // Email/password sign-in.
    {
      hd: 'acme.com', // using regex: /@acme\.com$/
      // ...
    },

啟用立即重新導向

如果您的應用程式只支援單一 ID 供應器，將 immediateFederatedRedirect 設為 true 會略過登入 UI，並將使用者直接重新導向至供應器。

注意： 這項設定可能會導致 Safari 使用者出現非預期結果，因為 Safari 可能會誤將轉向視為跳出追蹤器。詳情請參閱「智慧型防追蹤功能」。

設定回呼

設定物件包含一組回呼，會在驗證流程中的不同時間點叫用。這樣一來，您還可以自訂 UI。可用的掛鉤如下：

selectTenantUiShown()	在顯示租用戶選取 UI 時觸發。如果您想使用自訂標題或主題修改 UI，請使用這個選項。
signInUiShown(tenantId)	在選取租用戶並顯示使用者輸入憑證的 UI 時觸發。如果您想使用自訂標題或主題修改 UI，請使用這個選項。
beforeSignInSuccess(user)	在登入完成前觸發。您可以使用這個方法修改已登入的使用者，然後再重新導向至 IAP 資源。

以下程式碼範例說明如何實作這些回呼：

callbacks: {
  selectTenantUiShown: () => {
    // Show info of the IAP resource.
    showUiTitle(
        'Select your employer to access your Health Benefits');
  },
  signInUiShown: (tenantId) => {
    // Show tenant title and additional display info.
    const tenantName = getTenantNameFromId(tenantId);
    showUiTitle(`Sign in to access your ${tenantName} Health Benefits`);
  },
  beforeSignInSuccess: (user) => {
    // Do additional processing on user before sign-in is
    // complete.
    // For example update the user profile.
    return user.updateProfile({
      photoURL: 'https://example.com/profile/1234/photo.png',
    }).then(function() {
      // To reflect updated photoURL in the ID token, force token
      // refresh.
      return user.getIdToken(true);
    }).then(function() {
      return user;
    });
  }
}

初始化程式庫

建立設定物件後，請按照下列步驟在驗證頁面上初始化程式庫：

1. 建立 HTML 容器，用於轉譯 UI。

   <!DOCTYPE html>
   <html>
    <head>...</head>
    <body>
      <!-- The surrounding HTML is left untouched by FirebaseUI.
           Your app may use that space for branding, controls and other
           customizations.-->
      <h1>Welcome to My Awesome App</h1>
      <div id="firebaseui-auth-container"></div>
    </body>
   </html>
   

2. 建立 FirebaseUiHandler 例項，以便在 HTML 容器中算繪，並將您建立的 config 元素傳遞給該例項。

   const configs = {
     // ...
   }
   const handler = new firebaseui.auth.FirebaseUiHandler(
     '#firebaseui-auth-container', configs);
   

3. 建立新的 Authentication 例項，將處理常式傳遞至該例項，然後呼叫 start()。

   const ciapInstance = new ciap.Authentication(handler);
   ciapInstance.start();
   

部署應用程式並前往驗證頁面。系統應會顯示內含租戶和供應者的登入 UI。

後續步驟

• 瞭解如何透過程式輔助的方式存取非 Google 資源。
• 瞭解如何管理工作階段。
• 進一步瞭解外部身分識別資訊與 IAP 的搭配運作方式。