運用 IAM 資料庫驗證功能管理使用者

MySQL   |  PostgreSQL   |  SQL Server

本頁說明如何將使用者、服務帳戶和群組新增至使用 IAM 資料庫驗證的 Cloud SQL 執行個體，以及如何管理這些項目。

如要進一步瞭解 IAM 整合，請參閱「IAM 驗證」。

注意： 管理外部身分識別資訊提供者中使用者存取權時，請將 Google 帳戶主體 ID (例如 user:[e-mail]、group:[e-mail] 和 domain:example.com) 的例項，替換為適當的員工身分聯盟主體 ID。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Install the gcloud 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Install the gcloud 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

1. 確認使用者帳戶具備 Cloud SQL 管理員角色。

   前往「IAM」頁面

2. 在 Cloud SQL 執行個體上啟用 IAM 資料庫驗證。
3. 將必要的 cloudsql.instanceUser IAM 角色指派給 IAM 主體，例如 IAM 使用者、服務帳戶或群組，以便登入 Cloud SQL 執行個體。
• 如果您要將個別使用者或個別服務帳戶新增至 Cloud SQL 執行個體，則必須分別為每個使用者和服務帳戶指派 IAM 角色。
• 如果您要新增群組，則必須將 IAM 角色指派給群組，因為群組成員會自動繼承與 IAM 角色相關聯的 IAM 權限。如要進一步瞭解如何在 Cloud Identity 中建立群組，請參閱在 Google Cloud 控制台中建立及管理 Google 群組。
• 如要授予角色，可以使用 Google Cloud 控制台的「IAM」頁面、gcloud CLI、Terraform 或 Cloud SQL Admin API，在包含 Cloud SQL 執行個體的專案中授予角色。詳情請參閱「為使用者、服務帳戶或群組新增身分與存取權管理政策繫結」。
4. 如果您使用服務帳戶，請務必為專案中需要存取資料庫的每項服務新增服務帳戶。

如要進一步瞭解如何建立服務帳戶，請參閱「建立服務帳戶」。

為使用者、服務帳戶或群組新增 IAM 政策繫結

這項程序會根據專案 ID 和繫結，將政策繫結新增至特定專案的 IAM 政策。繫結指令包含成員、角色和選用條件。

資料庫使用者名稱必須是 IAM 使用者的電子郵件地址，例如 [e-mail]。必須全部為小寫，且因為含有特殊字元 (@ 和 .)，所以必須使用引號。

控制台

1. 前往 Google Cloud 控制台的「IAM」頁面。

   前往「IAM」頁面

2. 按一下「新增」。
3. 在「New members」(新增成員) 中輸入電子郵件地址。您可以新增個別使用者、服務帳戶或群組成員，但各專案至少要有一位主體成員。
4. 在「角色」中，前往「Cloud SQL」，然後選取「Cloud SQL 執行個體使用者」。
5. 選用：如要使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線，請一併選取「Cloud SQL Client」。
6. 按一下 [儲存]。

gcloud

使用 --role=roles/cloudsql.instanceUser 旗標執行 gcloud projects add-iam-policy-binding。

為使用者帳戶新增政策繫結

更改下列內容：

• PROJECT_ID：您要授權使用者使用的專案 ID。
• USERNAME：使用者的電子郵件地址。

  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=user:USERNAME \
    --role=roles/cloudsql.instanceUser
  

如要使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線，請再次執行 gcloud projects add-iam-policy-binding，並加上 --role=roles/cloudsql.client 旗標。

將政策繫結新增至服務帳戶

更改下列內容：

• PROJECT_ID：您要授權使用者使用的專案 ID。
• SERVICE_ACCT：服務帳戶的電子郵件地址。

  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCT \
    --role=roles/cloudsql.instanceUser
  

如要使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線，請再次執行 gcloud projects add-iam-policy-binding，並加上 --role=roles/cloudsql.client 旗標。

將政策繫結新增至 Cloud Identity 群組

更改下列內容：

• PROJECT_ID：您要授權群組成員使用的專案 ID。
• GROUP_EMAIL_ADDRESS：群組的電子郵件地址。例如 [e-mail]。

  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=group:GROUP_EMAIL_ADDRESS \
    --role=roles/cloudsql.instanceUser
   

指定群組的所有成員都會獲得 Cloud SQL 執行個體使用者角色，並可登入這個專案中的執行個體。

如要使用 Cloud SQL Auth Proxy 或 Cloud SQL 語言連接器連線，請再次執行 gcloud projects add-iam-policy-binding，並加上 --role=roles/cloudsql.client 旗標。

Terraform

如要將必要的政策繫結新增至 IAM 使用者和服務帳戶，請使用 Terraform 資源。

data "google_project" "project" {
}

resource "google_project_iam_binding" "cloud_sql_user" {
  project = data.google_project.project.project_id
  role    = "roles/cloudsql.instanceUser"
  members = [
    "user:[e-mail]",
    "serviceAccount:${google_service_account.default.email}"
  ]
}

resource "google_project_iam_binding" "cloud_sql_client" {
  project = data.google_project.project.project_id
  role    = "roles/cloudsql.client"
  members = [
    "user:[e-mail]",
    "serviceAccount:${google_service_account.default.email}"
  ]
}

