NPS 验证代理概述


本文描述如何配置共享的 NPS 以使用 NPS 验证代理,以便还可用其将呼叫通知推送到 Webex 应用程序。 如果 NPS 不支持其他应用程序,可以遵照《Webex for BroadWorks 解决方案指南》(https://help.webex.com/z9gt5j) 中的简易程序操作。

NPS 代理概述

为了与 Webex for BroadWorks 兼容,必须对 NPS 打补丁以支持 NPS 代理功能,即 UCaaS 中用于网络语音的推送服务器

此功能在通知推送服务器中采用了一项新的设计,以解决与移动客户端的服务商共享推送通知证书私钥的安全漏洞。 NPS 不再与服务商共享推送通知证书和密钥,而是使用新 API 从 UCaaS 后端获取短时有效的推送通知令牌,并使用此令牌向 Apple APNs 和 Google FCM 服务验证。

此功能还增强了通知推送服务器通过新的 Google Firebase Cloud Messaging (FCM) HTTPv1 API 将通知推送到 Android 设备的能力。

Xchange 上提供了针对此功能的 BroadWorks 补丁: https://xchange.broadsoft.com/node/1046235

有关更多信息,请参阅 Xchange 上 UCaaS 中用于网络语音的推送服务器功能描述https://xchange.broadsoft.com/node/1045458

托管 NPS 的 XSP(或应用程序交付平台 ADP)必须满足以下要求:

最低版本和并存限制

  • NPS 必须在专用 XSP/ADP 上激活,且必须是服务器上唯一的托管应用程序。 这是为了消除对推送通知传送的干扰。

  • 部署中应该只有一个 NPS 应用程序。 如果您使用的是移动 UC-One Collaborate/Connect 和/或 UC-One SaaS,并且实施了 Webex for BroadWorks,则必须对所有应用程序共享这个单一的 NPS。

  • NPS 必须在 R22 或更高版本的 XSP 或 ADP 上。

    如果 XSP 运行 NPS 且 AS 为 R21.SP1,则 R22/R23 XSP 与 R21 堆栈兼容。 请参阅 BroadWorks 兼容性矩阵了解更多信息。

  • 有关 ADP 服务器的更多信息,请访问 https://xchange.broadsoft.com/node/1051580

共享的 NPS

在配置共享的 NPS 以使用 NPS 代理之前,请参阅以下说明:

  • 如果您的 NPS 与其他应用程序(不仅仅是 Webex 应用程序)一起使用: 配置 NPS 代理之前,请勿将 NPS 从使用 FCM 旧式 API 更改为使用 FCM HTTP v1 API。

    您可以在配置 NPS 使用 NPS 代理时变更。

  • 使用 NPS 代理验证通知对于旧版应用程序的运行是否正常时,可以删除 Android 应用程序的 FCM API 密钥以及 iOS 应用程序的 APNs 验证密钥。

APNs HTTP/2

  • 如果您部署的任何 iOS 应用程序并非来自 Cisco/BroadSoft,请在配置 NPS 使用 NPS 代理之前,先配置这些应用程序使用 HTTP/2 APNS 协议。

  • 需要将已经支持协作或 SaaS BroadWorks 应用程序的 XSP/ADP 迁移至 HTTP/2。 有关配置 HTTP/2 的详细信息,请参阅 HTTP/2 对 APNS 通知推送服务器的支持(本文概述了 NPS 为支持这些 iOS 应用程序而进行的迁移)。

Android FCMv1

  • 如果您部署的任何 Android 应用程序并非来自 Cisco/BroadSoft,请在配置 NPS 使用 NPS 代理之前,先配置这些应用程序使用 FCMv1 密钥。

  • 如果 XSP/ADP 当前支持 Connect 或 UC-One SaaS 应用程序,则在配置 NPS 代理之前无法启用 FCMv1 密钥。 我们建议您将所有其他应用程序迁移到 FCMv1 密钥,启用、测试,然后禁用,直到准备好完成安装说明为止(本文中介绍了迁移流程)。

图 1. 迁移至 NPS 验证代理的可视化摘要
表 1. 迁移至 NPS 代理的任务摘要

顺序

任务标题

何时/为什么需要执行这项任务?

1

为了 UC-One SaaS(或 Connect)iOS 应用程序将 NPS 迁移到 HTTP/2。

如果 NPS 支持这些应用程序,且尚未针对 HTTP/2 对其进行配置。

2

为了 UC-One SaaS(或 Connect)Android 应用程序将 NPS 迁移到 FCMv1。

如果 NPS 支持这些应用程序,且尚未针对 FCMv1 对其进行配置。

3

启用 FCMv1 模式并测试推送通知。

如果 NPS 支持 UC-One Connect 和/或其他(非 Cisco)Android 应用程序。

4

重新启用 FCM 旧模式。

如果 NPS 支持 UC-One SaaS。 如果启用 FCMv1,在配置 NPS 代理之前,将通知推送到 UC-One SaaS 开始失败。

5

安装 NPS 验证代理补丁。

如果 NPS 在 XSP R22 或 XSP R23 上。

6

配置 NPS 以使用 NPS 验证代理:

  • 附加来自 NPS 的技术支持

  • 申请 CI OAuth 帐户

  • 在 NPS 上创建 CI 帐户并配置刷新令牌超时

  • 添加 Android 应用程序标识

  • 添加 iOS 应用程序标识

  • 检查/设置 URL 和连接超时

  • 将应用程序添加到 AS 允许列表

  • (重新)启用 FCMv1

  • 重启 XSP/ADP

  • 测试 iOS 和 Android 应用程序的 PN

始终必须执行。

7

删除 FCM 旧模式密钥。

适用于 FCMv1 上 NPS 成功支持的应用程序。

如果要在 iOS 平台上向 UC-One SaaS 和 Webex 应用程序推送通知,则必须执行此任务。

准备工作

如果 XSP 运行的是 R22,则必须先应用 ap354313,然后才能将 NPS 应用程序配置为对 APNS 使用 HTTP/2。

1

在以下位置设置制作 URL 和连接参数:XSP_CLI/Applications/NotificationPushServer/APNS/Production>

set url https://api.push.apple.com/3/device

set connectionPoolSize 2

set connectionTimeout 3000

set connectionIdleTimeoutInSeconds 600

注: 不要将连接超时设置为低于 1000 的值。

2

将应用程序标识添加到 APNS 应用程序上下文中,确保省略验证密钥 - 将其设置为空。

对于 UC-One SaaS:XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.broadsoft.uc-one

对于 Webex 应用程序: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared

3

通过以下命令检查验证密钥:XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> get

4

如果 com.broadsoft.uc-one 的验证密钥不为空,可以通过以下命令将其清除:XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> clear the-authkey

5

启用 HTTP/2:

XSP_CLI/Applications/NotificationPushServer/APNS/GeneralSettings> set HTTP2Enabled true

6

仅适用于 UC-One SaaS 应用程序: 登录转售商门户并转至配置 > BroadWorks >

7

向下滚动至“通知推送服务器”部分,选择您的发行版(例如发行版 22),然后按照门户中的说明操作。

  • 此任务适用于 XSP 上的 NPS。 如果 NPS 在 ADP 上,请忽略。

  • 您可以遵照此程序为 UC-One Connect 或 UC-One SaaS Android 应用程序迁移到 FCMv1 通知。

  • 如果要使用 NPS 代理向 UC-One 或 Webex Android 应用程序验证推送通知,必须使用 FCMv1。

  • 此任务旨在为 FCMv1 准备 NPS,以便您可以在配置 NPS 验证代理时启用它。 在准备配置 NPS 验证代理之前,请勿启用 FCMv1,否则通知将无法发送至 SaaS 客户端。

1

从 Firebase 控制台获取项目标识:

  1. 登录 console.firebase.google.com。

  2. 选择 UC-One(Connect 或 SaaS)应用程序项目,打开其项目设置。

  3. 打开常规标签页并记录项目标识。

2

从 Firebase 获取服务帐户的私钥:

  1. 导航至项目设置中的“服务帐户”标签页。

  2. 创建新服务帐户并获取其私钥,

  3. 或者打开现有服务帐户并为其生成一个新的私钥。

    注: 服务帐户必须有 firebaseadmin-sdk 权限。

  4. 将密钥下载到安全的位置。

3

将密钥复制到托管 NPS 的 XSP。

4

将项目标识和关联的私钥添加到 FCM 项目上下文:

XSP_CLI/Applications/NotificationPushServer/FCM/Projects> add project-id path/to/keyfile

5

将 UC-One(Connect 或 SaaS)应用程序和关联的项目标识添加到 FCM 应用程序上下文:

XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add applicationId com.broadsoft.connect projectId project-id

6

根据此处所示的属性和建议值检查 FCM 的配置。 如有必要,使用命令的 set 版本来更改值:

Run XSP_CLI/Applications/NotificationPushServer/FCM> get

参数

建议值

authURL

https://www.googleapis.com/oauth2/v4/token

pushURL

https://fcm.googleapis.com/v1/projects/PROJECT-ID/messages:send

scope

https://www.googleapis.com/auth/firebase.messaging

tokenTimeToLiveInSeconds

3600

connectionPoolSize

10

connectionTimeoutInMilliseconds

3000

connectionIdleTimeoutInSeconds

600

  • 此任务适用于 ADP 上的 NPS。 如果 NPS 在 XSP 上,请忽略。

  • 您可以遵照此程序为 UC-One Connect 或 UC-One SaaS Android 应用程序迁移到 FCMv1 通知。

  • 如果要使用 NPS 代理向 UC-One 或 Webex Android 应用程序验证推送通知,必须使用 FCMv1。

  • 此任务旨在为 FCMv1 准备 NPS,以便您可以在配置 NPS 验证代理时启用它。 在准备配置 NPS 验证代理之前,请勿启用 FCMv1,否则通知将无法发送至 SaaS 客户端。

1

从 Firebase 控制台获取项目标识:

  1. 登录 console.firebase.google.com。

  2. 选择 UC-One(Connect 或 SaaS)应用程序项目,打开其项目设置。

  3. 打开常规标签页并记录项目标识。

2

从 Firebase 获取服务帐户的私钥:

  1. 导航至项目设置中的“服务帐户”标签页。

  2. 创建新服务帐户并获取其私钥,

  3. 或者打开现有服务帐户并为其生成一个新的私钥。

    注: 服务帐户必须有 firebaseadmin-sdk 权限。

  4. 将密钥(.json 文件)下载到安全的位置。

3

将 .json 文件导入 ADP 服务器 /bw/install

4

登录到 ADP CLI,并将项目和 API 密钥添加到 FCM 项目上下文中:

ADP_CLI/Applications/NotificationPushServer/FCM/Projects> add connect-ucaas /bw/install/filename.json

5

将应用程序和项目标识添加到 FCM 应用程序上下文中:

ADP_CLI/Applications/NotificationPushServer/FCM/Applications> add applicationId com.broadsoft.ucaas.connect projectId project-id

6

验证您的配置:


  ADP_CLI/Applications/NotificationPushServer/FCM/Projects> get
Project ID Accountkey
========================
connect-ucaas ********

  ADP_CLI/Applications/NotificationPushServer/FCM/Applications> get
Application ID Project ID
===================================
com.broadsoft.ucaas.connect connect-ucaas

您只需要在以下情况下执行此操作(作为迁移的一部分):

  • 您的 NPS 可用于 UC-One SaaS 或 BroadWorks Connect Android 应用程序。

  • 您已经测试过,向其他应用程序发送呼叫推送通知的功能适用于 FCMv1 API。

您暂时禁用了 FCMv1,因为这些应用程序的 FCMv1 密钥只能在 NPS 验证代理配置过程中启用。

1

登录到托管您的共享 NPS 的 XSP。

2

导航至 FCM 上下文并禁用 FCM v1: XSP_CLI/Applications/NotificationPushServer/FCM> set V1enabled false,以恢复为使用 FCM 旧式 API 密钥。

请安装以下补丁以支持 NPS 验证代理功能:

R22 补丁

R23 补丁

1

通过您的入职联系人或 TAC 创建服务请求以预配置 (Webex Common Identity) OAuth 客户端帐户。 将服务请求的标题命名为“用于验证代理设置的 NPS 配置”(NPS Configuration for Auth Proxy Setup)。

Cisco 会为您提供 OAuth 客户端标识、客户端密码和有效期为 60 天的刷新令牌。 如果令牌在与 NPS 一起使用之前已过期,您可以重新提出请求。
2

在 NPS 上创建客户端帐户:

XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> set clientId client-Id-From-Step1


  XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> set clientSecret
New Password: client-Secret-From-Step1

  XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> set RefreshToken
New Password: Refresh-Token-From-Step1

要验证您输入的值与所提供的值是否匹配,请运行 XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> get

3

输入 NPS 代理 URL,并设置令牌刷新间隔(建议 30 分钟):

XSP_CLI/Applications/NotificationPushServer/CloudNPSService> set url https://nps.uc-one.broadsoft.com/nps/

XSP_CLI/Applications/NotificationPushServer/CloudNPSService> set VOIPTokenRefreshInterval 1800

4

(对于 Android 通知)将 Android 应用程序标识添加到 NPS 上的 FCM 应用程序上下文中。

对于 Android 上的 Webex 应用程序: XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add applicationId com.cisco.wx2.android

对于 Android 上的 UC-One 应用程序: XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add applicationId com.broadsoft.connect

5

(对于 Apple iOS 通知)将应用程序标识添加到 APNS 应用程序上下文中,确保省略验证密钥 - 将其设置为空。

对于 iOS 上的 Webex 应用程序: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared

对于 iOS 上的 UC-One 应用程序: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared

6

配置以下 NPS URL:

表 2.

XSP CLI 上下文

参数

XSP_CLI/Applications/NotificationPushServer/FCM>

authURL

https://www.googleapis.com/oauth2/v4/token

pushURL

https://fcm.googleapis.com/v1/projects//messages:send

scope

https://www.googleapis.com/auth/firebase.messaging

XSP_CLI/Applications/NotificationPushServer/APNS/Production>

url

https://api.push.apple.com/3/device

7

将以下 NPS 连接参数配置为所示的建议值:

表 3.

XSP CLI 上下文

参数

XSP_CLI/Applications/NotificationPushServer/FCM>

tokenTimeToLiveInSeconds

3600

connectionPoolSize

10

connectionTimeoutInMilliseconds

3000

connectionIdleTimeoutInSeconds

600

XSP_CLI/Applications/NotificationPushServer/APNS/Production>

connectionTimeout

3000

connectionPoolSize

2

connectionIdleTimeoutInSeconds

600

8

检查应用程序服务器是否在筛选应用程序标识,因为您可能需要将 Webex 应用程序添加到允许列表中:

  1. 运行 AS_CLI/System/PushNotification> get and check the value of enforceAllowedApplicationList。 如果为 true,您需要完成此子任务。 否则,请跳过剩余的子任务。

  2. AS_CLI/System/PushNotification/AllowedApplications> add com.cisco.wx2.android “Webex Android”

  3. AS_CLI/System/PushNotification/AllowedApplications> add com.cisco.squared “Webex iOS”

1

重启 XSP:

bwrestart
2

通过从 BroadWorks 订购方呼叫 Android 上的呼叫客户端,测试 Android 上的呼叫通知。 验证 Android 设备上是否显示呼叫通知。

注: 如果 UC-One Android 应用程序推送通知启动失败,则可能是配置错误。 如果是这种情况,您可以按如下方式还原为使用旧式 FCM:

  1. 禁用 FCMv1: XSP_CLI/Applications/NotificationPushServer/FCM> set V1Enabled false

  2. 重启 XSP: bwrestart

  3. 检查配置。

  4. 重新启用 FCMv1 并重启 XSP。

  5. 重复测试。

3

通过从 BroadWorks 订购方呼叫 iOS 上的呼叫客户端,测试 iOS 上的呼叫通知。 验证 iOS 设备上是否显示呼叫通知。

注: 如果 UC-One iOS 应用程序推送通知启动失败,则可能是配置错误。 如果是这种情况,您可以通过以下命令还原为使用二进制接口:set HTTP2Enabled false