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

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

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

事前準備

  1. 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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Install the gcloud CLI.

  4. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  5. To initialize the gcloud CLI, run the following command: 

    gcloud init
  6. 確認您的使用者帳戶具備 Cloud SQL 管理員角色。

    前往「IAM」頁面

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

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

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

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

資料庫使用者名稱必須是 IAM 使用者的電子郵件地址，例如 example-user@example.com。由於包含特殊字元 (@ 和 .)，因此必須全部使用小寫字母並加上引號。

控制台

  1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

    前往「IAM」頁面

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

gcloud

執行 gcloud projects add-iam-policy-binding 並加上 --role=roles/cloudsql.instanceUser 旗標。

將政策繫結新增至使用者帳戶

更改下列內容：

  • 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：群組的電子郵件地址。例如 example-group@example.com。
  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:test-user@example.com",
    "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:test-user@example.com",
    "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 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

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

  1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
    deletion_protection =  "false"
  2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
    terraform apply

  1. 執行下列指令，並在提示中輸入 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:example-group@example.com"
  ]
}

套用變更

如要在 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 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

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

  1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
    deletion_protection =  "false"
  2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
    terraform apply

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

    terraform destroy

REST

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

    {
      "role": "roles/cloudsql.instanceUser",
      "members": [
                   "user:example-user@example.com"
                   "serviceAccount:service1@sql."
                   "group:example-group@example.com"
      ]
    }
    {
      "role": "roles/cloudsql.client",
      "members": [
                   "user:example-user@example.com"
                   "serviceAccount:service1@sql."
      ]
    }

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

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

資料庫使用者名稱必須是 IAM 使用者的電子郵件地址，且全部使用小寫。例如 example-user@example.com。

使用 REST 指令時，使用者名稱必須使用引號，因為其中包含特殊字元 (@ 和 .)。服務帳戶使用 service-account-name@project-id. 格式。

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

控制台

的「IAM roles」(IAM 角色) 專區，查看這個 IAM 角色的指派詳細資料。

  1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 按一下「新增使用者帳戶」。「Add a user account to instance instance_name」(將使用者帳戶新增至執行個體 instance_name)instance_name 分頁隨即開啟。
  5. 點選「Cloud IAM」圓形按鈕。
  6. 在「Principal」(主體) 欄位中，新增要新增的使用者或服務帳戶電子郵件地址。
  7. 按一下「Add」(新增)。使用者或服務帳戶現在會顯示在使用者帳戶清單中。

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

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

gcloud

建立使用者帳戶

使用電子郵件地址 (例如 example-user@example.com) 識別使用者。

更改下列內容：

  • USERNAME：使用者的電子郵件地址。
  • INSTANCE_NAME：要授權使用者存取的執行個體名稱。
gcloud sql users create USERNAME \
--instance=INSTANCE_NAME \
--type=cloud_iam_user

建立使用者帳戶時，您可以指派一或多個資料庫角色，為使用者提供資料庫權限。

建立服務帳戶

更改下列內容：

  • SERVICE_ACCT：服務帳戶的電子郵件地址。
  • 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             = "mysql-db-auth-instance-name-test"
  region           = "us-west4"
  database_version = "MYSQL_8_0"
  settings {
    tier = "db-f1-micro"
    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     = "test-user@example.com"
  instance = google_sql_database_instance.default.name
  type     = "CLOUD_IAM_USER"
}

# Create a new IAM service account

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

# Specify the email address of the IAM service account to add to the instance

resource "google_sql_user" "iam_service_account_user" {
  name     = google_service_account.default.email
  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 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

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

  1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
    deletion_protection =  "false"
  2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
    terraform apply

  1. 執行下列指令，並在提示中輸入 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"
}

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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"
}

建立服務帳戶

使用任何要求資料之前，請先修改下列項目的值：

  • SERVICE_ACCT：服務帳戶電子郵件
  • 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"
}

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

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

{
"kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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"
  }

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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"
}

建立服務帳戶

使用任何要求資料之前，請先修改下列項目的值：

  • SERVICE_ACCT：服務帳戶電子郵件
  • 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"
}

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

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

