Updating Cisco BroadWorks NPS to Use NPS Proxy
Overview of NPS Authentication Proxy
NPS Proxy Overview
Your NPS needs to be patched so that it can handle the NPS Proxy function, also known as the Push Server for VoIP in UCaaS, in order for it to be compatible with Webex for BroadWorks.
Sharing push notification certificate private keys with service providers for mobile clients is a security risk that may be mitigated thanks to the implementation of a new design in the Notification Push Server that is made possible by this feature. The NPS uses a new API to retrieve a short-lived push notification token from the UCaaS backend. It then uses this token for authentication with the Apple APNs and Google FCM services, rather than sharing push notification certificates and keys with the service provider.
This addition further improves the capabilities of the Notification Push Server to send push notifications to Android devices by utilizing the newly introduced Google Firebase Cloud Messaging (FCM) HTTPv1 API.
Push Server for VoIP in UCaaS Feature Description may be found on Xchange at the following URL: https://xchange.broadsoft.com/node/1045458. For additional details, visit this page.
On Xchange, you can find the BroadWorks patches that are required for the functionality at this location: https://xchange.broadsoft.com/node/1046235.
https://xchange.broadsoft.com/node/1051580 is the address of a resource that provides additional details on the ADP server.
NPS Authentication Proxy Prerequisites
The following criteria must be satisfied by the XSP (also known as the Application Delivery Platform ADP) that serves as the host for NPS:
Minimum Versions and Co-residency Restrictions
- NPS can only be enabled on a dedicated XSP or ADP, and it must be the only hosted application on the server at the time of activation. This is done to ensure that there are no interruptions in the transmission of Push alerts.
- A deployment should only ever include a single instance of the NPS app. If you are adopting Webex for BroadWorks while also making use of mobile UC-One Collaborate/Connect and/or UC-One SaaS, then you are required to use this one and only NPS for all of your applications.
- NPS must be running XSP or ADP with a version number of R22 or later.
- If the XSP only runs NPS and the AS is R21.SP1, then R22/R23 XSP is compatible with an R21 stack. For further information, please refer to the BroadWorks Compatibility Matrix.
- https://xchange.broadsoft.com/node/1051580 is the address of a resource that provides additional details on the ADP server.
Shared NP
Before you configure your shared NPS to use the NPS Proxy, make sure you read the following notes:
- In the event that your NPS is utilized by other apps in addition to the Webex app: After the NPS proxy has been configured, the NPS should be modified so that it uses the FCM HTTP v1 API rather than the FCM old API.
- After you have confirmed that notifications are functioning as expected for older apps when using the NPS proxy, you should delete the FCM API key for the Android app and the APNs auth key for the iOS app from the respective app’s settings.
APNs HTTP/2
- Before configuring NPS to use the NPS proxy, you must first configure any iOS apps that were not developed by Cisco or BroadSoft to use the HTTP/2 APNS protocol. This step is necessary if you have already deployed any iOS apps.
- It is necessary to transition to HTTP/2 any XSPs or ADPs that are already supporting the Collaborate or SaaS BroadWorks app. See the article entitled “HTTP/2 Support to Notification Push Server for APNS” for more in-depth information on how to configure HTTP/2 (this post also provides a summary of the migration of NPS to support these iOS apps).
Android FCMv1
- Before configuring NPS to use the NPS proxy, you must first configure any Android apps that were not deployed from Cisco or BroadSoft to use the FCMv1 keys. If you have already deployed any Android apps, this step is required.
- After you have finished configuring the NPS proxy, you should enable FCMv1 keys if the XSP/ADP platform currently supports the Connect or UC-One SaaS app. It is highly recommended that you migrate all additional apps to FCMv1 keys, enable and test them, and then disable them until you are ready to finish the setup steps (the migration sequence has been defined in this post).
NPS Proxy Migration Summary
Figure 1: Graphical Outline of the NPS Authentication Proxy Migration Process
Sequence |
Task Title |
When/Why is Task Required? |
---|---|---|
1 |
It is recommended that UC-One SaaS (or Connect) iOS apps migrate from NPS to HTTP/2. |
In the event that the NPS supports such applications but they have not yet been modified to work with HTTP/2. |
2 |
It is recommended that UC-One SaaS (or Connect) Android apps migrate from NPS to FCMv1. |
If the NPS is capable of supporting certain applications, but they have not been set up to work with FCMv1, then. |
3 |
Test out push notifications while the FCMv1 mode is enabled. |
If the NPS supports UC-One Connect as well as other Android applications that are not made by Cisco. |
4 |
Re-enable legacy mode for the FCM. |
In the event that the NPS provides support for UC-One SaaS. If you do not disable FCMv1 before configuring the NPS proxy, then push notifications to UC-One SaaS will not work properly. |
5 |
Install the changes for the NPS authentication proxy. |
In the event that NPS is running on XSP R22 or XSP R23. |
6 |
Set up NPS to use the NPS authentication proxy by configuring the following:
|
Always required. |
7 |
Take out the keys for the FCM legacy mode. |
For applications that NPS has demonstrated a capacity to serve well on FCMv1. |
Migrate BroadWorks Collaborate iOS Apps to HTTP/2
For push alerts to be sent to UC-One SaaS and Webex apps running on iOS platforms, this task must be completed.
Before you begin
Before you can configure the NPS application to make advantage of HTTP/2 for APNS, you will first need to apply ap354313 to your XSP if it is running R22.
1 Set the production URL and connection parameters at XSP_CLI/Applications/NotificationPushServer/APNS/Production>
set url https://api.push.apple.com/3/device
set connectionPoolSize 2
set connectionTimeout 3000
set connectionIdleTimeoutInSeconds 600
Note: It is imperative that the connection timeout not be set lower than 1000.
2 When adding the application IDs to the APNS apps context, make sure that the Auth key is omitted and that it is set to have no value.
XSP_CLI/Applications/Notification is the path to take for UC-One SaaS.Add com.broadsoft.uc-one to the PushServer/APNS/Production/Tokens directory.
XSP_CLI/Applications/Notification is the path to take for the Webex app.Add com.cisco.squared to the PushServer/APNS/Production/Tokens directive.
3 Make that the authorization keys are correct by using XSP_CLI/Applications/Notification.PushServer/APNS/Production/Tokens is the URI that you should enter. get
4 Clearing the auth key for com.broadsoft.uc-one using the XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens command is possible if the key is not already empty. void the authorization key.
5 Make sure HTTP/2 is enabled:
Applications/Notification of XSP_CLI EventsSet the HTTP2Enabled variable to true in the PushServer/APNS/GeneralSettings menu.
6 This only applies to UC-One SaaS apps: After successfully logging into the reseller portal, navigate to Configuration > BroadWorks >.
7 Scroll all the way down until you reach the section titled “Notification Push Server,” choose your release (for example, Release 22), and then follow the instructions that are provided in the portal.
Migrate BroadWorks UC-One Connect / SaaS Android Apps to FCMv1
- This task pertains to NPS while working on XSP. If your NPS is on ADP, you can ignore it.
- The migration to FCMv1 notifications for UC-One Connect or UC-One SaaS Android apps can be accomplished by following this approach.
- If you want to authenticate push notifications to UC-One or the Webex Android apps using the NPS proxy, you will need to use FCMv1. This is a requirement.
- In order for you to be able to enable the FCMv1 as part of the configuration of the NPS authentication proxy, this job will prepare the NPS for use with the FCMv1. If you enable FCMv1 before you are ready to configure the NPS authentication proxy, the notifications that are sent to SaaS customers will not work.
1 Obtain the project ID from the Firebase console by doing the following:
- Create an account on the console.firebase.google.com website.
- Choose the UC-One (Connect or SaaS) app project, and then open the settings for that particular project.
- Launch the tab labeled General, then make a note of the project ID.
2 Obtain the private key associated with your service account from Firebase:
- To access the Service accounts page, navigate to the settings for the project.
- Either establish a brand new service account and obtain the private key associated with it.
- You could also create a new private key for an existing service account after opening the account.
- Please take note that the firebaseadmin-sdk permission needs to be granted to the service account.
- Save the key in a safe place after you download it.
3 Make a copy of the key and save it to the XSP that is hosting your NPS.
4 In the context of the FCM projects, add the project ID together with the accompanying private key:
XSP_CLI/Applications/NotificationPushServer/FCM/Projects> add project-id path/to/keyfile in the projects directory
5 Add the UC-One application (Connect or SaaS) and the project ID linked with it to the FCM apps context:
Applications/Notification of XSP_CLI EventsApplications> PushServer/FCM/Applications com.broadsoft.connect should be added as the applicationId. projectId project-id project-id
6 Verify that the setup for FCM corresponds to the attributes and values that are recommended in this section. In the event that the values require modification, use the set version of the command:
Carry out the operations specified in XSP_CLI/Applications/NotificationPushServer/FCM>. get
Parameter |
Recommended Value |
---|---|
|
|
|
|
|
|
|
3600 |
|
10 |
|
3000 |
|
600 |
Migrate BroadWorks UC-One Connect / SaaS Android Apps to FCMv1 (on ADP)
This assignment pertains to NPS on ADP. If your NPS is on XSP, you can disregard this warning.
You can migrate to FCMv1 notifications for UC-One Connect or UC-One SaaS Android apps by following the steps outlined here.
If you want to use the NPS proxy to authenticate push notifications to UC-One or the Webex Android apps, then you will need to use FCMv1.
This job gets the NPS ready for FCMv1 so that it may be enabled as part of the configuration of the NPS authentication proxy later on. If you enable FCMv1 before you are ready to configure the NPS authentication proxy, then alerts to SaaS customers will not work properly.
1 Obtain the project ID from the Firebase console by doing the following:
- Create an account on the console.firebase.google.com website.
- Choose the UC-One (Connect or SaaS) app project, and then open the settings for that particular project.
- Launch the tab labeled General, then make a note of the project ID.
2 Get the private key associated with your service account from Firebase:
- To access the Service accounts page, navigate to the settings for the project.
- Either establish a brand new service account and obtain the private key associated with it.
- You could also create a new private key for an existing service account after opening the account.
- Please take note that the firebaseadmin-sdk permission needs to be granted to the service account.
- Save the key (a file ending in.json) in a safe place after downloading it.
3 Upload the file ending in.json to the ADP server located at /bw/install.
4 After logging in to the ADP CLI, add the project as well as the API key to the FCM projects context:
Applications and notifications for the ADP_CLIAdd connect-ucaas to /bw/install/filename.json in the PushServer/FCM/Projects directory.
5 Include the application ID as well as the project ID within the FCM apps context:
Applications and notifications for the ADP_CLIApplications> PushServer/FCM/Applications com.broadsoft.ucaas.connect should be added as the applicationId. projectId project-id project-id
6 Make sure that your configuration is correct:
|
Re-enable FCM Legacy Mode
As part of the migration, you are only need to carry out this task if:
- In order to utilize the UC-One SaaS or BroadWorks Connect Android apps, your NPS is required.
- You have already verified that the FCMv1 API can successfully send call push notifications to other applications.
Because the FCMv1 keys for these applications can only be enabled once the NPS authentication proxy configuration process has been completed, you are temporarily blocking FCMv1.
1 Authenticate yourself using the XSP that is hosting your shared NPS.
2 Navigate to the FCM context and disable FCM v1 by entering the following command: XSP_CLI/Applications/NotificationPushServer/FCM> set V1enabled false. This will cause the FCM legacy API key to be used going forward.
Install NPS Authentication Proxy Patches
The following patches need to be installed in order to implement the NPS authentication proxy feature:
R22 Patches
-
AP.xsp.22.0.1123.ap369607
-
AP.platform.22.0.1123.ap369607
-
AP.xsp.22.0.1123.ap374677
-
AP.xsp.22.0.1123.ap375206
-
AP.xsp.22.0.1123.ap354313
-
AP.platform.22.0.1123.ap354313
R23 Patches
-
AP.xsp.23.0.1075.ap369607
-
AP.platform.23.0.1075.ap369607
-
AP.xsp.23.0.1075.ap374677
-
AP.xsp.23.0.1075.ap375206
Configure NPS to Use Authentication Proxy
1 In order to provision your (Webex Common Identity) OAuth client account, you will need to create a service request either with your onboarding contact or with TAC. NPS Configuration for Auth Proxy Setup should be the title of your service request.
You will be provided with an OAuth client ID, a client secret, and a refresh token that has a validity period of sixty days from the time it was generated. You are free to submit a fresh request in the event that the token becomes invalid before you have a chance to use it with your NPS.
2 Create a client account on the NPS by following these steps:
set clientId to the client-Id-From-Step1 value in the XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client file.
Applications/Notification of XSP_CLI EventsClient > PushServer > Cisco CI > clientSecret should be set.
client is the new password.”Secret From Step One”
Applications/Notification of XSP_CLI EventsClient > PushServer > Cisco CI > configure the RefreshToken
Reset Your Password: Renew the token obtained in Step 1
Execute the command XSP_CLI/Applications/Notification to check that the values you entered are the same as the ones you were given.Client > PushServer > Cisco CI > get
3 Input the URL for the NPS Proxy, and make sure the token refresh interval is set to the recommended thirty minutes:
CloudNPSService> set url to https://nps.uc-one.broadsoft.com/nps/ in the XSP_CLI/Applications/NotificationPushServer/CloudNPSService script.
set VOIPTokenRefreshInterval 1800 in XSP_CLI/Applications/NotificationPushServer/CloudNPSService
4 (Regarding the notifications on Android) Include the IDs of the Android applications in the FCM applications context that is hosted on the NPS.
XSP_CLI/Applications/Notification is the path to go for the Webex app for Android.Add the com.cisco.wx2.android package to the PushServer/FCM/Applications directory.
Regarding the UC-One application on Android: Applications/Notification of XSP_CLI EventsAdd the com.broadsoft.connect package to the PushServer/FCM/Applications directory.
5 (Regarding notifications on Apple’s iOS) When adding the application ID to the APNS apps context, make sure that the Auth key is omitted and that it is set to have an empty value.
XSP_CLI/Applications/Notification is the path to go for the Webex app for iOS.Add com.cisco.squared to the PushServer/APNS/Production/Tokens directive.
For those using the UC-One app on iOS: Applications/Notification of XSP_CLI EventsAdd com.cisco.squared to the PushServer/APNS/Production/Tokens directive.
6
Please configure the NPS URLs listed below:
|
7 Adjust the following NPS connection parameters so that they correspond to the values provided in the recommendations:
XSP CLI Context |
Parameter |
Value |
---|---|---|
|
|
3600 |
|
10 |
|
|
3000 |
|
|
600 |
|
|
|
3000 |
|
2 |
|
|
600 |
8 Determine whether or not the Application Server is screening application IDs; if it is, you will need to add the Webex apps to the list of those that are permitted to run.
- Get the value of the enforceAllowedApplicationList environment variable by using the AS_CLI/System/PushNotification> command. You are required to finish this subsidiary task if what you say is accurate. In that case, you should ignore the remaining steps of the subtask.
- Add “Webex Android” to the list of allowed applications in the AS_CLI/System/PushNotification/AllowedApplications file.
- Add “Webex iOS” to the list of allowed applications in the AS_CLI/System/PushNotification/AllowedApplications file.
Restart NPS and Test Push Notifications
1 Restart the XSP in its entirety:
2 Calls can be placed from a BroadWorks subscriber to the calling client running on Android in order to test out the call notification functionality. Check to see if the Android device displays a notification for incoming calls.
Note: If the UC-One android application’s push notifications start failing, it is probable that there is an issue with the application’s setup. If this describes your circumstances, the following is how you can switch back to using the legacy FCM:
- XSP_CLI/Applications/Notification should have FCMv1 disabled.Set V1Enabled to false in the PushServer/FCM configuration.
- bwrestart is used to restart XSP.
- Make sure your setting is correct.
- Activate FCMv1 again, and then restart the XSP.
- Try the test once more.
3 Calls can be made from a BroadWorks subscriber to the calling client on iOS in order to test out the call notification functionality. Check to see that a notification of the incoming call appears on the iOS device.
Note: It is likely that there is an error in configuration if the UC-One iOS application suddenly begins experiencing problems with its push notifications. In the event that this describes your circumstance, you can go back to the older binary interface by inputting set HTTP2Enabled false.