自定义 IAP

本文介绍如何自定义 Identity-Aware Proxy (IAP) 设置。借助这些设置,您可以控制以下行为:

  • 与 Google Kubernetes Engine 上的 GKE Enterprise 和 Istio 兼容。
  • CORS 预检请求的处理。
  • 用户的验证方式。
  • 拒绝访问时向用户显示的错误页面。

管理设置

您可以使用 Google Cloud 控制台、IAP API 或 Google Cloud CLI 查看和更新负载均衡器和 App Engine 应用的 IAP 设置。

如需更新所有资源(包括文件夹、项目和组织)的 IAP 设置,请使用 Google Cloud CLI 或 API。

如需在 IAP 中管理设置,请按以下说明操作:

控制台

如需使用 Google Cloud 控制台查看和修改设置,请执行以下操作:

  1. 转到 Identity-Aware Proxy 页面
    转到 Identity-Aware Proxy 页面
  2. 应用标签页中找到您的资源。
  3. 打开更多操作菜单 ,然后点击设置
  4. 点击保存

gcloud

如需使用 Google Cloud CLI 获取和修改设置,请使用 gcloud iap settings getgcloud iap settings set 命令,如下所示:

  • 如需获取项目、文件夹或组织的设置,请使用以下命令。如需使用 Google Cloud 控制台或 gcloud CLI 配置 IAP 设置,请参阅自定义 IAP
gcloud iap settings get --project=PROJECT-ID
gcloud iap settings get --folder=FOLDER-ID
gcloud iap settings get --organization=ORGANIZATION-ID
  • 如需获取某项目下特定 IAP 资源类型的设置,请执行以下操作:
gcloud iap settings get --project=PROJECT-ID \
  --resource-type=RESOURCE-TYPE-NAME
  • 如需设置项目、文件夹或组织的设置,或项目下的 IAP 资源类型,请创建一个包含所需新设置的 JSON 或 YAML 文件,然后指定该文件的路径。如需了解详情,请参见 gcloud iap settings set 主题:
gcloud iap settings set SETTING_FILE --project=PROJECT-ID \
  --resource-type=RESOURCE-TYPE-NAME

API

如需使用 IAP API 获取和修改设置,请使用 GETPATCH HTTP 动词向 Google Cloud 中的所需资源端点发出请求。结合使用 :iapSettings 路径后缀、资源路径(如资源和权限中所述)和适当的 HTTP 方法来获取或修改设置。如需了解详情,请参阅 getIapSettings()updateIapSettings()

  • 如需获取或设置某项目下特定 IAP 资源类型的设置,请执行以下操作:
https://iap.googleapis.com/v1/projects/PROJECT-ID/iap_web/appengine-APP-ID/services/SERVICE-ID/versions/VERSION-ID:iapSettings
  • 如需获取或设置项目设置,请执行以下操作:
https://iap.googleapis.com/v1/projects/PROJECT-ID:iapSettings
  • 如需获取或设置文件夹设置,请执行以下操作:
https://iap.googleapis.com/v1/folders/FOLDER-ID:iapSettings
  • 如需获取或设置组织的设置,请执行以下操作:
https://iap.googleapis.com/v1/organizations/ORGANIZATION-ID:iapSettings

了解针对设置的访问权限控制

需要特定的权限才能查看和修改 IAP 设置。下表列出了读取和修改每种资源类型的设置所需的权限。有关不同资源类型的说明,请参见资源和权限

资源 查看设置的权限 修改设置的权限
组织 iap.organizations.getSettings iap.organizations.updateSettings
文件夹 iap.folders.getSettings iap.folders.updateSettings
项目 iap.projects.getSettings iap.projects.updateSettings
所有 Web 服务 iap.web.getSettings iap.web.updateSettings
Web 服务类型 iap.webTypes.getSettings iap.webTypes.updateSettings
Web 服务 iap.webServices.getSettings iap.webServices.updateSettings
Web 服务版本 iap.webServiceVersions.getSettings iap.webServiceVersions.updateSettings

IAP Settings Admin (roles/iap.settingsAdmin) 角色会授予所有这些权限,这与 Project Editor (roles/editor) 一样。Project Viewer (roles/viewer) 会授予所有 getSettings 权限。

如需详细了解如何授予 IAM 角色,请参阅授予、更改和撤消访问权限

自定义 IAP 设置

IAP 提供以下自定义设置:

字段 说明
access_settings.cors_settings.allow_http_options 控制 HTTP 选项(CORS 预检)
access_settings.oauth_settings.login_hint 简化 G Suite 网域用户的登录
application_settings.access_denied_page_settings.access_denied_page_uri 拒绝访问时显示自定义错误页面
application_settings.csm_settings.rctoken_aud 签发 GKE Enterprise 和 Istio RCToken
access_settings.gcip_settings 使用 Identity Platform 进行身份验证
access_settings.ReauthSettings 设置重新身份验证政策。如需了解详情,请参阅配置重新身份验证