{
"kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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 執行個體」。

Cloud SQL 執行個體最多可同時存在 200 個 IAM 群組。閒置群組也會計入這項限制。

IAM 群組名稱的長度限制與 MySQL 使用者名稱相同，只能有 32 個字元。

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

控制台

的「IAM 角色」中，查看 IAM 角色指派詳細資料。

  1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 按一下「新增使用者帳戶」。「Add a user account to instance instance_name」(將使用者帳戶新增至執行個體 instance_name)instance_name 分頁隨即開啟。
  5. 點選「Cloud IAM」圓形按鈕。
  6. 在「Principal」(主體) 欄位中，新增要加入的群組電子郵件地址。
  7. 按一下「Add」(新增)。群組現在會顯示在使用者清單中。

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

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

gcloud

更改下列內容：

  • GROUP_EMAIL_ADDRESS：要新增至執行個體的 Cloud Identity 群組電子郵件地址。例如 example-group@example.com。
  • 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             = "mysql-iam-group-auth-instance-name"
  region           = "us-west4"
  database_version = "MYSQL_8_0"
  settings {
    tier = "db-f1-micro"
    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     = "example-group@example.com"
  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:example-group@example.com"
  ]
}

套用變更

如要在 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 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

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

  1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
    deletion_protection =  "false"
  2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
    terraform apply

  1. 執行下列指令，並在提示中輸入 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"
}

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "example-group@example.com",
  "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"
}

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "example-group@example.com",
  "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"
}

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

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

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

將現有 IAM 使用者遷移至 IAM 群組驗證機制

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

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

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

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

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

  4. 將指派給 IAM 使用者的資料庫權限指派給要遷移至群組的使用者。

  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 變更傳播所需的時間同時發生。

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

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

當您在 Cloud Identity 將新成員 (使用者或服務帳戶) 新增至 IAM 群組，且該成員首次成功登入執行個體時，就會自動繼承授予群組的資料庫權限。如要在同一個登入工作階段中使用新取得的資料庫權限，請使用下列陳述式。

SET ROLE ALL;

詳情請參閱 MySQL 說明文件中的 SET ROLE。

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

將個別 IAM 使用者或服務新增至 Cloud SQL 執行個體時，根據預設，該新帳戶不會獲得任何資料庫的權限。您可以將個別資料庫權限指派給帳戶，也可以建立資料庫角色，然後將資料庫角色指派給 IAM 使用者或服務帳戶。

如要將個別資料庫權限授予帳戶，請使用 GRANT 陳述式。如要查看可授予使用者和服務帳戶的完整權限清單，請參閱 GRANT 參考頁面。從 mysql 指令列執行 GRANT。

