如何共享 OAuth 客户端

本页面介绍了如何与组织内的其他应用共享 OAuth 客户端。

概览

在项目之间共享 OAuth 客户端意味着为多个受 Identity-Aware Proxy (IAP) 保护的应用使用单个自定义 OAuth 客户端，而不是为每个应用创建一个新的 OAuth 客户端。这种方法可以简化管理，尤其适用于拥有众多应用的组织。

配置 IAP 时，您可以使用以下两种 OAuth 客户端类型之一：

  • Google 管理的 OAuth 客户端：默认情况下，IAP 会自动使用此客户端。此内置选项无需手动创建客户端，但有两个主要限制：

    • 仅允许贵组织内的用户（内部用户）访问

    • 在权限请求页面上显示 Google Cloud 品牌信息，而不是贵组织的品牌信息

  • 自定义 OAuth 客户端：由您自行创建和管理。此选项：

    • 可在多个应用之间共享

    • 允许在权限请求页面上自定义品牌信息

    • 支持外部用户（组织外部人员）访问

创建自定义 OAuth 客户端时，您可以灵活地将其用于单个应用，也可以在多个应用之间共享。共享自定义 OAuth 客户端具有以下几项优势：

  • 减少管理多个客户的管理开销

  • 简化了为不应有权访问“凭据”页面的团队成员启用 IAP 的过程

  • 便于以编程方式（非浏览器）访问受 IAP 保护的应用

如需了解如何创建 OAuth 客户端，请参阅为 IAP 创建 OAuth 客户端。如需详细了解 Google 管理的 OAuth 客户端，请参阅自定义 OAuth 配置以启用 IAP。

准备工作

按照创建 OAuth 客户端中的步骤创建新的 OAuth 客户端，或使用现有的 OAuth 客户端。

以编程方式使用

配置 OAuth 客户端以进行程序化访问，从而允许非浏览器应用向受 IAP 保护的资源进行身份验证。这样，脚本、自动化作业和后端服务就可以安全地访问受保护的应用，而无需用户进行交互式登录。

您可以在资源层次结构的任何级别应用这些身份验证设置：组织、文件夹或项目。

如需了解实现步骤，请参阅程序化身份验证指南和 IAP 设置管理文档。

gcloud

  1. 准备一个包含 OAuth 客户端 ID 的设置文件：

    cat << EOF > SETTINGS_FILENAME
  access_settings:
    oauth_settings:
      programmatic_clients: [clientId1, clientId2, ..]
EOF

  2. 使用 gcloud iap settings set 命令应用设置：

    gcloud iap settings set SETTINGS_FILENAME \
  [--organization=ORGANIZATION | --folder=FOLDER | --project=PROJECT] \
  [--resource-type=RESOURCE_TYPE] \
  [--service=SERVICE] \
  [--version=VERSION]

    命令示例：

    # Organization level
gcloud iap settings set SETTINGS_FILENAME --organization=ORGANIZATION

# Folder level
gcloud iap settings set SETTINGS_FILENAME --folder=FOLDER

# Project level (web resources)
gcloud iap settings set SETTINGS_FILENAME \
  --project=PROJECT \
  --resource-type=iap_web

# App Engine service in a project
gcloud iap settings set SETTINGS_FILENAME \
  --project=PROJECT \
  --resource-type=app-engine \
  --service=SERVICE

    其中：

    • SETTINGS_FILENAME：您准备的 YAML 文件。

    • ORGANIZATION：组织 ID

    • FOLDER：文件夹 ID

    • PROJECT：项目 ID

    • RESOURCE_TYPE：IAP 资源类型（app-engine、iap_web、compute、organization 或 folder）

    • SERVICE：服务名称（对于 compute 或 app-engine 资源类型，此项为可选）

    • VERSION：版本名称（不适用于 compute，对于 app-engine 为可选）

API

  1. 准备设置 JSON 文件：

    cat << EOF > iap_settings.json
{
  "access_settings": {
    "oauth_settings": {
      programmatic_clients: [clientId1, clientId2, ..]
    }
  }
}
EOF

  2. 获取资源名称：

    gcloud iap settings get \
  [--organization=ORGANIZATION | --folder=FOLDER | --project=PROJECT] \
  [--resource-type=RESOURCE_TYPE] \
  [--service=SERVICE] \
  [--version=VERSION]

  3. 使用资源名称更新设置：

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @iap_settings.json \
"https://iap.googleapis.com/v1/RESOURCE_NAME:iapSettings?updateMask=iapSettings.accessSettings.oauthSettings.programmaticClients"

    其中：

    • ORGANIZATION：组织 ID

    • FOLDER：文件夹 ID

    • PROJECT：项目 ID

    • RESOURCE_TYPE：IAP 资源类型（app-engine、iap_web、compute、organization 或 folder）

    • SERVICE：服务名称（对于 compute 或 app-engine 资源类型，此项为可选）

    • VERSION：版本名称（不适用于 compute，对于 app-engine 为可选）

配置完成后，使用您配置的任一 OAuth 客户端 ID 登录应用。如需了解详情，请参阅程序化身份验证。

浏览器访问

如需通过Google Cloud 控制台使 IAP 能够使用您的客户端 ID 和密钥，请完成以下说明：

风险

虽然在应用之间共享客户端很方便，但存在风险。本部分简单介绍共享客户端时的潜在风险以及如何缓解风险。

单点故障

为多个应用使用一个 OAuth 客户端会造成单点依赖。如果客户端被错误地删除或修改，则使用该客户端的每个应用都会受到影响。已删除的 OAuth 客户端可在 30 天内恢复。

为了有效管理此运营风险，请执行以下操作：

这主要是运营风险，而不是安全风险。通过适当的访问权限控制和监控，共享 OAuth 客户端的便利性和管理优势通常会超过此考虑因素。

客户端密钥泄露

共享客户端需要与他人和脚本共享您的客户端密钥， 这会增加您的客户端密钥泄露的风险。IAP 无法区分从您的应用创建的令牌和从泄露的客户端密钥创建的令牌。

为了降低这种风险，请执行以下操作：

  • 像保护密码一样保护客户端密钥，切勿以纯文本形式存储

  • 使用 Secret Manager 实现安全的凭证管理

  • 使用 Cloud Audit Logging 监控对 IAP 资源的访问

  • 泄露的客户端密钥只会影响身份验证，而不会影响资源访问授权。如果您怀疑自己的密钥已泄露，请立即重置。

如需以编程方式访问受 IAP 保护的资源，请考虑使用服务账号 JWT 身份验证，而不是与个别用户共享 OAuth 客户端密钥。此方法可提供更好的安全隔离，同时为您的应用保留共享 OAuth 客户端的优势。

权限范围注意事项

共享 OAuth 客户端时，所有应用都会使用相同的权限范围。对于 IAP，openid 和 email 是唯一必需的范围。此注意事项本身并不是重大风险，但请务必了解：

  • OAuth 仅用于 IAP 中的身份验证（验证身份）；授权（资源访问权限）通过 IAM 政策单独处理

  • 即使身份验证凭证遭到泄露，攻击者仍需要适当的 IAM 权限才能访问受保护的资源

  • 将客户端限制为仅使用所需的 openid 和 email 范围有助于限制潜在的安全影响