OIDC¶
本文介绍如何在观测云工作空间配置基于 OIDC/OAuth 2.0 协议的单点登录（SSO）。
观测云支持两种 OIDC 配置方式：
标准 OIDC 配置：适用于符合 OpenID Connect 标准的身份提供商
非标准 OIDC 配置：适用于基于 OAuth 2.0 但接口规范有差异的身份提供商
前置准备¶
在开始配置前，请确保您已准备好：
| 准备项 | 说明 |
|---|---|
| IdP 管理员权限 | 需要在企业身份提供商（如 Keycloak、Authing、Auth0、自建 OIDC 服务等）中创建应用 |
| 客户端凭证 | 从 IdP 获取的 Client ID 和 Client Secret |
| 服务发现地址 | IdP 的 Issuer URL，如 https://****.example.com |
| 企业邮箱域名 | 用于识别 SSO 用户的邮箱后缀，如 example.com |
标准 OIDC 配置¶
第一步：进入配置页面¶
- 进入管理 > 成员管理 > SSO 管理 > 用户 SSO；
- 选择 OIDC 访问类型；
- 点击添加身份提供商。
第二步：连接配置¶
- 身份提供商名称：提供身份管理服务的平台名称（❗️该名称将作为 IdP 别名并呈现在单点登录 IdP 选择界面中，为确保您可快速定位所需登录的 IdP，需填写合适的名称）；
- 备注：用户可自定义添加的描述信息，用于记录身份提供商的相关说明；
- 身份提供商 URL：身份提供商的完整 URL，也是服务发现地址。例如：https://guance.example.com；
- 客户端 ID：由认证服务提供的唯一标识符，用于识别客户端应用程序；
- 客户端密钥：与客户端 ID 联合使用，用于对客户端应用程序进行身份验证；
- 授权请求 Scope：授权请求的范围。默认包含
openid、profile和email，可根据需要额外添加address和phone声明。
第三步：映射配置¶
实现 SSO 登录需将身份提供商（IdP）的账号信息与观测云账号信息进行字段映射。主要字段如下：
- 用户名：必填；身份提供商的 “用户名” 字段，例如
referred_username； - 邮件：必填；身份提供商的 “邮箱” 字段，例如
email； - 手机号：非必填；身份提供商的 “手机号” 字段，例如
phone。
第四步：登录控制¶
- 访问限制：校验登录邮箱的域名后缀是否与配置的域名匹配。匹配的邮箱才有权限访问 SSO 登录链接。用户首次登录时可动态创建观测云成员账号，无需提前在工作空间内创建；
- 角色授权：为首次登录的 SSO 账号分配角色，非首次登录的账号不受影响；
- 若工作空间内启用 SAML 映射，则优先按映射规则分配角色。
- 会话保持：设置 SSO 登录会话的无操作保持时间和最大保持时间。
会话保持配置¶
| 配置项 | 范围 | 默认值 | 说明 |
|---|---|---|---|
| 无操作登录会话保持 | 180～1440 分钟 | 180 分钟 | 用户无操作后自动退出的时间 |
| 登录会话最大保持 | 0～7 天 | 7 天 | 无论是否有操作，达到此时长后强制退出。0 表示永不超时 |
修改会话保持时间后，已登录成员保持原有设置，新登录成员按最新设置生效。
角色授权与角色映射的关系¶
用户侧配置 OIDC 相关注意事项¶
-
授权模式：仅支持
authorization_code授权模式；其返回类型必须是code； -
id_token签名算法：目前只支持HS256； -
code换取token身份验证方式：-
默认支持：
client_secret_basic -
自定义方式支持:
client_secret_post、client_secret_basic、none
-
-
scope范围：-
默认范围：
openid、profile、email、phone -
自定义要求：必须包含
openid，其他可自定义，但返回结果中必须包含email，可选返回phone_number。
-
第五步：获取回调 URL¶
身份提供商创建成功后，点击编辑按钮，获取以下 URL 并提供给您的 IdP：
- 回调 URL：IdP 授权成功后跳转回观测云的地址；
- 发起登录 URL：观测云 SSO 登录入口地址。
第六步：在 IdP 中配置回调地址¶
根据第五步获取的回调 URL，在您的 IdP 中完成以下配置：
- 回调地址（Redirect URI）：填入观测云提供的回调 URL；
- 授权模式：确保支持
authorization_code； - 返回类型：确保支持
code。
非 OIDC 标准配置¶
适用于基于 OAuth 2.0 但不符合标准 OIDC 规范的身份提供商，常见于以下场景：
- IdP 未提供标准的 OIDC 发现端点（
.well-known/openid-configuration）； - 获取用户信息的接口路径或返回格式与标准 OIDC 不同；
- 接口参数大小写风格与标准不一致。
配置步骤¶
- 进入管理 > 成员管理 > SSO 管理 > OIDC > 新建身份提供商；
- 点击右上角即可切换进入标准的 OIDC 配置页面；
-
连接配置：
- 身份提供商名称：自定义显示名称（限 64 字符）
- 配置文件上传：下载模板，补充授权端点、Token 端点、用户信息端点、字段映射等信息后上传
- 备注：自定义添加的描述信息，用于记录身份提供商的相关说明
-
登录配置：配置同标准 OIDC（访问限制、角色授权、会话保持）；
- 保存并启用。
登录验证¶
- 邮箱登录进入观测云 SSO 页面：https://auth.guance.com/login/sso；
- 输入创建 SSO 时配置的邮箱地址，选择需要登录的工作空间所属 IDP；
- 认证成功后，跳转至工作空间选择界面；
- 登录该地址；
- 输入用户名、密码等信息；
- 登录成功。
注意事项¶
- 角色映射启用时：若用户未匹配任何角色映射规则，或角色映射被禁用，登录后将提示“无访问权限”；
- 删除身份提供商后：用户通过 SSO 登录时，将无法看到已删除 IdP 对应的工作空间；
- 多 IdP 配置：单个工作空间最多支持 10 个 IdP，用户邮箱域名匹配任一 IdP 即可登录；
- 账号绑定：SSO 首次登录时，若邮箱与现有观测云账号一致，自动绑定并保留历史数据；
- 映射字段错误：若配置的映射字段与 IdP 实际返回字段不匹配，将导致无法获取用户信息，登录失败。
更多阅读¶
您可能对以下内容感兴趣：