对接 Yeastar P 系列云 PBX 和 Red Hat SSO

本文介绍如何对接 Yeastar P 系列云 PBX 和 Red Hat SSO。

注： 本文以 Keycloak 20.0.5 为例，介绍如何实现对接 Yeastar PBX。Red Hat SSO 的配置路径可能有所不同，但所需的设置与示例一致。

使用要求

平台 要求
Red Hat SSO 推荐版本：7.6 或更高版本
Yeastar PBX
  • 固件：84.21.0.16 或更高版本
  • 订阅服务：认证对接

步骤一、在 Red Hat SSO 上创建资源并获取凭证

在 Red Hat SSO 上创建必要的资源并获取相关凭证，用于授权和验证 Yeastar PBX 与 Red Hat SSO 之间的集成。

你需要在 Red Hat SSO 执行以下操作：

  1. 创建域并配置密钥，以集中管理用户身份，并为 SSO 提供签名和加密支持。
  2. 添加需要使用 Red Hat 凭证登录 Linkus 客户端的用户。
  3. 创建 OpenID Connect(OIDC) 客户端，用于将 Red Hat SSO 用户单向同步至 Yeastar PBX。
  4. 获取 Red Hat SSO 提供的元数据，以便后续导入 Yeastar PBX。
1、创建域并配置密钥
  1. 使用管理员账号登录 Red Hat SSO 管理控制台。
  2. 创建域。
    1. 点击左上角的 master，选择 Create Realm。

    2. 在 Realm name 栏，填写一个名称，然后点击 Create。

      系统将自动切换至新创建的域。

  3. 配置域密钥，用于签名和加密。
    1. 在左侧导航栏，点击 Realm settings。
    2. 在 Keys 页签下，点击 Providers。
    3. 点击 Add provider，选择 rsa-generated 类型，以生成密钥和自签名证书。

      注： Yeastar PBX 最多支持 5 个证书。元数据中证书数量超过 5 个时，将无法导入到 Yeastar PBX。
2、添加用户
  1. 在左侧导航栏，点击 Users。
  2. 在 User list 页签下，点击 Create new user。

  3. 填写用户信息。
    重要： 由于用户的邮箱地址是 Red Hat SSO 中识别用户身份的唯一标识，请确保已配置用户邮箱。
    • 如果使用内置的 Email 字段作为 SSO 的唯一标识，在 Email 栏填写用户的邮箱地址。

    • 如果使用自定义的邮箱字段作为 SSO 的唯一标识，添加相应属性并设置属性值。

  4. 点击 Save。
3、创建 OpenID Connect(OIDC) 客户端
  1. 在左侧导航栏，点击 Clients。
  2. 创建 OIDC 客户端。
    1. 在 Clients list 页签下，点击 Create client。

    2. 设置客户端，然后点击 Save。

      配置项 说明
      Client type 选择 OpenID Connect。
      Client ID 填写一个名称，帮助你识别此客户端。
      Client authentication 启用此项。
      Authentication flow 勾选 Service accounts roles，以允许该客户端获取访问令牌。
  3. 查看并记录客户端凭证。
    • Client ID：在 Settings 页签下，复制 client ID。

    • Client Secret：在 Credentials 页签下，复制 client secret。

  4. 为服务账号分配权限。
    1. 在 Service accounts roles 页签下，点击 Assign role。

    2. 在左上角，从下拉列表中选择 Filter by clients。

    3. 搜索并分配以下权限。
      示意图 权限

      • query-groups

      • query-users

      • view-groups

      • view-users

      • manage-realm
    4. 点击 Assign。
4、从 Red Hat SSO 获取元数据
  1. 在左侧导航栏，点击 Realm settings。
  2. 滚动到页面底部，点击 SAML 2.0 Identity Provider Metadata。

  3. 通过以下任一方式获取元数据：
    • 从浏览器地址栏复制元数据 URL
    • 将元数据 XML 文件保存到本地电脑

