使用 IAM 帳戶連線

本頁說明如何使用透過 Identity and Access Management (IAM) 準備的帳戶，登入 AlloyDB for PostgreSQL 執行個體。並說明如何使用 psql 指令列用戶端執行 IAM 式登入。

如要瞭解如何連線至 AlloyDB 執行個體，請參閱連線總覽。

事前準備

您必須先準備好專案、叢集、執行個體和 IAM 使用者帳戶，才能使用 IAM 憑證登入 AlloyDB 執行個體。

詳情請參閱「管理 IAM 驗證」。

使用 OAuth 2.0 權杖進行驗證

使用者或應用程式可以按照下列步驟，向 AlloyDB 資料庫進行驗證：

  1. 如果尚未授權 Google Cloud CLI，請使用要登入 AlloyDB 執行個體的相同使用者或服務帳戶授權 Google Cloud CLI。

  2. 使用 gcloud auth print-access-token Google Cloud 指令要求 OAuth 2.0 權杖：

    gcloud auth print-access-token

    這項 Google Cloud 指令會輸出 OAuth 2.0 權杖。

    如要進一步確保安全，可以按照下列替代步驟，限制權杖只能用於 AlloyDB 驗證：

    1. 如果尚未完成，請使用gcloud auth application-default loginalloydb.login 指令，將 alloydb.login 範圍新增至目前環境的存取憑證：

      gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid

    2. 使用gcloud auth application-default print-access-token 指令列印受限的 OAuth 2.0 權杖，並將權杖範圍僅限於 AlloyDB 驗證：

      gcloud auth application-default print-access-token –-scopes=https://www.googleapis.com/auth/alloydb.login

    OAuth 2.0 權杖可讓您 (或任何人) 代表您向 Google Cloud 提出已驗證的要求。請將權杖視為密碼，妥善保存。請妥善儲存權杖，或完全不要儲存。本頁稍後的 psql 範例用法，會示範如何透過單一動作要求、使用及捨棄 OAuth 2.0 權杖。

  3. 使用下列憑證，以標準 PostgreSQL 技術登入 AlloyDB 執行個體：

    • 將上一個步驟取得的存取權杖當做密碼。

    • 如果是 IAM 使用者帳戶，資料庫使用者名稱就是帳戶的完整電子郵件地址。

    • 如果是 IAM 服務帳戶，資料庫使用者名稱是帳戶的電子郵件地址，但不含 .gserviceaccount.com 後置字元。

下列 psql 指令示範如何透過指令列登入 IAM 使用者。這會將 gcloud auth print-access-token 的輸出內容指派給 PGPASSWORD 環境變數，後者隨後會做為資料庫登入密碼。psql

PGPASSWORD=$(gcloud auth print-access-token) psql \
  -h INSTANCE_ADDRESS \
  -U USERNAME \
  -d DATABASE

更改下列內容：

  • INSTANCE_ADDRESS：要連線的 AlloyDB 執行個體 IP 位址。

  • USERNAME：用於向執行個體進行驗證的 IAM 使用者 ID。

    如果是 IAM 使用者帳戶，請提供使用者帳戶的完整電子郵件地址。例如 kai@altostrat.com。

    如果是 IAM 服務帳戶，請提供服務帳戶的地址，不要加上 .gserviceaccount.com 後置字元。舉例來說，如要指定服務帳戶 my-service@my-project.iam.gserviceaccount.com，請在此處使用 my-service@my-project.iam 值。

  • DATABASE：要連線的資料庫名稱。

請注意，psql 會截斷指令列中長度超過 100 個字元的密碼。如要使用 OAuth 2.0 權杖做為登入密碼，請務必設定 PGPASSWORD 環境變數，如本範例所示，而不是在系統提示時手動貼上。psql

自動驗證

如要自動驗證以 IAM 為基礎的 AlloyDB 使用者，不必使用 OAuth 2.0 權杖，有兩種做法：AlloyDB Auth Proxy 和 AlloyDB 語言連接器。

用來執行 Proxy 用戶端或 Language Connectors 的 IAM 帳戶，必須與您新增為資料庫使用者的帳戶相同。舉例來說，如果您使用 IAM 使用者帳戶 kai@altostrat.com 執行工作負載，則可使用 Proxy 用戶端或 Language Connectors 自動驗證 kai@altostrat.com 資料庫使用者，不必指定 OAuth 2.0 權杖。在本範例中，自動驗證功能僅適用於 kai@altostrat.com，不適用於其他資料庫使用者。

Auth Proxy

如要使用 Auth Proxy，請執行 AlloyDB Auth Proxy 用戶端，並啟用 --auto-iam-authn 標記。

如要進一步瞭解如何執行 Auth Proxy，請參閱「使用 AlloyDB Auth Proxy 連線」。

語言連接器

如要使用語言連接器，必須以程式輔助方式啟用 IAM 驗證。「設定 AlloyDB 語言連接器」頁面上的每種語言都有對應選項。

排解 IAM 驗證問題

如要判斷 IAM 驗證嘗試失敗的原因，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

    前往記錄檔探索工具

  2. 在「資源類型」下方，按一下「AlloyDB 執行個體」。

  3. 在「嚴重性」下方，按一下「快訊」。

    如果沒有「快訊」選項，表示所選時間範圍內沒有記錄任何驗證失敗事件。您可能需要使用記錄檔探索工具控制項調整視窗。

  4. 在「查詢結果」下方，檢查記錄項目是否包含下列任一訊息：

    Request had invalid authentication credentials.
    存取權杖無效。
    Caller does not have required permission to use project.
    IAM 主體沒有必要的 IAM 角色或權限。 完整錯誤訊息會指出缺少的角色或權限。
    IAM principal does not match database user.

    存取權杖指定的已驗證 IAM 主體，與您要連線的資料庫使用者不符。

    如要查看權杖指定的主體，請執行下列指令：

    curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo

    將 ACCESS_TOKEN 替換為 OAuth 2.0 存取權杖。

    Request had insufficient scopes.
    存取權杖不含 alloydb.login 範圍或 cloud-platform 範圍。至少需要其中一個範圍。

後續步驟