套用變更

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

刪除變更

如要刪除變更，請按照下列步驟操作：

1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。

   deletion_protection =  "false"

2. 執行下列指令，並在提示中輸入 yes，套用更新的 Terraform 設定：

   terraform apply

3. 執行下列指令，並在提示中輸入 yes，移除先前透過 Terraform 設定套用的資源：

   terraform destroy

Terraform

如要將必要的政策繫結新增至 IAM 使用者和服務帳戶，請使用 Terraform 資源。

data "google_project" "project" {
}

resource "google_project_iam_binding" "cloud_sql_user" {
  project = data.google_project.project.project_id
  role    = "roles/cloudsql.instanceUser"
  members = [
    "group:[e-mail]"
  ]
}

套用變更

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

刪除變更

如要刪除變更，請按照下列步驟操作：

1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。

   deletion_protection =  "false"

2. 執行下列指令，並在提示中輸入 yes，套用更新的 Terraform 設定：

   terraform apply

3. 執行下列指令，並在提示中輸入 yes，移除先前透過 Terraform 設定套用的資源：

   terraform destroy

REST

編輯 get-iam-policy 指令傳回的 JSON 或 YAML 繫結政策，將 cloudsql.instanceUser 和 cloudsql.client 角色授予這兩種帳戶。請注意，您必須設定更新後的政策，這項政策異動才會生效。

    {
      "role": "roles/cloudsql.instanceUser",
      "members": [
                   "user:[e-mail]"
                   "serviceAccount:[e-mail]"
                   "group:[e-mail]"
      ]
    }
    {
      "role": "roles/cloudsql.client",
      "members": [
                   "user:[e-mail]"
                   "serviceAccount:[e-mail]"
      ]
    }

將個別 IAM 使用者或服務帳戶新增至 Cloud SQL 執行個體

您必須為要新增至 Cloud SQL 執行個體的每個 IAM 使用者或服務帳戶建立新的使用者帳戶，才能存取資料庫。如果您要新增 IAM 群組，則不需要為該群組的每位成員建立使用者帳戶。

資料庫使用者名稱必須是 IAM 使用者的電子郵件地址，且全部為小寫。 例如 [e-mail]。

使用 REST 指令時，使用者名稱必須加上引號，因為其中含有特殊字元 (@ 和 .)。服務帳戶的格式為 [e-mail]。

如要新增個別 IAM 使用者或服務帳戶，請新增使用者帳戶，然後選取 IAM 做為驗證方法：

控制台

注意：使用 Google Cloud 控制台將新的 IAM 使用者或服務帳戶新增至 Cloud SQL 執行個體時，Cloud SQL 會自動將 cloudsql.instanceUser IAM 角色指派給專案中所有執行個體的使用者或服務帳戶。系統會自動在專案層級為使用者或服務帳戶新增 IAM 政策繫結。您可以在 Google Cloud 控制台

的「IAM 角色」部分，查看這項 IAM 角色的指派詳細資料。

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在 SQL 導覽選單中選取「使用者」。
4. 按一下「新增使用者帳戶」，系統會開啟「在執行個體『instance_name』中新增使用者帳戶」instance_name分頁。
5. 按一下「Cloud IAM」圓形按鈕。
6. 在「Principal」(主體) 欄位中，新增要加入的使用者或服務帳戶的電子郵件地址。
   注意： 由於資料庫使用者名稱有長度限制，對於服務帳戶，PostgreSQL 適用的 Cloud SQL 會截斷電子郵件中的 .gserviceaccount.com 後置字串。舉例來說，服務帳戶的使用者名稱 [e-mail] 會變成 [e-mail]。
7. 按一下「Add」(新增)。使用者或服務帳戶現在位於使用者帳戶清單中。

8. 如果使用者帳戶建立後未獲指派 cloudsql.instanceUser IAM 角色，使用者名稱旁會顯示 圖示。

   如要授予使用者登入權限，請按一下圖示，然後選取「新增 IAM 角色」。如果圖示不再顯示，表示使用者帳戶已獲派可登入的 IAM 角色。

gcloud

建立使用者帳戶

使用電子郵件地址 (例如 [e-mail]) 識別使用者。

更改下列內容：

• USERNAME：使用者的電子郵件地址。
• INSTANCE_NAME：您要授權使用者存取的執行個體名稱。

gcloud sql users create USERNAME \
--instance=INSTANCE_NAME \
--type=cloud_iam_user

建立服務帳戶

更改下列內容：

• SERVICE_ACCT：服務帳戶的電子郵件地址。
  注意： 由於資料庫使用者名稱有長度限制，您必須省略電子郵件中的 .gserviceaccount.com 後置字元。舉例來說，服務帳戶 [e-mail] 的使用者名稱應為 [e-mail]。
• INSTANCE_NAME：要授權服務帳戶存取的執行個體名稱。

gcloud sql users create SERVICE_ACCT \
--instance=INSTANCE_NAME \
--type=cloud_iam_service_account

Terraform

如要在啟用 IAM 資料庫驗證功能的執行個體上新增 IAM 使用者和服務帳戶，請使用 Terraform 資源。

