使用 IAM 账号进行连接

本页面介绍了使用通过 Identity and Access Management (IAM) 准备的账号登录 AlloyDB for PostgreSQL 实例的过程。它通过展示如何使用 psql 命令行客户端执行基于 IAM 的登录，说明了该过程。

如需大致了解如何连接到 AlloyDB 实例，请参阅连接概览。

准备工作

在您使用 IAM 凭证登录 AlloyDB 实例之前，需要先准备好项目、集群、实例和 IAM 用户账号。

如需了解详情，请参阅管理 IAM 身份验证。

使用 OAuth 2.0 令牌进行身份验证

用户或应用可以按照以下步骤向 AlloyDB 数据库进行身份验证：

  1. 如果您尚未执行此操作，请使用您要用来登录 AlloyDB 实例的同一用户或服务账号授权 Google Cloud CLI。

  2. 使用 gcloud auth print-access-token 命令从 Google Cloud 请求 OAuth 2.0 令牌：

    gcloud auth print-access-token

    Google Cloud 会输出 OAuth 2.0 令牌作为此命令的输出。

    为了进一步提高安全性，您可以按照以下替代步骤将令牌的使用范围限制为仅用于 AlloyDB 身份验证：

    1. 使用 gcloud auth application-default login 命令将 alloydb.login 范围添加到当前环境的访问凭证（如果您尚未添加）：

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

    2. 使用 gcloud auth application-default print-access-token 命令输出受限的 OAuth 2.0 令牌，并将令牌范围限定为仅用于 AlloyDB 身份验证：

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

    借助 OAuth 2.0 令牌，您（或任何人）可以代表您向 Google Cloud 发出经过身份验证的请求。以与密码相同的安全级别使用令牌。要么安全地存储令牌，要么完全避免存储令牌。本页面稍后对 psql 的使用示例展示了在单个操作中请求、使用和舍弃 OAuth 2.0 令牌的方法。

  3. 使用标准 PostgreSQL 技术和以下凭证登录 AlloyDB 实例：

    • 将您在上一步中获取的访问令牌作为密码提供。

    • 对于 IAM 用户账号，数据库用户名是该账号的完整邮箱。

    • 对于 IAM 服务账号，数据库用户名是该账号的邮箱（不带 .gserviceaccount.com 后缀）。

以下 psql 命令演示了一种在命令行中登录 IAM 用户的方法。它将 gcloud auth print-access-token 的输出分配给 PGPASSWORD 环境变量，psql 随后用作数据库登录密码。

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

替换以下内容：

  • INSTANCE_ADDRESS：要连接到的 AlloyDB 实例的 IP 地址。

  • USERNAME：用于向实例进行身份验证的 IAM 用户标识符。

    对于 IAM 用户账号，请提供用户账号的完整电子邮件地址。例如 [email protected]。

    对于 IAM 服务账号，请提供服务账号的地址（不带 .gserviceaccount.com 后缀）。例如，如需指定服务账号 [email protected]，您可以在此处使用值 [email protected]。

  • DATABASE：要连接的数据库名称。

请注意，psql 会截断在命令行中输入的长度超过 100 个字符的密码。如需将 psql 与 OAuth 2.0 令牌搭配使用作为登录密码，您必须设置 PGPASSWORD 环境变量（如本示例所示），而不是在系统提示时手动粘贴。

自动进行身份验证

如需自动对基于 IAM 的 AlloyDB 用户进行身份验证，而无需使用 OAuth 2.0 令牌，您有以下两种选择：AlloyDB Auth Proxy 和 AlloyDB 语言连接器。

您用于运行代理客户端或语言连接器的 IAM 账号必须与您添加为数据库用户的账号相同。例如，如果您使用 IAM 用户账号 [email protected] 运行工作负载，则可以使用代理客户端或语言连接器自动对 [email protected] 数据库用户进行身份验证，而无需指定 OAuth 2.0 令牌。在此示例中，自动身份验证不适用于 [email protected] 以外的任何其他数据库用户。

身份验证代理

使用 Auth Proxy 需要运行 AlloyDB Auth Proxy 客户端并启用 --auto-iam-authn 标志。

如需详细了解如何运行 Auth Proxy，请参阅使用 AlloyDB Auth Proxy 连接。

语言连接器

使用语言连接器需要以编程方式启用 IAM 身份验证。配置 AlloyDB 语言连接器中提供了每种语言对应的选项。

排查 IAM 身份验证问题

如需确定基于 IAM 的身份验证尝试失败的原因，请按照以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Logs Explorer 页面：

    前往 Logs Explorer

  2. 在资源类型下，点击 AlloyDB 实例。

  3. 在严重程度下，点击提醒。

    如果提醒不是一个选项，则表示所选时段内没有记录任何身份验证失败事件。您可能需要使用 Logs Explorer 控件调整时段。

  4. 在查询结果下，检查日志条目中是否包含以下消息之一：

    Request had invalid authentication credentials.
    访问令牌无效。
    Caller does not have required permission to use project.
    IAM 主账号没有必要的 IAM 角色或权限。完整的错误消息会指明缺少的角色或权限。
    IAM principal does not match database user.

    访问令牌指定的经身份验证的 IAM 主账号与您要连接的数据库用户不匹配。

    如需查看令牌指定的主账号，请运行以下命令：

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

    将 ACCESS_TOKEN 替换为 OAuth 2.0 访问令牌。

    Request had insufficient scopes.
    访问令牌不包含 alloydb.login 范围或 cloud-platform 范围。必须至少包含其中一个范围。

后续步骤