本页面介绍如何将使用 IAM 数据库身份验证的用户或服务帐号添加到数据库,以及如何管理这些用户和服务帐号。如需详细了解 IAM 集成,请参阅 IAM 数据库身份验证概览。
准备工作
- 登录您的 Google Cloud 帐号。如果您是 Google Cloud 新手,请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
-
在 Google Cloud Console 中的项目选择器页面上,选择或创建一个 Google Cloud 项目。
-
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
- 安装并初始化 Google Cloud CLI。
-
在 Google Cloud Console 中的项目选择器页面上,选择或创建一个 Google Cloud 项目。
-
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
- 安装并初始化 Google Cloud CLI。
-
启用 Cloud Key Management Service API。
- 确保您的用户帐号具有 Cloud SQL Admin 角色。
- 在 Cloud SQL 实例上启用 IAM 数据库身份验证。
- 对于包含用户需要访问的数据库的每个项目,请确保向需要该权限的用户授予 IAM 访问权限。请参阅授予、更改和撤消对资源的访问权限。
- 确保您已为需要访问项目中的数据库的每个服务添加了服务帐号。
将 IAM 用户或服务帐号添加到数据库
对于您要有权访问数据库实例的每位 IAM 用户,您都必须为其创建一个新的数据库用户。数据库用户名必须是 IAM 用户的电子邮件地址,例如 test-user@gmail.com
。
使用 REST 命令时,用户名必须使用英文引号,因为它包含特殊字符(@
和 .
)。
服务帐号使用 service-account-name@project-id.iam.gserviceaccount.com
格式。
如需添加 IAM 用户或服务帐号,您需要添加新的数据库用户并选择 IAM 作为身份验证方法:
控制台
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
- 从 SQL 导航菜单中选择用户。
- 点击添加用户帐号。系统会打开将用户帐号添加到实例 instance_name 标签页。
- 点击 Cloud IAM 单选按钮。
- 在主帐号字段中添加要添加的用户或服务帐号的电子邮件地址。
- 点击添加。该用户现在位于用户列表中。
如果未将用户分配给 Cloud SQL Instance User 角色,则用户名左侧会显示一个
图标。
如需向用户授予登录权限,请点击该图标,然后选择添加 IAM 角色。图标不会再出现。该用户现在是该角色的成员。
gcloud
创建用户帐号
使用电子邮件地址(如 test-user@gmail.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
REST v1
创建用户帐号
在使用任何请求数据之前,请先进行以下替换:
- project-id:您的项目 ID
- instance-id:您要向其添加用户的实例的 ID
- username:用户的电子邮件地址
- operation-id:操作的 ID
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
- operation-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:用户的电子邮件地址
- operation-id:操作的 ID
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
- operation-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 用户授予数据库权限
默认情况下,将 IAM 用户添加到数据库实例时,该新用户不会对任何数据库授予权限。用户或服务帐号连接到数据库时,可以针对已被授予 PUBLIC 访问权限的任何数据库对象运行查询。
如果他们需要其他访问权限,可以使用 GRANT 语句授予更多权限。如需查看您可以向用户和服务帐号授予的完整权限列表,请参阅 GRANT 参考页面。从命令行运行 GRANT。
替换以下内容:
- USERNAME:用户的电子邮件地址。您必须使用英文引号括住电子邮件地址,因为它包含特殊字符(
@
和.
)。 - TABLE_NAME:您要向用户授予访问权限的表的名称。
grant select on TABLE_NAME to "USERNAME";
从数据库中移除 IAM 用户或服务帐号
要从数据库中移除用户或服务帐号,请从实例中删除该帐号:
控制台
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
- 从 SQL 导航菜单中选择用户。
- 针对您要移除的用户,点击 。
- 选择移除。这样只会撤消对此实例的访问权限。
gcloud
撤消用户
使用电子邮件地址(如 test-user@gmail.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 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" }
在审核日志中查看登录信息
您可以启用审核日志以捕获对数据库的 IAM 登录。如果出现登录问题,您可以使用审核日志来诊断问题。
注意:Audit Logging 会产生额外费用。如需了解详情,请参阅日志记录数据的价格。
配置后,您可以使用日志浏览器来查看成功登录的数据访问审核日志。
例如,日志可能包含类似如下所示的信息:
{
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 IAM 用户身份验证”还是“Cloud SQL IAM 服务帐号身份验证”,请验证用于登录的数据库用户类型是 CLOUD_IAM_USER
或 CLOUD_IAM_SERVICE_ACCOUNT
。您可以使用控制台或 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 用户或服务帐号,并且未过期。
如果详细信息指明缺少权限,请验证已使用预定义的 Cloud SQL Instance User
角色或实例项目的 IAM 政策中的自定义角色为 IAM 用户或服务帐号授予了 cloudsql.instances.login
权限。如需其他帮助,请使用 IAM 政策问题排查工具。
如果由于 IAM 数据库身份验证不可用而导致登录失败,则用户可以使用默认的 PostgreSQL 用户名和密码登录。这种登录方法仍可为用户提供整个数据库的访问权限。 验证连接是否为安全连接。
后续步骤
- 详细了解 IAM 数据库身份验证。
- 了解如何登录 Cloud SQL 数据库。
- 了解如何配置实例以使用 IAM 数据库身份验证。