默认情况下,员工身份联合会话的时长上限为 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 角色:
- 配置员工身份池提供方:员工池或组织上的 Workforce Pool Admin (
roles/iam.workforcePoolAdmin)。 - 管理 Access Context Manager 云访问权限绑定:组织级层的 Cloud Access Binding Admin (
roles/accesscontextmanager.gcpAccessAdmin)。此角色提供创建、查看、更新和删除 Access Context Manager 访问权限绑定所需的权限。
启用 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绑定不支持空闲会话超时。
- 支持的身份提供方:
- 属性过时阈值:强制执行固定的 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 预配进行处理。如果使用基于令牌的属性刷新:
- 在外部 IdP 中,配置一个使用授权代码流程的 OIDC 应用,并启用离线访问,以便返回刷新令牌。
- 在 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 预配:
- 为员工池提供方设置 SCIM 租户。
- 配置从身份提供方到 SCIM 端点的用户和群组预配。
- 在所有用户和群组都同步到 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
在名为
updated-esl-binding.yaml的 YAML 文件中定义更新后的政策:scopedAccessSettings: - scope: clientScope: restrictedProject: name: projects/PROJECT_NUMBER activeSettings: sessionSettings: sessionLength: 2592000s sessionLengthEnabled: true sessionReauthMethod: LOGIN应用更新后的政策:
- 替换限定范围的访问权限设置:如需使用
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。