使用 IAM 账号连接

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

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

准备工作

您需要先准备好项目、集群、实例和 IAM 用户账号，然后才能使用 IAM 凭据登录 AlloyDB 实例。

如需了解详情，请参阅管理 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 用户账号，请提供用户账号的完整电子邮件地址。例如 kai@altostrat.com。

    对于 IAM 服务账号，请提供服务账号的地址（不带 .gserviceaccount.com 后缀）。例如，若要指定服务账号 my-service@my-project.iam.gserviceaccount.com，您应在此处使用值 my-service@my-project.iam。

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

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

使用 AlloyDB Auth Proxy 或 AlloyDB 语言连接器自动进行身份验证

您可以使用 AlloyDB Auth Proxy 或 AlloyDB 语言连接器自动对基于 IAM 的 AlloyDB 用户进行身份验证，并连接到实例，而无需提供 OAuth 2.0 令牌。

如需使用 AlloyDB Auth Proxy，您需要启用 --auto-iam-authn 标志并运行 AlloyDB Auth Proxy 客户端，而 AlloyDB 语言连接器需要以编程方式启用 IAM 身份验证。

使用语言连接器时，每种语言都有对应的选项。如需了解详情，请参阅配置 AlloyDB 语言连接器。

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

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

如需详细了解如何运行语言连接器，请参阅使用 AlloyDB 语言连接器进行连接。

排查 IAM 身份验证问题

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

  1. 在 Google Cloud 控制台中，前往“日志浏览器”页面：

    转到日志浏览器

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

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

    如果提醒不是选项，则表示在所选时间范围内没有记录身份验证失败。您可能需要使用日志浏览器控件调整窗口。

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

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

    访问令牌指定的经过身份验证的 IAM 正文与您要以哪个数据库用户身份进行连接不符。

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

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

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

    Request had insufficient scopes.
    访问令牌不包含 alloydb.login 范围或 cloud-platform 范围。必须至少具有以下某个权限范围。