Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

透過 Node.js 驗證使用者

在 Google Cloud 代管平台 (例如 App Engine) 上執行的應用程式，可使用 Identity-Aware Proxy (IAP) 控管存取權，避免管理使用者驗證和工作階段。IAP 不僅可控管對應用程式的存取權，還能提供已驗證使用者的相關資訊，包括電子郵件地址和應用程式的永久 ID (採用新的 HTTP 標頭)。

目標

要求 App Engine 應用程式的使用者必須使用 IAP 驗證自己的身分。
在應用程式中存取使用者的身分，以顯示目前使用者已驗證的電子郵件地址。

費用

在本文件中，您將使用下列 Google Cloud計費元件：

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

背景

此教學課程使用 IAP 對使用者進行身分驗證。這只是其中一種方法。如要進一步瞭解驗證使用者的不同方法，請參閱驗證概念一節。

Hello `user-email-address` 應用程式

此教學課程使用的應用程式是最小型的 Hello World App Engine 應用程式，其中有一非典型功能：顯示「Hello user-email-address」而非「Hello world」，而 user-email-address 是已驗證的使用者電子郵件地址。

這項功能會檢查 IAP 新增至每個網頁要求的驗證資訊，並將這些資訊傳遞至應用程式。每個傳送至應用程式的網頁要求都會新增三個要求標頭。前兩個標頭是純文字字串，可用來識別使用者。第三個標頭是具有相同資訊的加密簽署物件。

X-Goog-Authenticated-User-Email：使用者的電子郵件地址可用於識別身分。如果可以，請不要讓您的應用程式儲存個人資訊。這個應用程式不會儲存任何資料，而只是回應給使用者。
X-Goog-Authenticated-User-Id：此由 Google 指派的使用者 ID 不會顯示使用者的相關資訊，但可讓應用程式知道登入的使用者是先前有出現過的。
X-Goog-Iap-Jwt-Assertion：除了網際網路網頁要求，您也可以設定 Google Cloud 應用程式接受來自其他雲端應用程式的網頁要求，略過 IAP。如果將應用程式如此設定，則此類要求可能會具有假造的標頭。您可以不使用先前提到的純文字標頭，改為使用並驗證這個經過加密簽署的標頭，確認資訊是由 Google 提供。這個已簽署的標頭中會包含使用者電子郵件地址和永久使用者 ID。

如果您確定應用程式已設定為僅能接收網際網路網頁要求，且沒有人可以停用應用程式的 IAP 服務，則只需一行程式碼即可擷取不重複的使用者 ID：

userId = req.header('X-Goog-Authenticated-User-ID') :? null;

但是，有彈性的應用程式可能會發生錯誤，包括非預期的設定或環境問題，因此我們建議建立一個可使用並驗證經加密簽署標頭的函式。這個標頭的簽署無法假造，驗證後即可用於傳回身分識別。

建立原始碼

使用文字編輯器建立名為 app.js 的檔案，並在其中貼上下列程式碼：

const express = require('express');
const metadata = require('gcp-metadata');
const {OAuth2Client} = require('google-auth-library');

const app = express();
const oAuth2Client = new OAuth2Client();

// Cache externally fetched information for future invocations
let aud;

async function audience() {
  if (!aud && (await metadata.isAvailable())) {
    let project_number = await metadata.project('numeric-project-id');
    let project_id = await metadata.project('project-id');

    aud = '/projects/' + project_number + '/apps/' + project_id;
  }

  return aud;
}

async function validateAssertion(assertion) {
  if (!assertion) {
    return {};
  }

  // Check that the assertion's audience matches ours
  const aud = await audience();

  // Fetch the current certificates and verify the signature on the assertion
  const response = await oAuth2Client.getIapPublicKeys();
  const ticket = await oAuth2Client.verifySignedJwtWithCertsAsync(
    assertion,
    response.pubkeys,
    aud,
    ['https://cloud.google.com/iap']
  );
  const payload = ticket.getPayload();

  // Return the two relevant pieces of information
  return {
    email: payload.email,
    sub: payload.sub,
  };
}

app.get('/', async (req, res) => {
  const assertion = req.header('X-Goog-IAP-JWT-Assertion');
  let email = 'None';
  try {
    const info = await validateAssertion(assertion);
    email = info.email;
  } catch (error) {
    console.log(error);
  }
  res.status(200).send(`Hello ${email}`).end();
});


// Start the server
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

本教學課程稍後的認識程式碼一節會詳加說明 app.js 檔案。