resource "google_sql_database_instance" "default" {
  name             = "postgres-db-auth-instance-name-test"
  region           = "us-west4"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    database_flags {
      name  = "cloudsql.iam_authentication"
      value = "on"
    }
  }
}

# Specify the email address of the IAM user to add to the instance
# This resource does not create a new IAM user account; this account must
# already exist

resource "google_sql_user" "iam_user" {
  name     = "[e-mail]"
  instance = google_sql_database_instance.default.name
  type     = "CLOUD_IAM_USER"
}

# Specify the email address of the IAM service account to add to the instance
# This resource does not create a new IAM service account; this service account
# must already exist

# Create a new IAM service account

resource "google_service_account" "default" {
  account_id   = "cloud-sql-postgres-sa"
  display_name = "Cloud SQL for Postgres Service Account"
}

resource "google_sql_user" "iam_service_account_user" {
  # Note: for PostgreSQL only, Google Cloud requires that you omit the
  # ".gserviceaccount.com" suffix
  # from the service account email due to length limits on database usernames.
  name     = trimsuffix(google_service_account.default.email, ".gserviceaccount.com")
  instance = google_sql_database_instance.default.name
  type     = "CLOUD_IAM_SERVICE_ACCOUNT"
}

套用變更

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

刪除變更

如要刪除變更，請按照下列步驟操作：

1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。

   deletion_protection =  "false"

2. 執行下列指令，並在提示中輸入 yes，套用更新的 Terraform 設定：

   terraform apply

3. 執行下列指令，並在提示中輸入 yes，移除先前透過 Terraform 設定套用的資源：

   terraform destroy

REST v1

建立使用者帳戶

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：專案 ID
• INSTANCE_ID：要將使用者新增至其中的執行個體 ID
• USERNAME：使用者的電子郵件地址

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USERNAME",
  "type": "CLOUD_IAM_USER"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-02-07T22:44:16.656Z",
  "startTime": "2020-02-07T22:44:16.686Z",
  "endTime": "2020-02-07T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

建立服務帳戶

使用任何要求資料之前，請先替換以下項目：

• ：服務帳戶電子郵件地址
  注意： 由於資料庫使用者名稱有長度限制，您必須省略電子郵件地址中的 .gserviceaccount.com 字尾。SERVICE_ACCT舉例來說，服務帳戶 sa-name@PROJECT_ID.iam.gserviceaccount.com 的使用者名稱應為 sa-name@PROJECT_ID.iam。
• PROJECT_ID：專案 ID
• INSTANCE_ID：您要新增服務帳戶的執行個體 ID

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
    "name": "SERVICE_ACCT",
    "type": "CLOUD_IAM_SERVICE_ACCOUNT"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
"kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-11-20T04:08:00.211Z",
  "startTime": "2020-11-20T04:08:00.240Z",
  "endTime": "2020-11-20T04:08:02.003Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

建立使用者帳戶

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：專案 ID
• INSTANCE_ID：要將使用者新增至其中的執行個體 ID
• USERNAME：使用者的電子郵件地址

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USERNAME",
  "type": "CLOUD_IAM_USER"
  }

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-02-07T22:44:16.656Z",
  "startTime": "2020-02-07T22:44:16.686Z",
  "endTime": "2020-02-07T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

建立服務帳戶

使用任何要求資料之前，請先替換以下項目：

• ：服務帳戶電子郵件地址
  注意： 由於資料庫使用者名稱有長度限制，您必須省略電子郵件地址中的 .gserviceaccount.com 字尾。SERVICE_ACCT舉例來說，服務帳戶 sa-name@PROJECT_ID.iam.gserviceaccount.com 的服務帳戶電子郵件地址應以 sa-name@PROJECT_ID.iam 形式提供。
• PROJECT_ID：專案 ID
• INSTANCE_ID：您要新增服務帳戶的執行個體 ID

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
    "name": "SERVICE_ACCT",
    "type": "CLOUD_IAM_SERVICE_ACCOUNT"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
"kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-11-20T04:08:00.211Z",
  "startTime": "2020-11-20T04:08:00.240Z",
  "endTime": "2020-11-20T04:08:02.003Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

將 IAM 群組新增至 Cloud SQL 執行個體

如要使用 IAM 群組驗證，並將 IAM 群組新增至 Cloud SQL 執行個體，請使用本節中的其中一個程序。新增 IAM 群組後，您不需要將個別群組成員新增至執行個體。詳情請參閱「自動將群組成員新增至 Cloud SQL 執行個體」。

IAM 群組名稱的長度限制與 PostgreSQL 識別符相同，最多只能有 63 個字元。

如果 IAM 群組的名稱超過資料庫引擎的使用者名稱長度限制，您仍可將該群組巢狀內嵌至名稱符合長度限制的父項 IAM 群組，以進行 IAM 群組驗證。必須先將父項 IAM 群組新增至執行個體，才能使用巢狀群組。

控制台

