认证源-Google Workspace

概述

Google Workspace（原 G Suite）是 Google 面向企业提供的云办公套件，通过 Google Cloud Console 提供基于 OpenID Connect（OIDC）的身份认证服务。专属集成平台支持将 Google Workspace 配置为认证源，用户可使用 Google Workspace 账号一键登录平台。

Google Workspace 认证源底层基于 Google Identity Services 的 OIDC 协议，通过 Google 的 OAuth 2.0 授权服务器完成身份验证和用户信息获取。

核心能力：

统一身份登录：用户使用 Google Workspace 或 Google 账号一键登录

自动用户同步：首次登录时通过 JIT 自动创建平台用户

域名限制：支持限制仅允许指定域名的 Google Workspace 用户登录

属性持续更新：支持每次登录时按规则更新用户属性

适用场景：

企业使用 Google Workspace 作为办公套件和身份主数据源

需要为海外团队或合作伙伴提供 Google 账号登录方式

面向海外用户的 SaaS 应用，需要支持社会化登录

教育机构使用 Google Workspace for Education 管理师生身份

前提条件

序号	条件	说明
1	平台管理员权限	拥有专属集成平台的管理员账号
2	Google Cloud 项目	在 Google Cloud Console 中创建项目并启用 API
3	OAuth 2.0 凭据	在 Google Cloud Console 中创建 OAuth 2.0 客户端 ID
4	Client ID	OAuth 2.0 客户端的 Client ID
5	Client Secret	OAuth 2.0 客户端的 Client Secret
6	域名（可选）	如需限制仅特定 Google Workspace 域名用户登录，需提供域名

注意：创建 Google Cloud 项目和 OAuth 凭据的详细步骤请参考 Google Identity Services 文档。如未完成 OAuth 同意屏幕的验证，Google 会标记应用为"未验证"，仅测试用户可完成授权。

操作步骤

添加 Google Workspace 认证源

添加认证源

登录专属集成平台管理后台。

在左侧导航栏依次点击 用户中心 → 认证源管理。

点击页面右上角的 添加认证源 按钮。

在弹出的选择框中，选择 Google Workspace 或 OIDC 类型。

提示：Google Workspace 认证源预置了 Google OIDC 发现端点（https://accounts.google.com/.well-known/openid-configuration），简化了 OIDC 端点配置。如需支持个人 Gmail 账号登录，同样可以使用此配置。

配置基本信息

在认证源配置表单中填写以下参数：

参数	必填	说明	示例
认证源名称	是	在登录页显示的认证源名称	`Google 登录`
Client ID	是	Google Cloud Console 中 OAuth 2.0 客户端 ID	`123456789012-xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com`
Client Secret	是	Google Cloud Console 中 OAuth 2.0 客户端密钥	`********`
Domain	否	限制仅允许指定域名的 Google Workspace 用户登录	`example.com`
认证源图标	否	上传图标文件，支持 PNG/JPG，建议 64×64px	—

重要：Client ID 和 Client Secret 需在 Google Cloud Console（https://console.cloud.google.com）的 API 和服务 → 凭据 中获取。如未创建凭据，点击 创建凭据 → OAuth 客户端 ID，应用类型选择 Web 应用。

提示：配置 Domain 参数后，仅具有该域名的 Google Workspace 用户可登录。留空则允许所有 Google 账号（包括 Gmail 个人账号）登录。如需更精确的用户范围控制，建议启用 Domain 限制。

配置回调地址

复制专属集成平台自动生成的回调地址（格式：{平台域名}/api/auth/callback/google）。

在 已获授权的重定向 URI 部分，点击 添加 URI。

填入复制的回调地址。

保存 Google Cloud Console 配置。

警告：Google OAuth 2.0 要求重定向 URI 使用 HTTPS 协议，除非使用 http://localhost 进行本地开发。请确保平台域名已配置有效的 SSL 证书。

配置属性映射

将 Google 返回的用户属性（通过 ID Token 的 claims）映射到平台用户模型：

Google 属性	平台字段	映射方式	说明
`sub`	`google_id`	创建且更新	Google 用户唯一标识符，建议设置唯一字段匹配
`email`	`email`	创建且更新	用户邮箱地址
`name`	`display_name`	创建且更新	用户全名
`picture`	`avatar_url`	创建且更新	用户头像 URL
`given_name`	`first_name`	创建且更新	用户名字
`family_name`	`last_name`	创建且更新	用户姓氏
`email_verified`	`email_verified`	创建且更新	邮箱是否已验证

重要：至少需要配置一个唯一字段匹配规则（sub → google_id），这是系统识别已有用户的依据。Google 的 sub 是用户的全局唯一标识符，跨应用不变。不建议使用 email 作为唯一匹配字段，因为 Google 用户可能更改邮箱。

提示：如果启用了 Domain 限制，Google Workspace 仅返回符合域名条件的用户信息。hd（hosted domain）claim 包含用户的 Google Workspace 域名，可用于验证用户归属。

完成配置

确认所有参数填写无误。

点击保存按钮。

系统将验证 Google API 连通性，验证通过后认证源创建成功。

认证源将出现在列表中，状态为 已启用。

验证与测试

测试项	验证方法	预期结果
认证源连通性	在认证源列表中点击测试连接	提示连接成功
登录跳转	打开登录页，点击 Google 认证源图标	正确跳转至 Google 登录页面
用户授权	在 Google 页面选择账号并完成授权	成功跳回平台并完成登录
属性同步	登录后查看用户中心个人信息	用户名、邮箱、头像与 Google 账号一致
JIT 创建	使用 Google 中未预先创建的新用户登录	平台自动创建该用户账号
域名限制	使用非指定域名的 Google 账号登录	登录被拒绝，显示相应提示
拒绝授权	在 Google 授权页面点击取消	平台显示相应提示，不创建用户

常见问题

Q1：Google 授权后提示"此应用未经验证"？

Q2：非 Google Workspace 用户（Gmail 个人账号）能否登录？

Q3：Google 登录后获取不到用户的头像图片？

Q4：能否限制特定组织单位（OU）的用户登录？

概述#

前提条件#

操作步骤#

添加 Google Workspace 认证源#

验证与测试#

常见问题#

概述

前提条件

操作步骤

添加 Google Workspace 认证源

验证与测试

常见问题