建立另一個名為 package.json 的檔案，然後貼上下列內容：

{
  "name": "iap-authentication",
  "description": "Minimal app to use authentication information from IAP.",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/getting-started-nodejs.git"
  },
  "engines": {
    "node": ">=12.0.0"
  },
  "scripts": {
    "start": "node app.js",
    "test": "mocha --exit test/*.test.js"
  },
  "dependencies": {
    "express": "^4.17.1",
    "gcp-metadata": "^5.0.0",
    "google-auth-library": "^8.0.0"
  },
  "devDependencies": {
    "mocha": "^9.0.0",
    "supertest": "^6.0.0"
  }
}

package.json 檔案列出您的應用程式所需的 Node.js 依附元件。jsonwebtoken 為 JWT 提供檢查和解碼的功能。

建立名為 app.yaml 的檔案，並在其中加入下列文字：

# Copyright 2019 Google LLC
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

runtime: nodejs10

app.yaml 檔案會告知 App Engine 程式碼所需的語言環境。

瞭解程式碼

本節將說明 app.js 檔案中程式碼的運作方式。如要執行應用程式，請直接跳至部署應用程式一節。

下列程式碼位於 app.js 檔案中。當應用程式收到 HTTP GET 時，會叫用 / 的 switch case：

該函式會取得 IAP 從傳入要求中加入的 JWT 斷言標頭值，並呼叫函式以驗證經加密簽署的值。傳回的第一個值 (電子郵件地址) 會用於該函式建立並傳回的最小網頁。

app.get('/', async (req, res) => {
  const assertion = req.header('X-Goog-IAP-JWT-Assertion');
  let email = 'None';
  try {
    const info = await validateAssertion(assertion);
    email = info.email;
  } catch (error) {
    console.log(error);
  }
  res.status(200).send(`Hello ${email}`).end();
});

validateAssertion 函式會使用 google-auth-library 的 verifySignedJwtWithCertsAsync() 函式，驗證斷言是否已正確簽署，並從斷言中擷取酬載資訊。這項資訊就是已驗證的使用者電子郵件地址，以及該使用者的永久唯一識別碼。如果無法解碼斷言，這個函式會擲回並輸出訊息以記錄錯誤。

如要驗證 JWT 聲明，您必須知道簽署聲明的實體 (在本例中為 Google) 的公開金鑰憑證，以及聲明的目標對象。如果是 App Engine 應用程式，目標對象是包含 Google Cloud 專案識別資訊的字串。此函式會從其先前的函式中取得憑證和目標對象字串。

async function validateAssertion(assertion) {
  if (!assertion) {
    return {};
  }

  // Check that the assertion's audience matches ours
  const aud = await audience();

  // Fetch the current certificates and verify the signature on the assertion
  const response = await oAuth2Client.getIapPublicKeys();
  const ticket = await oAuth2Client.verifySignedJwtWithCertsAsync(
    assertion,
    response.pubkeys,
    aud,
    ['https://cloud.google.com/iap']
  );
  const payload = ticket.getPayload();

  // Return the two relevant pieces of information
  return {
    email: payload.email,
    sub: payload.sub,
  };
}

您可以自行查詢專案的 Google Cloud 數值 ID 和名稱，並將其放入原始碼，但 audience 函式會為您查詢每個 App Engine 應用程式可用的標準中繼資料服務，因此不必這麼做。由於中繼資料服務位於應用程式程式碼外部，因此結果會儲存在全域變數中，後續呼叫時不必查詢中繼資料，即可傳回結果。

async function audience() {
  if (!aud && (await metadata.isAvailable())) {
    let project_number = await metadata.project('numeric-project-id');
    let project_id = await metadata.project('project-id');

    aud = '/projects/' + project_number + '/apps/' + project_id;
  }

  return aud;
}

App Engine 中繼資料服務 (以及其他Google Cloud 運算服務的類似中繼資料服務) 看起來像網站，可透過標準網路查詢進行查詢。不過，中繼資料服務並非外部網站，而是傳回執行中應用程式相關資訊的內部功能，因此使用 http 而非 https 要求是安全的。用於取得定義 JWT 聲明指定目標對象所需的目前 Google Cloud ID。

const response = await oAuth2Client.getIapPublicKeys();

驗證數位簽章時，需要簽署者的公用金鑰憑證。Google 提供了一個網站，可傳回目前使用中的所有公用金鑰憑證。傳回的結果會存放在快取中，以利同一個應用程式執行個體在需要時重複使用。