注意：使用 Google Cloud 控制台將新的 IAM 群組新增至 Cloud SQL 執行個體時，Cloud SQL 會自動為專案中的所有執行個體，將 cloudsql.instanceUser IAM 角色指派給該群組。系統會自動在專案層級為群組新增 IAM 政策繫結。您可以在 Google Cloud 控制台的「IAM 角色」中查看 IAM 角色指派詳細資料。

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在 SQL 導覽選單中選取「使用者」。
4. 按一下「新增使用者帳戶」，系統會開啟「在執行個體『instance_name』中新增使用者帳戶」instance_name分頁。
5. 按一下「Cloud IAM」圓形按鈕。
6. 在「Principal」欄位中，新增要加入的群組電子郵件地址。
7. 按一下「Add」(新增)。該群組現在會顯示在使用者清單中。

8. 如果群組在建立使用者帳戶後未獲指派 cloudsql.instanceUser IAM 角色，群組旁就會顯示 圖示。

   如要授予群組成員登入權限，請按一下圖示，然後選取「新增 IAM 角色」。 如果圖示不再顯示，表示群組的所有成員都已獲派可登入的角色。

gcloud

更改下列內容：

• GROUP_EMAIL_ADDRESS：要新增至執行個體的 Cloud Identity 群組電子郵件地址。例如 [e-mail]。
• INSTANCE_NAME：要新增群組的執行個體名稱。

執行下列指令：

gcloud sql users create GROUP_EMAIL_ADDRESS \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_group

Terraform

如要在啟用 IAM 資料庫驗證功能的執行個體上新增 IAM 使用者和服務帳戶，請使用 Terraform 資源。

resource "google_sql_database_instance" "default" {
  name             = "postgres-iam-group-auth-instance-name"
  region           = "us-west4"
  database_version = "POSTGRES_16"
  settings {
    tier = "db-custom-2-7680"
    database_flags {
      name  = "cloudsql.iam_authentication"
      value = "on"
    }
  }
}

# Specify the email address of the Cloud Identity group to add to the instance
# This resource does not create a Cloud Identity group; the group must
# already exist

resource "google_sql_user" "iam_group" {
  name     = "[e-mail]"
  instance = google_sql_database_instance.default.name
  type     = "CLOUD_IAM_GROUP"
}

data "google_project" "project" {
}

resource "google_project_iam_binding" "cloud_sql_user" {
  project = data.google_project.project.project_id
  role    = "roles/cloudsql.instanceUser"
  members = [
    "group:[e-mail]"
  ]
}

套用變更

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

刪除變更

如要刪除變更，請按照下列步驟操作：

1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。

   deletion_protection =  "false"

2. 執行下列指令，並在提示中輸入 yes，套用更新的 Terraform 設定：

   terraform apply

3. 執行下列指令，並在提示中輸入 yes，移除先前透過 Terraform 設定套用的資源：

   terraform destroy

REST v1

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：專案 ID
• INSTANCE_ID：您要將 Cloud Identity 群組新增至的執行個體 ID
• GROUP_EMAIL：Cloud Identity 群組的電子郵件地址

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "GROUP_EMAIL",
  "type": "CLOUD_IAM_GROUP"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2023-12-07T22:44:16.656Z",
  "startTime": "2023-12-07T22:44:16.686Z",
  "endTime": "2023-12-07T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：專案 ID
• INSTANCE_ID：您要將 Cloud Identity 群組新增至的執行個體 ID
• GROUP_EMAIL：Cloud Identity 群組的電子郵件地址

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "GROUP_EMAIL",
  "type": "CLOUD_IAM_GROUP"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2023-12-07T22:44:16.656Z",
  "startTime": "2023-12-07T22:44:16.686Z",
  "endTime": "2023-12-07T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

注意：從 IAM 刪除並立即重新建立的 IAM 群組可能無法立即使用。刪除及重新建立 IAM 群組後，需要一段時間才能完成傳播，屆時 IAM 群組才能再次用於 IAM 群組驗證。

自動將群組成員新增至 Cloud SQL 執行個體

將 IAM 群組新增至 Cloud SQL 執行個體後，該群組的所有成員 (使用者和服務帳戶) 都會沿用 IAM 權限，以驗證執行個體。您不需要個別將群組成員新增至 Cloud SQL 執行個體。群組成員首次登入並成功驗證主要執行個體後，Cloud SQL 會為該群組成員建立群組使用者帳戶或群組服務帳戶。群組成員首次成功登入後，您可以在執行個體上查看成員名單。

容錯移轉後，只要容錯移轉執行個體有適當的群組，IAM 群組使用者就能繼續登入及建立。

如要進一步瞭解登入程序，請參閱「使用 IAM 資料庫驗證功能登入」。

將現有 IAM 使用者移轉至 IAM 群組驗證

現有的 CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT 類型的 IAM 使用者不會使用 IAM 群組驗證。

您可以將這些使用者遷移至 IAM 群組驗證。

1. 將這些使用者加入群組。

2. 將群組新增至執行個體。

3. 指派足夠的 IAM 權限給群組，讓群組成員連線至執行個體。這些變更可能需要一段時間才會生效。如要進一步瞭解傳播時間，請參閱「 存取權變更傳播」。

4. 將資料庫權限指派給要遷移至群組的身分與存取權管理使用者。