步骤二、在 Yeastar PBX 上导入 Red Hat SSO 元数据并进行配置

  1. 进入 Red Hat SSO 的配置界面。

    1. 登录 PBX 网页，进入 应用对接 > 协同办公平台集成。
    2. 在 Red Hat SSO 右侧，点击 集成。
  2. 通过元数据 XML 文件或元数据 URL 导入配置。
    通过元数据文件导入
    1. 在 快速导入 Red Hat 配置 栏，选择 从元数据文件导入。
    2. 点击 导入。
    3. 点击 浏览，选择 .xml 文件。
      注： 文件大小不得超过 4MB。
    4. 点击 上传。

      PBX 将自动解析文件内容，并将关键元数据填充到相应字段中。

    通过元数据 URL 导入
    1. 在 快速导入 Red Hat 配置 栏，选择 从元数据URL导入。
    2. 在 URL 栏，填写元数据 URL。
    3. 点击 导入。

      PBX 将自动解析 URL 中的元数据，并将关键元数据填充到相应字段中。

  3. 在 通用 栏，查看并完成以下配置。

    配置项 说明
    身份提供商实体 ID Red Hat SSO 的唯一标识符。该值从导入的元数据中自动解析并填充。
    单点登录 URL Red Hat SSO 服务的地址，PBX 会向该地址发送 SAML 认证请求。该值从导入的元数据中自动解析并填充。
    请求签名方式 选择用于签名 SAML 请求的哈希算法。
    SAML 绑定

    选择 PBX 与 Red Hat SSO 之间 SAML 消息交换所使用的绑定协议。

    目前仅支持 Redirect。当 Red Hat 用户登录 Linkus 客户端时，PBX 会将 SAML 消息进行 Base64 编码和 URL 编码，并作为 URL 参数发送给 Red Hat SSO。
    连接协议 设置 Yeastar PBX 和 Red Hat SSO 用于验证和授权的协议。
    签名 SAML 请求

    设置是否对 SAML 请求进行签名。
    支持加密的 SAML 断言 设置是否加密 SAML 断言。

  4. 在 属性匹配 栏，指定用于识别 Red Hat 用户单点登录身份的属性。

    • 如果使用内置的 Email 字段作为单点登录的唯一标识，选择 SAML_SUBJECT，并确保 Red Hat 用户已配置邮箱地址。

    • 如果使用自定义的邮箱属性作为单点登录的唯一标识，选择 自定义，并确保在 PBX 填写的属性名称与 Red Hat SSO 用户属性名称一致。

  5. 可选： 在 证书管理 栏，按需添加或管理证书。

    注：
    • 通过元数据导入的证书会自动上传并显示在列表中。
    • 如果你手动上传证书，确保证书满足以下要求：
      • 格式：.pem、.crt、.cer 或 .cert
      • 文件大小：不超过 4MB
    • 最多支持 5 个证书。PBX 会按列表顺序尝试使用证书，当前一个不可用时才会切换下一个。
  6. 在 应用注册 栏，选择用户可通过 Red Hat 账户单点登录的地址。

  7. 可选： 在 用户同步 栏，粘贴 OIDC 客户端的 ID 和密钥。

  8. 点击 保存。
  9. 在弹出的窗口中，点击 服务提供商元数据文件 下载文件，该文件将在后续配置 Red Hat SAML 客户端时使用。

步骤三、在 Red Hat SSO 配置 SAML 客户端

  1. 在左侧导航栏，点击 Clients。
  2. 在 Clients list 页签下，点击 Import client。

  3. 在 Resource file 栏，点击 Browse，上传从 PBX 下载的元数据文件。

  4. 点击 Save，完成导入。
  5. 配置 SAML 客户端的用户属性。
    1. 在 Client scopes 页签下，选择对应的客户端范围和映射。

    2. 在 Mappers 页签下，点击默认的邮箱属性或自定义的邮箱属性。

    3. 在 User Attribute 栏，填写用户属性。

    4. 点击 Save。

执行结果

对接状态显示 已连接，表示 PBX 已成功对接 Red Hat SSO。

后续操作