为员工身份联合配置延长会话时长

默认情况下,员工身份联合会话的时长上限为 12 小时。借助延长的会话时长,您可以为以下各项配置最长 90 天的会话:

  • Google Cloud 项目拥有的 OAuth 应用:使用项目范围 (restricted_project) 进行配置。员工用户可以与指定项目拥有的 OAuth 应用保持不间断的连接,而无需每天向外部身份提供方 (IdP) 重新进行身份验证。

  • 支持的应用 Google Cloud :使用应用范围 (restricted_client_application) 进行配置。员工用户可以与支持的应用(例如 Gemini Enterprise 移动和桌面应用)保持不间断的连接,而无需每天向外部 IdP 重新进行身份验证。

为了在延长会话期间始终确保安全, Google Cloud 会定期在后台直接从外部身份提供方 (IdP) 同步用户属性和群组成员资格。

本文档介绍了如何使用 Access Context Manager API 定义具有项目级和应用级控制功能的扩展会话政策,如何配置员工池提供方,以及如何管理有效绑定。


延长会话时长的运作方式

员工身份联合使用 Access Context Manager Google Cloud 访问权限绑定来配置延长会话时长:

  • Google Cloud 访问权限绑定:管理员使用 Access Context Manager 定义会话时长政策,该政策在整个组织范围内适用于组织中的所有员工池。政策通过以下任一方式授予最长 90 天的延长会话:

    • 项目范围 (restricted_project):将延长会话应用于指定 Google Cloud 项目拥有的 OAuth 应用。

    • 应用范围 (restricted_client_application):将延长会话应用于受支持的 Google Cloud 应用。

  • 后台属性同步:

    • OIDC:支持使用具有 offline_access 范围的 OIDC 授权代码流程(使用刷新令牌在后台定期从外部 IdP 刷新用户属性和群组成员资格),或通过 SCIM 预配。

    • SAML:对于 SAML 提供商,用户属性和群组成员资格会通过 SCIM 预配保持最新状态。

  • 过时保护:如果无法在 24 小时内从外部 IdP 刷新用户属性(例如,如果用户在 IdP 处被取消配置或凭据被撤消), Google Cloud 会终止会话。

  • 撤消会话:如需在用户的延长会话到期之前立即将其退出,请撤消用户的会话。


准备工作

在配置延长会话时长之前,请确保您拥有所需的 Identity and Access Management 权限并已启用相关 API:

所需的角色和权限

如需获得配置延长会话时长所需的权限,请让管理员向您授予以下 IAM 角色:

启用 API

在项目中启用 Access Context Manager API 和 IAM API:

gcloud services enable \
    accesscontextmanager.googleapis.com \
    iam.googleapis.com

支持的应用

应用范围 (restricted_client_application) 仅支持以下 Google Cloud 应用。如需将政策范围限定为某个应用,请将 name 字段设置为确切的应用名称(区分大小写):

应用 应用名称
Gemini Enterprise 移动应用 (Android) Gemini Enterprise mobile Android
Gemini Enterprise 移动应用 (iOS) Gemini Enterprise mobile IOS
Gemini Enterprise 桌面应用 Gemini Enterprise Desktop

不支持通过 OAuth 客户端 ID (clientId) 标识应用。


限制和要求