5. 群組成員變更和 IAM 權限套用完畢後，請從執行個體中刪除現有的 IAM 使用者。下次 IAM 使用者成功登入時，系統會將該使用者重新建立為 IAM 群組使用者，並可使用 IAM 群組驗證。

管理 Cloud SQL 執行個體的群組成員

將 IAM 群組新增至 Cloud SQL 執行個體後，該群組的所有成員 (使用者或服務帳戶) 都會繼承 IAM 權限，可向執行個體驗證。您可以在 Cloud Identity 中管理群組，藉此控管執行個體的存取權。舉例來說，如要授予新使用者執行個體存取權，請在 Cloud Identity 中將該使用者新增為群組成員。您不需要在 Cloud SQL 執行個體層級個別移除或新增群組成員，因為系統會自動將群組成員資格變更傳播至 Cloud SQL 執行個體。群組成員資格如有變動 (例如新增或移除成員)，大約需要 15 分鐘才會全面套用。Cloud SQL 的 15 分鐘傳播延遲時間，與 IAM 變更傳播所需的時間平行發生。

在 PostgreSQL 中授予或撤銷 IAM 群組的資料庫權限時，系統會立即生效。舉例來說，如果撤銷表格的存取權，該 IAM 群組的成員會立即失去表格存取權。

使用者或服務帳戶可以同時是多個 IAM 群組的成員。如果使用者或服務帳戶屬於執行個體上的多個 IAM 群組，則他們會擁有來自每個 IAM 群組的所有 IAM 權限和資料庫權限。

在 Cloud Identity 中將新成員 (使用者或服務帳戶) 新增至 IAM 群組後，只要新成員首次成功登入執行個體，就會自動繼承授予該群組的資料庫權限。

將資料庫權限授予個別 IAM 使用者或服務帳戶

將個別 IAM 使用者或服務新增至 Cloud SQL 執行個體時，系統預設不會授予新帳戶任何資料庫的權限。他們只能對已授予 PUBLIC 存取權的任何資料庫物件執行查詢。

如果需要其他存取權，可以使用 GRANT 陳述式授予更多權限。如需可授予使用者和服務帳戶的完整權限清單，請參閱 GRANT 參考頁面。從指令列執行 GRANT。

更改下列內容：

• USERNAME：使用者的電子郵件地址。電子郵件地址含有特殊字元 (@ 和 .)，因此必須加上引號
• TABLE_NAME：您要授予使用者存取權的資料表名稱。

grant select on TABLE_NAME to "USERNAME";

將資料庫權限授予 IAM 群組

使用 IAM 群組驗證時，您會將資料庫權限授予 IAM 群組，而非個別使用者或服務帳戶。根據預設，將 IAM 群組新增至 Cloud SQL 執行個體時，該群組沒有任何資料庫權限。

如要將資料庫權限授予 IAM 群組，請使用 GRANT 陳述式。群組成員 (包括使用者和服務帳戶) 首次登入 Cloud SQL 執行個體後，系統會自動將授予群組的資料庫權限指派給他們。

更改下列內容：

• GROUP_NAME：Cloud Identity 群組的電子郵件地址，包括 @ 和網域名稱。舉例來說，如果 IAM 群組的電子郵件地址是 [e-mail]，則群組名稱為 [e-mail]。由於字串含有特殊字元 (@ 和 .)，因此群組名稱必須加上引號
• TABLE_NAME：您要授予使用者存取權的資料表名稱。

從 psql 指令列執行 GRANT。

grant select on TABLE_NAME to "GROUP_NAME";

如要進一步瞭解如何授予權限，請參閱 PostgreSQL 說明文件中的「GRANT」參考頁面。

您授予 IAM 群組的資料庫權限會立即生效。

查看新增至 Cloud SQL 執行個體的 IAM 使用者、服務帳戶和群組

如要查看已新增至 Cloud SQL 執行個體的 IAM 使用者、服務帳戶和群組，請執行下列指令。

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在 SQL 導覽選單中選取「使用者」。 這個頁面會顯示已新增至執行個體的 IAM 使用者、服務帳戶和 Cloud Identity 群組清單。
4. 選用：如要查看已登入執行個體的 IAM 使用者或服務帳戶清單，請按一下「已通過驗證的 IAM 群組成員」。

gcloud

將 INSTANCE_NAME 替換為要查看群組的執行個體名稱。

  gcloud sql users list --instance=INSTANCE_NAME
  

群組的使用者類型為 CLOUD_IAM_GROUP。

輸出內容也會列出 Cloud SQL 執行個體上的使用者和服務帳戶。

• 群組成員的使用者帳戶類型為 CLOUD_IAM_GROUP_USER。
• 群組成員服務帳戶的類型為 CLOUD_IAM_GROUP_SERVICE_ACCOUNT。
• 個別 IAM 資料庫驗證使用者帳戶的使用者帳戶類型為 CLOUD_IAM_USER。
• 個別 IAM 資料庫驗證服務帳戶的服務帳戶類型為 CLOUD_IAM_SERVICE_ACCOUNT。

REST v1

以下要求使用 users.list 方法，列出在 Cloud SQL 執行個體中擁有帳戶的使用者。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：專案 ID
• INSTANCE_ID：執行個體 ID