部署應用程式

現在您可以部署應用程式，然後啟用 IAP，要求使用者必須經過驗證才能存取應用程式。

在終端機視窗中，前往包含 app.yaml 檔案的目錄，然後將應用程式部署至 App Engine：
```
gcloud app deploy
```
系統提示時，請選取附近的區域。
當系統詢問您是否要繼續進行部署作業時，請輸入 Y。

幾分鐘後，應用程式就會在網際網路上線。
查看應用程式：
```
gcloud app browse
```
在輸出中，複製 web-site-url (應用程式的網址)。
在瀏覽器視窗中，貼上 web-site-url 即可開啟應用程式。

由於您尚未使用 IAP，因此系統不會顯示任何電子郵件，也不會傳送任何使用者資訊給應用程式。

啟用 IAP

現在有了 App Engine 執行個體，您可以使用 IAP 進行保護：

前往 Google Cloud 控制台的「Identity-Aware Proxy」頁面。

前往「Identity-Aware Proxy」頁面
由於這是您第一次為這項專案啟用驗證選項，因此系統會顯示一則訊息，說明您必須先設定 OAuth 同意畫面，才能使用 IAP。

按一下 [Configure consent screen] (設定同意畫面)。
在「Credentials」(憑證) 頁面的「OAuth Consent Screen」(OAuth 同意畫面) 分頁中，填寫下列欄位：
- 如果帳戶屬於 Google Workspace 機構，請選取「外部」，然後按一下「建立」。一開始，只有您明確允許的使用者才能存取應用程式。
- 在「Application name」(應用程式名稱) 欄位中，輸入 IAP Example。
- 在「Support email」(支援電子郵件) 欄位中，輸入您的電子郵件地址。
- 在「Authorized domain」(授權網域) 欄位中，輸入應用程式網址的主機名稱部分，例如 iap-example-999999.uc.r.appspot.com。在欄位中輸入主機名稱後，按下 Enter 鍵。
- 在「Application homepage link」(應用程式首頁連結) 欄位中，輸入應用程式的網址，例如 https://iap-example-999999.uc.r.appspot.com/。
- 在「Application privacy policy line」(應用程式隱私權政策行) 欄位中，使用與首頁連結相同的網址進行測試。
按一下 [Save] (儲存)，在系統提示您建立憑證時，您可以關閉視窗。
前往 Google Cloud 控制台的「Identity-Aware Proxy」頁面。

前往「Identity-Aware Proxy」頁面
如要重新整理頁面，請按一下「重新整理」圖示。該頁面會列出您可以保護的資源。
在「IAP」資料欄中，按一下以開啟應用程式的 IAP。
在瀏覽器中，再次前往 web-site-url。
除了網頁外，您也可以透過登入畫面來驗證自己的身分。當您登入時，由於 IAP 未具備允許進入應用程式的使用者清單，因此系統會拒絕您的存取。

將已獲授權的使用者加入應用程式

前往 Google Cloud 控制台的「Identity-Aware Proxy」頁面。

前往「Identity-Aware Proxy」頁面
勾選 App Engine 應用程式的核取方塊，然後按一下「Add Principal」(新增主體)。
輸入 allAuthenticatedUsers，然後選取 [Cloud IAP/IAP-Secured Web App User] (受 Cloud IAP/IAP 保護的網路應用程式使用者) 角色。
按一下 [儲存]。

現在，Google 可以驗證的任何使用者都能存取應用程式。如要進一步限制存取權，可以只將一或多個使用者或群組新增為主體：

任何 Gmail 或 Google Workspace 電子郵件地址
Google 網路論壇電子郵件地址
Google Workspace 網域名稱

存取應用程式

透過瀏覽器前往 web-site-url：
如要重新整理頁面，請按一下「重新整理」圖示。
請在登入畫面中，使用您的 Google 憑證登入。

網頁上會顯示包含您電子郵件地址的「Hello user-email-address」網頁。

若您看到的網頁沒有變化，則可能是您啟用 IAP 後，瀏覽器尚未將新的要求完全更新。請關閉所有的瀏覽器視窗後重新開啟，然後再試一次。

驗證概念

應用程式可透過多種方式驗證使用者的身分，並限制僅已獲授權的使用者可擁有存取權。以下各節列出常見的驗證方式，並依應用程式所需投入的心力由高到低排序。