在配置延长会话时长之前,请查看以下要求和限制:

  • 支持的范围:必须使用以下任一客户端范围在 scopedAccessSettings 中配置会话设置:
    • restricted_project 范围:适用于 Google Cloud 项目拥有的 OAuth 应用。通过项目编号 (projects/{PROJECT_NUMBER}) 指定项目。
    • restricted_client_application 范围:适用于受支持的 Google Cloud 应用。通过应用名称(name 字段)指定应用。
    • 您必须使用支持的应用中列出的某个确切应用名称。
    • 员工身份联合绑定不支持按 OAuth 客户端 ID (clientId) 限定范围,并且会被拒绝。您必须使用 name 字段标识应用。
  • 会话时长范围:会话时长必须介于 1 小时 (3600s) 到 90 天 (7776000s) 之间。
  • 会话设置参数要求:
    • session_length_enabled:必须设置为 true。
    • session_length:必需,时长介于 1 小时 (3600s) 到 90 天 (7776000s) 之间。
    • session_reauth_method:必须取消设置或设置为 LOGIN。
    • use_oidc_max_age:必须取消设置或设置为 false。
    • max_inactivity:必须取消设置(或默认设置为 0s)。restricted_project 绑定和 restricted_client_application 绑定不支持空闲会话超时。
  • 支持的身份提供方:
    • 采用授权代码流程的 OIDC:需要 offline_access 范围,以便您的 IdP 签发刷新令牌,或需要为用户和群组进行 SCIM 预配,并在员工身份池提供方上设置 --scim-usage=enabled-for-users-groups。
    • 采用隐式流的 OIDC 和 SAML 2.0:需要为用户和群组进行 SCIM 预配,并在员工身份池提供方上设置 --scim-usage=enabled-for-users-groups。--scim-usage=enabled-for-groups 不支持延长会话时长。
  • 属性过时阈值:强制执行固定的 24 小时过时阈值。如果 Google Cloud 无法在 24 小时内从您的 IdP 刷新用户属性,则会话将失效,用户必须重新进行身份验证。
  • Access Context Manager 限制条件:
    • 单一组织绑定:员工池的延长会话时长绑定必须以组织的“所有员工池”主账号 (principalSet://cloudresourcemanager.googleapis.com/organizations/{ORG_ID}/type/WorkforcePool) 为目标。由于此联合主账号标识符适用于组织范围内的所有员工池,因此每个组织只能存在一个此类绑定。如需为多个项目、应用或两者的组合配置延长会话,请在绑定的单个 scopedAccessSettings 列表中添加多个 restricted_project 和 restricted_client_application 范围块。
    • 员工池绑定不支持访问权限级别(access_levels、dry_run_access_levels)。
    • 员工池绑定不支持直接在 GcpUserAccessBinding 上使用顶级 sessionSettings;必须在 scopedAccessSettings.activeSettings.sessionSettings 中定义设置。

配置员工池提供方

如需允许延长会话时长,必须将员工池提供方配置为支持后台属性刷新。您可以将提供方配置为使用 OIDC 或 SAML 协议。

配置 OIDC 提供方

如果您的 OIDC 提供方使用隐式流 (--web-sso-response-type=id-token),则无法使用基于令牌的属性刷新。请改为配置 SCIM,或将提供方切换到授权代码流程。

OIDC 提供商的后台属性刷新可以使用刷新令牌(offline_access 范围)或 SCIM 预配进行处理。如果使用基于令牌的属性刷新:

  1. 在外部 IdP 中,配置一个使用授权代码流程的 OIDC 应用,并启用离线访问,以便返回刷新令牌。
  2. 在 Google Cloud中,将 offline_access 添加到 OIDC 员工池提供方的其他范围。

必须在 Google Cloud 组织中的所有员工身份池上配置离线访问权限,延长会话时长政策才能达到预期效果。

gcloud

如果您的提供商已有其他范围,请将这些范围与 offline_access 一起添加,以免被覆盖:

gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_NAME \
    --location=global \
    --web-sso-additional-scopes="offline_access[,EXISTING_ADDITIONAL_SCOPES]"

替换以下内容:

  • PROVIDER_ID:员工身份池提供方的名称。
  • WORKFORCE_POOL_NAME:员工身份池的名称。
  • EXISTING_ADDITIONAL_SCOPES:之前在提供商上配置的任何以逗号分隔的其他范围。如果您没有现有的其他范围,请省略此参数。

REST API

发送 PATCH 请求以更新提供方。在 offline_access 旁边添加任何现有的其他范围:

PATCH https://iam.googleapis.com/v1/locations/global/workforcePools/WORKFORCE_POOL_NAME/providers/PROVIDER_ID?updateMask=oidc.webSsoConfig.additionalScopes

请求正文:

{
  "oidc": {
    "webSsoConfig": {
      "additionalScopes": [
        "offline_access"
      ]
    }
  }
}

替换以下内容:

  • WORKFORCE_POOL_NAME:员工身份池的名称。
  • PROVIDER_ID:员工身份池提供方的 ID。

为 SAML 和 OIDC 隐式流提供方配置 SCIM

对于 SAML 提供方以及使用隐式流的 OIDC 提供方,后台属性刷新需要 SCIM 预配:

  1. 为员工池提供方设置 SCIM 租户。
  2. 配置从身份提供方到 SCIM 端点的用户和群组预配。
  3. 在所有用户和群组都同步到 Google Cloud后,在员工身份池提供方上设置 --scim-usage=enabled-for-users-groups。--scim-usage=enabled-for-groups 不支持延长会话时长。

如需查看分步说明,请参阅员工身份联合的 SCIM 预配以及 Microsoft Entra ID 或 Okta 的“为用户和群组启用 SCIM”。


Google Cloud 项目的政策配置示例

创建一个 GcpUserAccessBinding 资源,用于将延长会话时长政策分配给组织的员工池,并将该政策的作用域限定为 Google Cloud 项目拥有的 OAuth 应用。

gcloud

在名为 esl-binding.yaml 的 YAML 文件中定义政策:

scopedAccessSettings:
- scope:
    clientScope:
      restrictedProject:
        name: projects/PROJECT_NUMBER
  activeSettings:
    sessionSettings:
      sessionLength: 7776000s
      sessionLengthEnabled: true
      sessionReauthMethod: LOGIN

创建访问权限绑定:

gcloud access-context-manager cloud-bindings create \
    --organization=ORG_ID \
    --federated-principal="principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool" \
    --binding-file="esl-binding.yaml"

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。
  • PROJECT_NUMBER:要应用延长会话时长的 Google Cloud 项目编号(例如 987654321098)。此项目拥有的所有 OAuth 应用都会获得延长的会话时长。
  • sessionLength:会话时长(以秒为单位),后跟 s。例如,7776000s 指定 90 天的会话。
  • sessionLengthEnabled:设置为 true。
  • sessionReauthMethod:设置为 LOGIN(或不设置)。

REST API

向 Access Context Manager API 发送 POST 请求:

POST https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings

JSON 请求正文:

{
  "principal": {
    "federatedPrincipal": "principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool"
  },
  "scopedAccessSettings": [
    {
      "scope": {
        "clientScope": {
          "restrictedProject": {
            "name": "projects/PROJECT_NUMBER"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
          "sessionLength": "7776000s",
          "sessionLengthEnabled": true,
          "sessionReauthMethod": "LOGIN"
        }
      }
    }
  ]
}

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。
  • PROJECT_NUMBER:要应用延长会话时长的 Google Cloud 项目编号(例如 987654321098)。此项目拥有的所有 OAuth 应用都会获得延长的会话时长。
  • sessionLength:会话时长(以秒为单位),后跟 s。例如,7776000s 指定 90 天的会话。
  • sessionLengthEnabled:设置为 true。
  • sessionReauthMethod:设置为 LOGIN(或不设置)。

Google Cloud 应用的政策配置示例

创建一个 GcpUserAccessBinding 资源,将延长会话时长政策分配给组织的员工池,并使用 restricted_client_application 范围将该政策限定于受支持的 Google Cloud 应用。此示例使用的是 Gemini Enterprise 移动应用的名称。如需查看受支持应用的完整列表,请参阅受支持的应用。

gcloud

在名为 esl-app-binding.yaml 的 YAML 文件中定义政策:

scopedAccessSettings:
- scope:
    clientScope:
      restrictedClientApplication:
        name: "Gemini Enterprise mobile Android"
  activeSettings:
    sessionSettings:
      sessionLength: 7776000s
      sessionLengthEnabled: true
      sessionReauthMethod: LOGIN
- scope:
    clientScope:
      restrictedClientApplication:
        name: "Gemini Enterprise mobile IOS"
  activeSettings:
    sessionSettings:
      sessionLength: 7776000s
      sessionLengthEnabled: true
      sessionReauthMethod: LOGIN

创建访问权限绑定:

gcloud access-context-manager cloud-bindings create \
    --organization=ORG_ID \
    --federated-principal="principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool" \
    --binding-file="esl-app-binding.yaml"

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。
  • name:受支持的应用的确切名称。不支持通过 OAuth 客户端 ID (clientId) 标识应用。
  • sessionLength:会话时长(以秒为单位),后跟 s(介于 3600s 和 7776000s 之间)。
  • sessionLengthEnabled:设置为 true。
  • sessionReauthMethod:设置为 LOGIN(或不设置)。

REST API

向 Access Context Manager API 发送 POST 请求:

POST https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings

JSON 请求正文:

{
  "principal": {
    "federatedPrincipal": "principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool"
  },
  "scopedAccessSettings": [
    {
      "scope": {
        "clientScope": {
          "restrictedClientApplication": {
            "name": "Gemini Enterprise mobile Android"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
          "sessionLength": "7776000s",
          "sessionLengthEnabled": true,
          "sessionReauthMethod": "LOGIN"
        }
      }
    },
    {
      "scope": {
        "clientScope": {
          "restrictedClientApplication": {
            "name": "Gemini Enterprise mobile IOS"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
          "sessionLength": "7776000s",
          "sessionLengthEnabled": true,
          "sessionReauthMethod": "LOGIN"
        }
      }
    }
  ]
}

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。
  • name:受支持的应用的确切名称。不支持通过 OAuth 客户端 ID (clientId) 标识应用。
  • sessionLength:会话时长(以秒为单位),后跟 s。例如,7776000s 指定 90 天的会话。
  • sessionLengthEnabled:设置为 true。
  • sessionReauthMethod:设置为 LOGIN(或不设置)。

查看和列出绑定

由于绑定适用于组织中的所有员工池,因此每个组织最多有一个访问权限绑定。

列出有效绑定

如需列出组织中的员工池访问权限绑定,请使用 principal:federatedPrincipal 过滤条件:

gcloud

gcloud access-context-manager cloud-bindings list \
    --organization=ORG_ID \
    --filter="principal:federatedPrincipal"

REST API

GET https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings?filter=principal:federated_principal

获取绑定详情

如需查看特定员工池访问权限绑定的详细信息,请执行以下操作:

gcloud

gcloud access-context-manager cloud-bindings describe \
    --binding=BINDING_NAME

将 BINDING_NAME 替换为绑定的完整资源名称(例如 organizations/123456789012/gcpUserAccessBindings/b1234567890)。

REST API

GET https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。
  • BINDING_ID:访问权限绑定的 ID(例如 b1234567890)。

更新访问权限绑定

您可以更新现有员工池访问权限绑定,以修改会话时长、添加新的项目或应用范围,或移除现有范围。

gcloud

  1. 在名为 updated-esl-binding.yaml 的 YAML 文件中定义更新后的政策:

    scopedAccessSettings:
    - scope:
        clientScope:
          restrictedProject:
            name: projects/PROJECT_NUMBER
      activeSettings:
        sessionSettings:
          sessionLength: 2592000s
          sessionLengthEnabled: true
          sessionReauthMethod: LOGIN
    
  2. 应用更新后的政策:

    • 替换限定范围的访问权限设置:如需使用 updated-esl-binding.yaml 中定义的配置覆盖现有范围,请执行以下操作:
    gcloud access-context-manager cloud-bindings update \
        --binding=BINDING_NAME \
        --binding-file="updated-esl-binding.yaml"
    
    • 附加到现有设置:如需将 updated-esl-binding.yaml 中定义的范围附加到绑定的现有范围而不覆盖它们,请传递 --append 标志:
    gcloud access-context-manager cloud-bindings update \
        --binding=BINDING_NAME \
        --binding-file="updated-esl-binding.yaml" \
        --append
    

替换以下内容: * BINDING_NAME:绑定的完整资源名称(例如 organizations/123456789012/gcpUserAccessBindings/b1234567890)。 * PROJECT_NUMBER:要应用延长会话时长的 Google Cloud 项目编号。此项目拥有的所有 OAuth 应用都会获得延长的会话时长。 sessionLength:更新后的会话时长(例如,2592000s 表示 30 天)。

REST API

发送 PATCH 请求以更新绑定。

  • 替换范围访问权限设置:如需覆盖现有范围,请执行以下操作:
PATCH https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID?updateMask=scopedAccessSettings
  • 附加到现有设置:如需附加新范围而不覆盖现有范围,请设置 append=true 查询参数:
PATCH https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID?updateMask=scopedAccessSettings&append=true

JSON 请求正文:

{
"scopedAccessSettings": [
  {
    "scope": {
      "clientScope": {
        "restrictedProject": {
          "name": "projects/PROJECT_NUMBER"
        }
      }
    },
    "activeSettings": {
      "sessionSettings": {
        "sessionLength": "2592000s",
        "sessionLengthEnabled": true,
        "sessionReauthMethod": "LOGIN"
      }
    }
  }
]
}

替换以下内容: * ORG_ID:您的 Google Cloud 组织 ID(例如 123456789012)。 * BINDING_ID:您的访问权限绑定的 ID(例如 b1234567890)。 * PROJECT_NUMBER:要应用延长会话时长的 Google Cloud 项目编号。此项目拥有的所有 OAuth 应用都会获得延长的会话时长。 sessionLength:更新后的会话时长(例如,2592000s 表示 30 天)。


删除访问权限绑定

如果您删除员工池访问权限绑定,系统会为贵组织中的所有员工池停用延长会话时长。

gcloud

gcloud access-context-manager cloud-bindings delete \
    --binding=BINDING_NAME

将 BINDING_NAME 替换为绑定的完整资源名称。

REST API

发送 DELETE 请求以移除绑定:

DELETE https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID

替换以下内容:

  • ORG_ID:您的 Google Cloud 组织 ID。
  • BINDING_ID:要删除的访问权限绑定的 ID。

后续步骤