HTTP 方法和網址：

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users/list

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users/list"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users/list" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#usersList",
  "items": [
    {
     "kind": "sql#user",
     "etag": "--redacted--",
     "name": "example-service-acct@PROJECT_ID.iam",
     "host": "",
     "instance": "INSTANCE_ID",
     "project": "PROJECT_ID",
     "type": "CLOUD_IAM_SERVICE_ACCOUNT"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "another-example-service-acct@PROJECT_ID.iam",
      "host": "",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_SERVICE_ACCOUNT"
     },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "postgres",
      "host": "",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "[e-mail]",
      "host": "",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_USER"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "[e-mail]",
      "host": "",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_USER"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "[e-mail]",
      "host": "",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP"
    }
  ]
}

群組的使用者類型為 CLOUD_IAM_GROUP。

輸出內容也會列出 Cloud SQL 執行個體上的使用者和服務帳戶。

• 群組成員的使用者帳戶類型為 CLOUD_IAM_GROUP_USER。
• 群組成員服務帳戶的類型為 CLOUD_IAM_GROUP_SERVICE_ACCOUNT。
• 個別 IAM 資料庫驗證使用者帳戶的使用者帳戶類型為 CLOUD_IAM_USER。
• 個別 IAM 資料庫驗證服務帳戶的服務帳戶類型為 CLOUD_IAM_SERVICE_ACCOUNT。

REST v1beta4

以下要求使用 users.list 方法，列出在 Cloud SQL 執行個體中擁有帳戶的使用者。

使用任何要求資料之前，請先替換以下項目：

• project-id：您的專案 ID
• instance-id：所需執行個體 ID