您可以在项目级层或任何较低的 IAP 资源级层应用设置。

您可以为基于 Web 的 IAP 资源配置设置,但不能为通过使用 IAP 实现 TCP 转发访问的资源配置设置。

access_settings.cors_settings.allow_http_options 为例,您可按如下方式配置自定义设置:

YAML

access_settings:
  cors_settings:
    allow_http_options: "false"

JSON

{
  "access_settings": {
    "cors_settings": {
      "allow_http_options": "false"
    }
  }
}

以下部分详细介绍了每项设置。

允许 HTTP OPTIONS 请求(CORS 预检)

字段 默认值
access_settings.cors_settings.allow_http_options false

Web 的同源政策会阻止浏览器在网站之间发送 AJAX 请求。默认情况下,从一个来源提供的页面上的 JavaScript 不能使用 AJAX 将请求发送到以托管在不同来源上 IAP 保护的应用。

某些情况下,浏览器将自动尝试请求,但如果响应的内容不包含 Access-Control-Allow-Origin 标头,则将其丢弃。如需允许这些类型的请求,请在应用的响应中包含此标头。

在其他情况下,浏览器将在发送跨源请求之前发送 CORS 预检请求(一种 HTTP OPTIONS 请求)。如果您的应用未返回适当的预检响应(包含必需的 Access-Control-* 响应标头)进行响应,则浏览器将阻止该请求并提示错误。此外,由于预检请求不会随任何身份验证凭据(例如 IAP 会话 Cookie)发送,因此 IAP 也会以错误响应。

如需允许这些请求,请执行以下操作:

  1. 将代码添加到您的应用,以响应 OPTIONS 请求。

  2. 将设置 access_settings.cors_settings.allow_http_options 更改为 true,以便 IAP 将 OPTIONS 请求传递到您的应用。

使用 Google Workspace 网域进行身份验证

字段 默认值
access_settings.oauth_settings.login_hint ""

如果只有特定 Google Workspace 网域的成员会使用您的应用,则可以配置 IAP 以优化身份验证流程。这样做有几个好处:

  • 如果用户使用多个账号(例如工作账号和个人账号)登录,则系统将自动选择其工作账号,而不显示账号选择界面。

  • 如果未登录其 Google 账号,则登录界面将自动填充其电子邮件地址的网域部分(例如,该用户只需输入 alice,而不需输入 alice@example.com)。

  • 如果您的 Google Workspace 网域配置为使用第三方单点登录提供商,则系统将显示该自定义登录页面,而不是 Google 的登录页面。

如需启用此行为,请将 access_settings.oauth_settings.login_hint 的值设置为您的 Google Workspace 域名(例如 example.com)。域名所有权必须已通过验证:您不能使用自己拥有的任意互联网 DNS 域名。(添加为 Google Workspace 主域名或辅助域名的域名已通过验证,因此可以在此处使用。)

如果您需要对网域外的用户进行身份验证,则可以使用程序化身份验证

如需了解详情,请参阅 OpenID Connect 文档

设置自定义访问遭拒错误页面

字段 默认值
application_settings.access_denied_page_settings.access_denied_page_uri ""

您可以在此字段中设置网址,以便在政策拒绝访问时将用户重定向到自定义页面,而不是默认的 IAP 错误页面。

您还可以使用此功能嵌入问题排查网址。如需了解详情,请参阅为自定义访问遭拒错误页面启用问题排查网址

签发 GKE Enterprise 和 Istio RCToken 网状网 ID

字段 默认值
application_settings.csm_settings.rctoken_aud ""

如果您在 GKE 上使用 Istio,则可以将 IAP 配置为生成与 Istio 兼容的 RCToken。如果将此字段设置为非空字符串,则 IAP 将添加一个包含 RCToken 的 Ingress-Authorization HTTP 标头。aud 声明将设置为该字段的值。

使用 Identity Platform 进行身份验证

字段 默认值
access_settings.gcip_settings null

默认情况下,IAP 使用 Google 的原生身份系统。如果设置了此字段,IAP 将使用 Identity Platform 来验证用户身份。

了解资源层次结构中的设置继承机制

IAP 始终评估对特定 Web 服务版本的请求。这种类型的资源位于资源层次结构的最低级别,如下所示:

- Organization
  - Folder
    - Project
      - All web services
        - Web service type
          - Web service
            - Web service version

为了确定适用于 Web 服务版本的设置,IAP 会从一组默认值开始,然后从上到下遍历层次结构。系统会应用找到的设置,因此在较低级层设置的值会覆盖在较高级别设置的值。例如,如果 access_settings.cors_settings.allow_http_options 在项目级层设为 true,但 false 在服务级层,则有效值将是 false

如需详细了解 IAP 资源层次结构,请参阅资源和权限