選項	優勢	缺點
應用程式驗證	無論是否有網際網路連線，應用程式都可在任何平台上執行使用者不需使用任何其他服務來管理驗證	應用程式必須安全地管理使用者憑證，以防止憑證洩漏應用程式必須維護登入使用者的工作階段資料應用程式必須提供使用者註冊、密碼變更、密碼復原的功能
OAuth2	應用程式可以在任何網際網路連線平台上執行，包括開發人員工作站應用程式不需要使用者註冊、密碼變更或密碼復原的功能使用者資訊外洩的風險可委派給其他服務管理新的登入安全措施會在應用程式外部處理	使用者必須使用身分服務註冊應用程式必須維護登入使用者的工作階段資料
IAP	應用程式不需要任何程式碼即可管理使用者、驗證或工作階段狀態應用程式不包含可能遭到破解的使用者憑證	應用程式只能在服務支援的平台上執行具體來說，某些 Google Cloud 支援 IAP 的服務，例如 App Engine。

應用程式管理的驗證

透過此方法，應用程式可自行管理使用者驗證的各個環節。應用程式必須維護自己的使用者憑證資料庫並管理使用者工作階段，此外還需提供下列功能：管理使用者帳戶和密碼、檢查使用者憑證，以及對每個經過驗證的登入發出、檢查和更新使用者工作階段。下圖說明應用程式管理的驗證方法。

應用程式管理流程

如圖所示，使用者登入後，應用程式會建立並維護使用者工作階段的相關資訊。使用者向應用程式提出要求時，要求中必須包含工作階段資訊，應用程式負責驗證這些資訊。

此方法的主要優點在於其獨立性，以及受到應用程式的控管，且應用程式甚至不需在網際網路中提供。主要缺點是應用程式現在必須負責提供所有帳戶管理功能，並保護所有敏感憑證資料。

使用 OAuth2 進行外部驗證

如果不想在應用程式中處理所有事項，不妨使用外部身分識別服務 (例如 Google)，這類服務會處理所有使用者帳戶資訊和功能，並負責保護私密憑證。使用者嘗試登入應用程式時，系統會將要求重新導向至身分服務，由該服務對使用者進行驗證，然後在取得必要的驗證資訊後，將要求重新導向回應用程式。詳情請參閱「使用 OAuth 2.0 處理網路伺服器應用程式」。

下圖說明使用 OAuth2 方法進行的外部驗證。

OAuth2 流程

圖表中的流程從使用者傳送應用程式存取要求開始。應用程式不會直接回應，而是將使用者的瀏覽器重新導向至 Google 的身分識別平台，該平台會顯示登入 Google 的頁面。成功登入後，使用者的瀏覽器會導向回應用程式。要求中會包含所需資訊，讓應用程式可針對已完成驗證的使用者查詢相關資訊，並對該使用者發出回應。

這種方法對應用程式有許多好處。它將所有帳戶管理功能和風險委派給外部服務，這樣可以改善登入和帳戶安全性，而無需變更應用程式。不過，如上圖所示，應用程式必須具備網際網路存取權才能使用這個方法。在驗證過使用者的身分後，應用程式也需負責管理工作階段。

Identity-Aware Proxy

本教學課程將介紹第三種方法，也就是使用 IAP 處理所有驗證和工作階段管理作業，並對應用程式進行任何變更。IAP 會攔截傳送至應用程式的所有網頁要求，封鎖未經驗證的要求，並將其他要求連同使用者身分資料一併傳送。

要求的處理方式如下圖所示。

應用程式內購流程

所有使用者的要求會遭到 IAP 攔截，因而能阻止未經驗證的要求。已驗證的要求則會傳送至應用程式，前提是已驗證的使用者名列允許的使用者清單之中。透過 IAP 傳送的要求會加入標頭，以用於識別提出要求的使用者。

應用程式不再需要處理任何使用者帳戶或工作階段資訊。任何需要知道使用者專屬 ID 的作業，都可以直接從每個傳入的網頁要求取得該 ID。不過此流程僅限用於支援 IAP 的運算服務，例如 App Engine 和負載平衡器。您無法在本機開發電腦上使用 IAP。

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 帳戶收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

透過 Node.js 驗證使用者 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

背景

Hello user-email-address 應用程式

建立原始碼

瞭解程式碼

部署應用程式

啟用 IAP

將已獲授權的使用者加入應用程式

存取應用程式

驗證概念

應用程式管理的驗證

使用 OAuth2 進行外部驗證

Identity-Aware Proxy

清除所用資源

透過 Node.js 驗證使用者

Hello `user-email-address` 應用程式