HTTP 方法和網址：

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#usersList",
  "items": [
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "sqlserver",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-1",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-2",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

群組的使用者類型為 CLOUD_IAM_GROUP。

輸出內容也會列出 Cloud SQL 執行個體上的使用者和服務帳戶。

• 群組成員的使用者帳戶類型為 CLOUD_IAM_GROUP_USER。
• 群組成員服務帳戶的類型為 CLOUD_IAM_GROUP_SERVICE_ACCOUNT。
• 個別 IAM 資料庫驗證使用者帳戶的使用者帳戶類型為 CLOUD_IAM_USER。
• 個別 IAM 資料庫驗證服務帳戶的服務帳戶類型為 CLOUD_IAM_SERVICE_ACCOUNT。

從 Cloud SQL 執行個體移除個別 IAM 使用者或服務帳戶

如要從 Cloud SQL 執行個體中移除不是群組成員的個別使用者或服務帳戶，請使用下列指令刪除該帳戶：

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在 SQL 導覽選單中選取「使用者」。
4. 找出要移除的使用者，然後按一下 。
5. 選取「移除」。這項操作只會撤銷這個執行個體的存取權。

gcloud

撤銷使用者

使用電子郵件地址 (例如 [e-mail]) 識別使用者。

更改下列內容：

• USERNAME：電子郵件地址。
• INSTANCE_NAME：要移除使用者存取權的執行個體名稱。

gcloud sql users delete USERNAME \
--instance=INSTANCE_NAME

刪除個別服務帳戶

更改下列內容：

• SERVICE_ACCT：服務帳戶的電子郵件地址。
• INSTANCE_NAME：要從中移除使用者的執行個體名稱。

gcloud sql users delete SERVICE_ACCT \
--instance=INSTANCE_NAME

REST v1

以下要求使用 users.delete 方法刪除指定使用者帳戶。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：您的專案 ID
• INSTANCE_ID：所需執行個體 ID
• USERNAME：使用者或服務帳戶的電子郵件地址

HTTP 方法和網址：

DELETE https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "DELETE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

以下要求使用 users.delete 方法刪除指定使用者帳戶。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：您的專案 ID
• INSTANCE_ID：所需執行個體 ID
• USERNAME：使用者或服務帳戶的電子郵件地址

HTTP 方法和網址：

DELETE https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "[e-mail]",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "DELETE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

從 Cloud SQL 執行個體移除 IAM 群組成員

從 Cloud SQL 執行個體移除 IAM 群組成員的方法有兩種：

• 自動移除
• 手動移除

自動移除

如要移除 IAM 群組成員，您必須在 Cloud Identity 中，從適用的 IAM 群組移除成員資格。身分與存取權管理群組使用者失去 Cloud Identity 中所有適用群組的成員資格後，Cloud SQL 會自動從執行個體中移除這些群組使用者。但如果群組使用者擁有資料庫物件，就不會遭到移除。您必須手動移除這些群組使用者。

群組成員如有變動 (例如新增或移除成員)，大約需要 15 分鐘才會全面套用。Cloud SQL 的 15 分鐘傳播延遲時間，與 IAM 變更傳播所需的時間並行。

手動移除

如果無法自動移除 IAM 群組使用者，您可以手動移除。您無法使用 gcloud CLI、Google Cloud 主控台、Terraform 或 Cloud SQL Admin API，手動從 Cloud SQL 執行個體移除 IAM 群組使用者。不過，具有超級使用者權限的資料庫使用者，可以透過 PostgreSQL 用戶端的 DROP USER 陳述式，手動從 Cloud SQL 執行個體刪除 IAM 群組使用者。

手動從 Cloud SQL 執行個體移除 IAM 群組使用者後，請務必也從 Cloud Identity 的 IAM 群組中移除該使用者，以免他們繼續登入 Cloud SQL 執行個體。

從 Cloud SQL 執行個體刪除 IAM 群組

您可以從 Cloud SQL 執行個體中刪除已新增的 IAM 群組。從執行個體刪除 IAM 群組後，所有屬於該 IAM 群組的使用者和服務帳戶，都會失去授予該 IAM 群組的任何資料庫權限。此外，還須符合下列條件：

• 從 IAM 群組移除 cloudsql.instances.login IAM 權限後，屬於該群組的使用者和服務帳戶就無法登入。
• 如果刪除群組後，執行個體上沒有其他群組包含該 IAM 群組使用者或服務帳戶，Cloud SQL 就會從執行個體中移除該 IAM 群組使用者或服務帳戶。
• 不過，如果 IAM 群組使用者擁有執行個體上的資料庫物件，您必須重新指派物件擁有權，才能手動捨棄使用者。

如果從 Cloud SQL 執行個體中刪除所有 IAM 群組，所有 IAM 群組使用者和服務帳戶都會失去所有資料庫權限。此外，還須符合下列條件：

• 所有 IAM 群組使用者和服務帳戶都無法登入執行個體。
• Cloud SQL 也會自動從執行個體中移除所有 IAM 群組使用者和服務帳戶。
• 不過，如果 IAM 群組使用者擁有執行個體上的資料庫物件，您必須重新指派物件擁有權，才能手動捨棄使用者。

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
3. 在 SQL 導覽選單中選取「使用者」。
4. 按一下要移除的群組 。
5. 選取「移除」。這項操作只會撤銷這個執行個體的存取權。

gcloud

如要從執行個體中刪除 Cloud Identity 群組，請使用 gcloud sql users delete 指令。

更改下列內容：

• GROUP_NAME：Cloud Identity 群組電子郵件地址的第一部分。舉例來說，如果電子郵件地址是 [e-mail]，Cloud Identity 群組名稱就是 example-group。
• INSTANCE_NAME：要刪除 Cloud Identity 群組的 Cloud SQL 執行個體名稱。

gcloud sql users delete GROUP_NAME \
   --instance=INSTANCE_NAME

從 IAM 群組移除 IAM 登入權限

如果從 IAM 群組撤銷 cloudsql.instanceUser 角色，該群組的所有成員就無法登入專案中的任何 Cloud SQL 執行個體。使用者或服務帳戶必須是另一個仍具備登入權限的 IAM 群組成員，才能登入執行個體。

如要撤銷 Cloud Identity 群組的角色，請參閱「撤銷單一角色」。

注意： 群組登入權限變更最多可能需要 15 分鐘才會生效。

從 IAM 群組中移除使用者

您可以從 Cloud Identity 的 IAM 群組中移除 IAM 群組成員，例如使用者或服務帳戶。

移除作業在 IAM 中傳播後，使用者就無法再登入資料庫，除非他們已從其他群組取得登入權限，或是直接獲准登入。此外，從群組中移除的使用者會失去該群組的資料庫權限。

如果 IAM 群組使用者不屬於執行個體上的任何群組，Cloud SQL 會自動從執行個體中移除該使用者。不過，如果 Cloud SQL 偵測到 IAM 群組使用者擁有執行個體上的物件，Cloud SQL 就不會移除該使用者。管理員必須重新指派物件擁有權，並手動移除使用者。

在稽核記錄中查看登入資訊

您可以啟用稽核記錄，擷取資料庫的 IAM 登入資訊。 如果發生登入問題，可以使用稽核記錄診斷問題。

注意： 稽核記錄會產生額外費用。詳情請參閱「記錄資料的定價」。

設定完成後，您可以使用記錄檔探索工具，查看登入成功的資料存取稽核記錄。

如果是 IAM 群組驗證，稽核記錄會顯示個別使用者和服務帳戶的活動和登入記錄。

舉例來說，記錄可能包含類似下列的資訊：

{
 insertId: "..."
 logName: "projects/.../logs/cloudaudit.googleapis.com%2Fdata_access"
 protoPayload: {
  @type: "type.googleapis.com/google.cloud.audit.AuditLog"
  authenticationInfo: {
   principalEmail: "..."
  }
  authorizationInfo: [
   0: {
    granted: true
    permission: "cloudsql.instances.login"
    resource: "instances/..."
    resourceAttributes: {
    }
   }
  ]
  methodName: "cloudsql.instances.login"
  request: {
   @type: "type.googleapis.com/google.cloud.sql.authorization.v1.InstancesLoginRequest"
   clientIpAddress: "..."
   database: "..."
   databaseSessionId: ...
   instance: "projects/.../locations/us-central1/instances/..."
   user: "..."
  }
  requestMetadata: {
   callerIp: "..."
   destinationAttributes: {
   }
   requestAttributes: {
    auth: {
    }
    time: "..."
   }
  }
  resourceName: "instances/..."
  serviceName: "cloudsql.googleapis.com"
  status: {
  }
 }
 receiveTimestamp: "..."
 resource: {
  labels: {
   database_id: "...:..."
   project_id: "..."
   region: "us-central"
  }
  type: "cloudsql_database"
 }
 severity: "INFO"
 timestamp: "..."
}

排解登入失敗問題

登入嘗試失敗時，PostgreSQL 會基於安全考量傳回最少的錯誤訊息。例如：

PGPASSWORD=not-a-password psql --host=... --username=... --dbname=...
psql: error: could not connect to server: FATAL:  Cloud SQL IAM user authentication failed for user "..."
FATAL:  pg_hba.conf rejects connection for host "...", user "...", database "...", SSL off

您可以查看 PostgreSQL 錯誤記錄，進一步瞭解錯誤詳情。詳情請參閱查看記錄。

舉例來說，針對先前的錯誤，以下記錄項目說明瞭可採取哪些行動來解決問題。

F ... [152172]: [1-1] db=...,user=... FATAL:  Cloud SQL IAM user authentication failed for user "..."
I ... [152172]: [2-1] db=...,user=... DETAIL:  Request is missing required authentication credential. Expected OAuth 2 access token, log in cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.

查看收到的錯誤訊息。如果訊息未指出您使用「Cloud SQL 身分與存取權管理使用者驗證」或「Cloud SQL 身分與存取權管理服務帳戶驗證」，請確認用於登入的資料庫使用者類型為 CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT。 您可以使用 Google Cloud 主控台或 gcloud sql users list 指令檢查這項設定。 如果是 IAM 使用者，請確認資料庫使用者名稱是 IAM 使用者的電子郵件地址。

如果您使用 IAM 資料庫驗證，請查看錯誤訊息的詳細資料。您可以在資料庫錯誤記錄中找到錯誤訊息。如果系統指出您以密碼形式傳送的存取權杖 (OAuth 2.0) 無效，可以使用 gcloud auth application-default print-access-token gcloud 指令找出權杖的詳細資料，如下所示：

curl -H "Content-Type: application/x-www-form-urlencoded" \
-d "access_token=$(gcloud auth application-default print-access-token)" \
https://www.googleapis.com/oauth2/v1/tokeninfo

確認權杖適用於預期的 IAM 使用者或服務帳戶，且尚未過期。

如果詳細資料顯示缺少權限，請確認 IAM 使用者或服務帳戶已在執行個體專案的 IAM 政策中，使用預先定義的 Cloud SQL Instance User 角色或自訂角色授予 cloudsql.instances.login 權限。如需其他協助，請使用 IAM 政策疑難排解工具。

如果因 IAM 資料庫驗證機制無法使用而登入失敗，使用者可以透過預設的 PostgreSQL 使用者名稱和密碼登入。使用者仍可透過這種登入方式存取整個資料庫。確認連線是否安全。

排解使用 IAM 群組驗證功能的使用者帳戶問題

本節列出 IAM 群組驗證的疑難排解情境。

無法將群組新增至資料庫

嘗試將群組新增至執行個體時，您會收到下列錯誤訊息：

(gcloud.sql.users.create) HTTPError 400: Invalid request: Provided CLOUD_IAM_GROUP: EMAIL, does not exist.

確認您提供的電子郵件地址是有效的群組。

如果群組尚未建立，請建立群組。 如要進一步瞭解如何建立群組，請參閱「在 Google Cloud 控制台中建立及管理 Google 群組」。

如果收到下列錯誤訊息：

(gcloud.sql.users.create) HTTPError 400: Invalid request: IAM Group Authentication is disabled.

然後，您必須先為 Cloud SQL 執行個體進行下列維護更新，才能使用 IAM 群組驗證：

R20240514.00_04 以上版本

您可以透過自助式維護功能，將維護更新套用到執行個體。詳情請參閱「自助式維護」。

現有的 IAM 使用者或服務帳戶未沿用授予其 IAM 群組的資料庫權限

如果現有的 IAM 使用者或服務帳戶未沿用所屬群組的正確資料庫權限，請完成下列步驟：

1. 前往 Google Cloud 控制台的「IAM」頁面。

   前往「IAM」頁面

   確認帳戶是已新增至 Cloud SQL 執行個體的群組成員。

2. 列出執行個體上的使用者和服務帳戶。

   gcloud sql users list --instance=INSTANCE_NAME

   在輸出內容中，檢查使用者或服務帳戶是否列為 CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT。

3. 如果使用者或服務帳戶列為 CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT，請從執行個體中移除該帳戶。您要移除的帳戶是個別 IAM 帳戶，不會沿用群組的資料庫權限。

4. 使用使用者或服務帳戶再次登入執行個體。

   再次登入執行個體時，系統會以正確的帳戶類型 (CLOUD_IAM_GROUP_USER 或 CLOUD_IAM_GROUP_SERVICE_ACCOUNT) 重新建立帳戶。

後續步驟

• 進一步瞭解 IAM 資料庫驗證。
• 瞭解如何登入 Cloud SQL 資料庫。
• 瞭解如何設定執行個體，以便進行 IAM 資料庫驗證。