更改下列內容：

  • USERNAME：如果是使用者帳戶，這是 IAM 使用者的電子郵件地址，其中 @ 和網域字串會遭到截斷。舉例來說，如果 IAM 使用者的電子郵件地址是 example-user@example.com，使用者名稱就會是 example-user。如果是服務帳戶，則為服務帳戶的電子郵件地址，不含 @project-id. 網域。
  • DATABASE_NAME：託管資料表的資料庫名稱。
  • TABLE_NAME：要授予使用者存取權的資料表名稱。
    • grant select on DATABASE_NAME.TABLE_NAME to "USERNAME";

    將資料庫權限授予 IAM 群組

    使用 IAM 群組驗證時，您會將資料庫權限授予 IAM 群組，而非個別使用者或服務帳戶。根據預設，將 IAM 群組新增至 Cloud SQL 執行個體時，群組沒有資料庫權限。您可以將個別資料庫權限指派給群組，也可以建立資料庫角色，然後將資料庫角色指派給 IAM 群組。

    如要將個別資料庫權限授予 IAM 群組，請使用 GRANT 陳述式。首次登入 Cloud SQL 執行個體後，每位群組成員 (包括使用者和服務帳戶) 都會自動繼承授予群組的資料庫權限。

    更改下列內容：

  • GROUP_NAME：Cloud Identity 群組電子郵件地址的第一部分，不含 @ 和網域名稱。舉例來說，如果 IAM 群組的電子郵件地址是 example-group@example.com，則群組名稱為 example-group。
  • DATABASE_NAME：託管資料表的資料庫名稱。
  • TABLE_NAME：要授予使用者存取權的資料表名稱。

    • 從 mysql 指令列執行 GRANT。

    grant select on DATABASE_NAME.TABLE_NAME to "GROUP_NAME"@"HOSTNAME";

    將 HOSTNAME 替換為 IAM 群組電子郵件地址的網域名稱。

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

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

    將 IAM 帳戶新增至執行個體時指派資料庫角色

    如要在 MySQL 中建立自訂資料庫角色，請參閱「使用角色」。

    gcloud

    建立使用者帳戶

    使用電子郵件地址 (例如 example-user@example.com) 識別使用者。

    gcloud sql users create USERNAME \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_user \
  --database-roles=ROLE_1, ROLE_2

    更改下列內容：

    • USERNAME：使用者的電子郵件地址。
    • INSTANCE_NAME：要授權使用者存取的執行個體名稱。
    • ROLE_1、ROLE_2、...、ROLE_N：要指派給使用者的資料庫角色。

    建立服務帳戶

    gcloud sql users create SERVICE_ACCOUNT \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_service_account \
  --database-roles=ROLE_1, ROLE_2

    更改下列內容：

    • SERVICE_ACCOUNT：服務帳戶的電子郵件地址。
    • INSTANCE_NAME：要授權服務帳戶存取的執行個體名稱。
    • ROLE_1、ROLE_2、...、ROLE_N：要指派給服務帳戶的一或多個資料庫角色。

    建立群組

    gcloud sql users create GROUP_EMAIL_ADDRESS \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_group \
  --database-roles=ROLE_1, ROLE_2

    更改下列內容：

    • GROUP_EMAIL_ADDRESS：要新增至執行個體的 Cloud Identity 群組電子郵件地址。例如 example-group@example.com。
    • INSTANCE_NAME：要新增群組的執行個體名稱。
    • ROLE_1、ROLE_2、...、ROLE_N：要指派給服務帳戶的一或多個資料庫角色。

    Terraform

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

    resource "google_sql_user" "iam_user" {
  name     = "test-user@example.com"
  instance = google_sql_database_instance.default.name
  type     = "CLOUD_IAM_USER"
  # Specify the list of database roles to be granted to the user
  # The database roles must exist in the database.
  database_roles = ["cloudsqlsuperuser"]
}

    套用變更

    如要在 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 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

    刪除變更

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

    1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
      deletion_protection =  "false"
    2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
      terraform apply

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

      terraform destroy

    REST v1

    使用任何要求資料之前，請先修改下列項目的值：

    • PROJECT_ID：專案 ID
    • INSTANCE_ID：要新增使用者的執行個體 ID
    • USERNAME：使用者的電子郵件地址
    • USER_TYPE：Cloud SQL 使用者類型，為下列其中一種 IAM 使用者類型：
      • CLOUD_IAM_USER
      • CLOUD_IAM_SERVICE_ACCOUNT
      • CLOUD_IAM_GROUP
    • ROLE_1、ROLE_2 ...、ROLE_N：要指派給 IAM 使用者、服務帳戶或群組的一或多個資料庫角色

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "name": "USERNAME",
  "type": "USER_TYPE",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ]
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-07T22:44:16.656Z",
  "startTime": "2025-10-07T22:44:16.686Z",
  "endTime": "2025-10-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：要新增使用者的執行個體 ID
    • USERNAME：使用者的電子郵件地址
    • USER_TYPE：Cloud SQL 使用者類型，為下列其中一種 IAM 使用者類型：
      • CLOUD_IAM_USER
      • CLOUD_IAM_SERVICE_ACCOUNT
      • CLOUD_IAM_GROUP
    • ROLE_1、ROLE_2 ...、ROLE_N：要指派給 IAM 使用者、服務帳戶或群組的一或多個資料庫角色

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "name": "USERNAME",
  "type": "CLOUD_IAM_USER",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ]
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-07T22:44:16.656Z",
  "startTime": "2025-10-07T22:44:16.686Z",
  "endTime": "2025-10-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 群組新增至 Cloud SQL 執行個體後，您可以修改指派給該執行個體的資料庫角色。您可以指派為資料庫定義的資料庫角色。您指派的資料庫角色會新增至已指派給帳戶的任何角色。如要取代資料庫角色，則必須使用 --revoke-existing-roles 旗標撤銷資料庫角色。

    您必須先建立角色，才能在 MySQL 適用的 Cloud SQL 中將角色指派給主體。如果您使用的是自訂角色，請先在 MySQL 資料庫中建立角色。

    如要在 MySQL 中建立角色，請參閱「使用角色」。

    gcloud

    更新使用者帳戶

    使用電子郵件地址 (例如 example-user@example.com) 識別使用者。

    如要為使用者帳戶新增資料庫角色，請使用下列指令：

    gcloud sql users assign-roles USERNAME \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_user \
  --database-roles=ROLE_1, ROLE_2

    如要取代使用者帳戶的資料庫角色，請使用下列指令：

    gcloud sql users assign-roles USERNAME \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_user \
  --database-roles=ROLE_1, ROLE_2
  --revoke-existing-roles

    更改下列內容：

    • USERNAME：使用者的電子郵件地址。
    • INSTANCE_NAME：要授權使用者存取的執行個體名稱。
    • ROLE_1、ROLE_2、...、ROLE_N：要指派給使用者的資料庫角色。

    更新服務帳戶

    如要為服務帳戶新增資料庫角色，請使用下列指令：

    gcloud sql users assign-roles SERVICE_ACCT \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_service_account \
  --database-roles=ROLE_1, ROLE_2

    如要取代服務帳戶的資料庫角色，請使用下列指令：

    gcloud sql users assign-roles SERVICE_ACCT \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_service_account \
  --database-roles=ROLE_1, ROLE_2
  --revoke-existing-roles

    更改下列內容：

    • SERVICE_ACCT：服務帳戶的電子郵件地址。
    • INSTANCE_NAME：要授權服務帳戶存取的執行個體名稱。
    • ROLE_1、ROLE_2、...、ROLE_N：要指派給服務帳戶的一或多個資料庫角色。

    更新群組

    如要為群組新增資料庫角色，請使用下列指令： 
    gcloud sql users assign-roles GROUP_EMAIL_ADDRESS \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_group \
  --database-roles=ROLE_1, ROLE_2

    如要取代群組的資料庫角色，請使用下列指令：

    gcloud sql users assign-roles GROUP_EMAIL_ADDRESS \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_group \
  --database-roles=ROLE_1, ROLE_2
  --revoke-existing-roles

    更改下列內容：

    • GROUP_EMAIL_ADDRESS：要新增至執行個體的 Cloud Identity 群組電子郵件地址。例如 example-group@example.com。
    • INSTANCE_NAME：要新增群組的執行個體名稱。
    • ROLE_1、ROLE_2、...ROLE_N：要指派給群組的一或多個資料庫角色。

    REST v1

    使用任何要求資料之前，請先修改下列項目的值：

    • PROJECT_ID：專案 ID
    • INSTANCE_ID：要新增使用者的執行個體 ID
    • USERNAME：使用者的電子郵件地址
    • USER_TYPE：Cloud SQL 使用者類型，為下列其中一種 IAM 使用者類型：
      • CLOUD_IAM_USER
      • CLOUD_IAM_SERVICE_ACCOUNT
      • CLOUD_IAM_GROUP
    • ROLE_1、ROLE_2 ...、ROLE_N：要指派給 IAM 使用者、服務帳戶或群組的一或多個資料庫角色
    • REVOKE_EXISTING_ROLES：設為 true 可撤銷使用者現有的角色，設為 false 則可保留使用者現有的角色

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "name": "USERNAME",
  "type": "USER_TYPE",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ],
  "revokeExistingRoles": REVOKE_EXISTING_ROLES
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-07T22:44:16.656Z",
  "startTime": "2025-10-07T22:44:16.686Z",
  "endTime": "2025-10-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：要新增使用者的執行個體 ID
    • USERNAME：使用者的電子郵件地址
    • USER_TYPE：Cloud SQL 使用者類型，可以是下列其中一種 IAM 使用者類型：
      • CLOUD_IAM_USER
      • CLOUD_IAM_SERVICE_ACCOUNT
      • CLOUD_IAM_GROUP
    • ROLE_1、ROLE_2 ...、ROLE_N：要指派給 IAM 使用者、服務帳戶或群組的一或多個資料庫角色
    • REVOKE_EXISTING_ROLES：設為 true 可撤銷使用者現有的角色，設為 false 則可保留使用者現有的角色

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "name": "USERNAME",
  "type": "USER_TYPE",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ],
  "revokeExistingRoles": REVOKE_EXISTING_ROLES
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-07T22:44:16.656Z",
  "startTime": "2025-10-07T22:44:16.686Z",
  "endTime": "2025-10-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"
}

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

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

    控制台

    1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

      前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

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

    gcloud

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

      gcloud sql users list --instance=INSTANCE_NAME

    群組的使用者類型為 CLOUD_IAM_GROUP。

    IAM_STATUS 欄會顯示群組是否有效。ACTIVE IAM 群組可用於 IAM 群組驗證。INACTIVE IAM 群組無法用於 IAM 群組驗證。

    輸出內容也會列出 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

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

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

    
{
  "kind": "sql#usersList",
  "items": [
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-service-acct",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_SERVICE_ACCOUNT",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "another-example-service-acct",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_SERVICE_ACCOUNT",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "root",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "passwordPolicy": {
        "status": {}
      },
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-user",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_USER",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "another-example-user",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_USER",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-group",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP",
      "iamStatus": "ACTIVE"
    }
  ]
}

    群組的使用者類型為 CLOUD_IAM_GROUP。

    群組會透過 iamStatus 欄位顯示是否處於有效狀態。ACTIVE IAM 群組可用於 IAM 群組驗證。INACTIVE IAM 群組不會用於 IAM 群組驗證。

    iamStatus 欄位的值 IAM_STATUS_UNSPECIFIED 表示 IAM 狀態與該特定使用者類型無關。

    輸出內容也會列出 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/list

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

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

    
{
  "kind": "sql#usersList",
  "items": [
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-service-acct",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_SERVICE_ACCOUNT",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "another-example-service-acct",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_SERVICE_ACCOUNT",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "root",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "passwordPolicy": {
        "status": {}
      },
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-user",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_USER",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "another-example-user",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP_USER",
      "iamStatus": "IAM_STATUS_UNSPECIFIED"
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "example-group",
      "host": "%",
      "instance": "INSTANCE_ID",
      "project": "PROJECT_ID",
      "type": "CLOUD_IAM_GROUP",
      "iamStatus": "ACTIVE"
    }
  ]
}

    群組的使用者類型為 CLOUD_IAM_GROUP。

    群組會透過 iamStatus 欄位顯示其為有效或無效。ACTIVE IAM 群組可用於 IAM 群組驗證。INACTIVE IAM 群組無法用於 IAM 群組驗證。

    iamStatus 欄位的值 IAM_STATUS_UNSPECIFIED 表示 IAM 狀態與該特定使用者類型無關。

    輸出內容也會列出 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 執行個體) 頁面。

      前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

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

    gcloud

    撤銷使用者

    使用電子郵件地址 (例如 example-user@example.com) 識別使用者。

    更改下列內容：

    • 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

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "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 群組移除其成員資格。當 IAM 群組使用者失去 Cloud Identity 中所有適用群組的成員資格後，Cloud SQL 會自動從執行個體中移除這些群組使用者。

    群組成員資格的變更 (例如新增或移除成員) 約需 15 分鐘才會生效。Cloud SQL 的 15 分鐘傳播延遲時間，與 IAM 變更傳播所需時間並行。

    手動移除

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

    從 Cloud SQL 執行個體手動移除 IAM 群組使用者後，請務必一併從 Cloud Identity 的 IAM 群組中移除該使用者，防止他們再次登入 Cloud SQL 執行個體。

    變更 Cloud SQL 執行個體上現有 IAM 群組成員的網域名稱

    如果您在 Cloud Identity 中變更組織的網域名稱，Cloud SQL 執行個體上的 IAM 群組成員不會自動套用變更。

    舉例來說，如果您在 Cloud Identity 中將 user@example.com 變更為 user@new-example.com，則即使 Cloud Identity 中的網域名稱已變更，user@example.com 仍會保留在 Cloud SQL 執行個體上。

    如要變更 IAM 群組成員的網域名稱，請按照下列步驟操作：

    1. 使用 IAM 群組成員自動移除程序，從執行個體中移除使用舊網域名稱的所有使用者。

    2. 以各個 IAM 群組成員的身分登入 Cloud SQL 執行個體，並使用具有新網域名稱的帳戶，重新建立帳戶。詳情請參閱「自動將群組成員新增至 Cloud SQL 執行個體」。

    如要變更 IAM 群組的網域名稱，請按照下列步驟操作：

    1. 使用 IAM 群組移除程序，從執行個體中移除使用舊網域名稱的所有群組。

    2. 使用 IAM 群組建立程序，將具有新網域的群組新增至執行個體。

    3. 重新授予 IAM 群組的資料庫權限。

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

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

    • 屬於 IAM 群組的使用者和服務帳戶仍可登入，直到從群組中移除 cloudsql.instances.login IAM 權限為止。
    • 如果刪除群組後，IAM 群組使用者或服務帳戶不屬於執行個體上的任何其他群組，Cloud SQL 會從執行個體中移除 IAM 群組使用者或服務帳戶。

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

    • 所有 IAM 群組使用者和服務帳戶都無法登入執行個體。
    • Cloud SQL 也會自動從執行個體中移除所有 IAM 群組使用者和服務帳戶。

    控制台

    1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

      前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

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

    gcloud

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

    更改下列內容：

    • GROUP_NAME：Cloud Identity 群組電子郵件地址的第一部分。舉例來說，如果使用電子郵件地址 example-group@example.com，Cloud Identity 群組名稱就是 example-group。
    • HOSTNAME：電子郵件地址的第二部分代表 Cloud Identity 群組的主機名稱。舉例來說，如果使用電子郵件地址 example-group@example.com，主機名稱就是 example.com。
    • INSTANCE_NAME：Cloud SQL 執行個體的名稱，其中包含要刪除的 Cloud Identity 群組。
    gcloud sql users delete GROUP_NAME \
   --host=HOSTNAME \
   --instance=INSTANCE_NAME

    從 IAM 或 Cloud Identity 刪除 IAM 群組

    如果從 IAM 或 Cloud Identity 刪除 IAM 群組，但未從 Cloud SQL 執行個體刪除，則該 IAM 群組會標示為 INACTIVE，並保留在執行個體上，直到您手動移除群組為止。

    無效的 IAM 群組無法用於 IAM 群組驗證。授予停用群組的資料庫權限不會傳遞給成員。無效群組不會計入有效的 IAM 群組成員資格。不屬於有效 IAM 的 IAM 群組使用者，無法使用 IAM 群組驗證功能進行驗證。

    如果 IAM 群組處於停用狀態，即使您在 IAM 和 Cloud Identity 中重新建立群組，該群組在 Cloud SQL 執行個體中仍會保持停用狀態。如要重新建立 IAM 群組名稱，請按照下列步驟操作：

    1. 在 IAM 和 Cloud Identity 中重新建立群組。

    2. 請按照 IAM 群組移除程序移除閒置群組。

    3. 請按照新增 IAM 群組的程序，將群組重新加入 Cloud SQL 執行個體。

    4. 將資料庫權限授予新建立的 IAM 群組。

    移除 IAM 群組的 IAM 登入權限

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

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

    從 IAM 群組中移除使用者

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

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

    如果 IAM 群組使用者不屬於執行個體上的任何群組，Cloud SQL 會自動從執行個體中移除該使用者。

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

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

    設定完成後，您可以使用Logs Explorer查看成功登入的資料存取稽核記錄。

    如果是 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: "..."
}

    疑難排解登入失敗問題

    登入失敗時，MySQL 會基於安全考量傳回簡短的錯誤訊息。例如：

    $MYSQL_PWD=`gcloud-access-token mysql` --enable-cleartext-plugin --ssl-ca=server-ca.pem
--ssl-cert=client-cert.pem --ssl-key=client-key.pem   --host=ip_address --user=testuser
Access denied for user 'testuser'@'...' (using password: NO)

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

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

    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 IAM 使用者驗證」或「Cloud SQL IAM 服務帳戶驗證」，請確認用於登入的資料庫使用者類型為 CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT。如果是 IAM 使用者，請確認資料庫使用者名稱是 IAM 使用者的電子郵件地址，但不含 @ 和網域。如果是服務帳戶，請確認這是服務帳戶的電子郵件，不含 @project-id.。

    如果您使用 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 使用者或服務帳戶已獲派 cloudsql.instances.login 權限。如要授予這項權限，請在執行個體專案的 IAM 政策，使用預先定義的 Cloud SQL Instance User 角色或自訂角色。如需其他協助，請使用 IAM 政策疑難排解工具。

    如果因 IAM 資料庫驗證功能無法使用而導致登入失敗，使用者可以使用預設的 MySQL 使用者和密碼登入。這種登入方法仍可讓使用者存取整個資料庫。確認連線安全無虞。

    排解使用 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 重新建立帳戶。

    後續步驟