Overview of NPS Authentication Proxy

This article describes how to configure a shared NPS to use NPS authentication proxy, so that it can also be used to push call notifications to Webex apps. If your NPS does not support other apps, you can follow the simplified procedure in the Webex for BroadWorks Solution Guide https://help.webex.com/z9gt5j.

NPS Proxy Overview

For compatibility with Webex for BroadWorks, your NPS must be patched to support the NPS Proxy feature, Push Server for VoIP in UCaaS.

The feature implements a new design in the Notification Push Server to resolve the security vulnerability of sharing push notification certificate private keys with service providers for mobile clients. Instead of sharing push notification certificates and keys with the service provider, the NPS uses a new API to obtain a short-lived push notification token from UCaaS backend, and uses this token for authentication with the Apple APNs and Google FCM services.

The feature also enhances the capability of the Notification Push Server to push notifications to Android devices through the new Google Firebase Cloud Messaging (FCM) HTTPv1 API.

NPS Authentication Proxy Prerequisites

The XSP (or Application Delivery Platform ADP) that hosts NPS must meet the following requirements:

Minimum Versions and Co-residency Restrictions

  • NPS must be activated on a dedicated XSP/ADP and NPS must be the only hosted application on the server. This is to eliminate interference with the delivery of Push notifications.

  • There should only be one NPS app in a deployment. If you're using mobile UC-One Collaborate/Connect and or UC-One SaaS, and are implementing Webex for BroadWorks, you must share this single NPS for all the apps.

  • NPS must be on version R22 or later XSP, or ADP.

    R22/R23 XSP is compatible with an R21 stack if the XSP only runs NPS and the AS is R21.SP1. See the BroadWorks Compatibility Matrix for more information.

  • More information on the ADP server can be found at https://xchange.broadsoft.com/node/1051580.

Shared NPS

Read these notes before you configure your shared NPS to use the NPS Proxy:

  • If your NPS is used with other apps (not just the Webex app): First configure the NPS proxy, then change the NPS from using the FCM legacy API to using FCM HTTP v1 API.

  • After you have verified that notifications are working properly for older apps with the NPS proxy, then remove the FCM API key for the Android app, and the APNs auth key for the iOS app.

APNs HTTP/2

  • If you have deployed any iOS apps that are not from Cisco/BroadSoft, configure those apps to use the HTTP/2 APNS protocol before configuring NPS to use the NPS proxy.

  • XSP/ADPs that already support the Collaborate or SaaS BroadWorks app need to be migrated to HTTP/2. For detailed information on configuring HTTP/2, see HTTP/2 Support to Notification Push Server for APNS (migration of NPS to support these iOS apps is summarized in this article).

Android FCMv1

  • If you have deployed any Android apps that are not from Cisco/BroadSoft, configure those apps to use the FCMv1 keys before configuring NPS to use the NPS proxy.

  • If XSP/ADP currently supports the Connect or UC-One SaaS app, then enable FCMv1 keys after you configure NPS proxy. We recommend that you migrate all additional apps to FCMv1 keys, enable and test, then disable until you're ready to complete the setup instructions (the migration flow is documented in this article).

NPS Proxy Migration Summary

Figure 1. Visual Summary of Migration to NPS Authentication Proxy
Table 1. Summary of Tasks to Migrate to NPS Proxy

Sequence

Task Title

When/Why is Task Required?

1

Migrate NPS to HTTP/2 for UC-One SaaS (or Connect) iOS apps.

If the NPS supports those apps, and they are not yet configured for HTTP/2.

2

Migrate NPS to FCMv1 for UC-One SaaS (or Connect) Android apps.

If the NPS supports those apps, and they are not yet configured for FCMv1.

3

Enable FCMv1 mode, and test push notifications.

If the NPS is supporting UC-One Connect and/or other (non-Cisco) Android apps.

4

Re-enable FCM legacy mode.

If the NPS is supporting UC-One SaaS. If you leave FCMv1 enabled, before you configure the NPS proxy, then push notifications to UC-One SaaS start failing.

5

Install NPS authentication proxy patches.

If NPS is on XSP R22 or XSP R23.

6

Configure NPS to use the NPS authentication proxy:

  • Attach techsupport from NPS

  • Request CI OAuth account

  • Create CI account on NPS and configure refresh token timeout

  • Add Android app ids

  • Add iOS app ids

  • Check/set URLs and connection timeouts

  • Add apps to AS allow list

  • (Re-)Enable FCMv1

  • Restart XSP / ADP

  • Test PNs for iOS and Android apps

Always required.

7

Remove FCM legacy mode keys.

For apps that are successfully supported by NPS on FCMv1.

Migrate BroadWorks Collaborate iOS Apps to HTTP/2

This task is mandatory for push notifications to UC-One SaaS and Webex apps on iOS platforms.

Before you begin

If your XSP is running R22, you need to apply ap354313 before you can configure the NPS application to use HTTP/2 for APNS.

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: Do not set the connection timeout below 1000.

2

Add the application IDs to the APNS applications context, making sure to omit the Auth key – set it to empty.

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

For Webex app: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared
3

Check the auth keys with XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> get
4

If the auth key is not empty for com.broadsoft.uc-one, you can clear it with XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> clear the-authkey
5

Enable HTTP/2:

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

For UC-One SaaS apps only: Sign in to the reseller portal and go to Configuration > BroadWorks > .
7

Scroll down to the Notification Push Server section, and select your release (e.g. Release 22), then follow the instructions provided in the portal.

Migrate BroadWorks UC-One Connect / SaaS Android Apps to FCMv1

  • This task applies to NPS on XSP. Ignore it if your NPS is on ADP.

  • You can use this procedure for migrating to FCMv1 notifications for UC-One Connect or UC-One SaaS Android apps.

  • You must use FCMv1 if you want to use the NPS proxy to authenticate push notifications to UC-One or the Webex Android apps.

  • This task prepares the NPS for FCMv1 so that you can enable it as part of the configuration of NPS authentication proxy. Do not enable FCMv1 until you are ready to configure NPS authentication proxy, or notifications to SaaS clients will fail.

1

Get the project ID from Firebase console:

  1. Sign in to console.firebase.google.com.

  2. Select the UC-One (Connect or SaaS) app project, open its project settings.

  3. Open the General tab and record the project ID.

2

Get your service account’s private key from Firebase:

  1. Navigate to the Service accounts tab in the project settings.

  2. Either create a new service account and get its private key.

  3. Or open an existing service account and generate a new private key for it.

    Note: The service account must have the firebaseadmin-sdk permission.

  4. Download the key to a secure location.
3

Copy the key to the XSP hosting your NPS.
4

Add the project ID and associated private key to the FCM projects context:

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

Add the UC-One (Connect or SaaS) application and associated project ID to the FCM applications context:

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

Check the configuration for FCM against the attributes and recommended values shown here. Use set version of the command to change values if necessary:

Run XSP_CLI/Applications/NotificationPushServer/FCM> get

Parameter

Recommended Value

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

Migrate BroadWorks UC-One Connect / SaaS Android Apps to FCMv1 (on ADP)

  • This task applies to NPS on ADP. Ignore it if your NPS is on XSP.

  • You can use this procedure for migrating to FCMv1 notifications for UC-One Connect or UC-One SaaS Android apps.

  • You must use FCMv1 if you want to use the NPS proxy to authenticate push notifications to UC-One or the Webex Android apps.

  • This task prepares the NPS for FCMv1 so that you can enable it as part of the configuration of NPS authentication proxy. Do not enable FCMv1 until you are ready to configure NPS authentication proxy, or notifications to SaaS clients will fail.

1

Get the project ID from Firebase console:

  1. Sign in to console.firebase.google.com.

  2. Select the UC-One (Connect or SaaS) app project, open its project settings.

  3. Open the General tab and record the project ID.

2

Get your service account’s private key from Firebase:

  1. Navigate to the Service accounts tab in the project settings.

  2. Either create a new service account and get its private key.

  3. Or open an existing service account and generate a new private key for it.

    Note: The service account must have the firebaseadmin-sdk permission.

  4. Download the key (.json file) to a secure location.
3

Import the .json file to the ADP server /bw/install.

4

Login to ADP CLI and add the project and API key to the FCM projects context:

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

Add the application and project ID to the FCM applications context:

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

Verify your configuration:

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

Re-enable FCM Legacy Mode

You only need to do this (as part of the migration) if:

  • Your NPS is used for UC-One SaaS or BroadWorks Connect Android apps.

  • You already tested that call push notifications to other apps are working with FCMv1 API.

You are temporarily disabling FCMv1 because FCMv1 keys for these apps must only be enabled during the NPS authentication proxy configuration process.

1

Sign in to the XSP hosting your shared NPS.
2

Navigate to the FCM context and disable FCM v1: XSP_CLI/Applications/NotificationPushServer/FCM> set V1enabled false to revert to using the FCM legacy API key.

Install NPS Authentication Proxy Patches

Configure NPS to Use Authentication Proxy

1

Create a service request with your onboarding contact, or with TAC, to provision your (Webex Common Identity) OAuth client account. Title your service request NPS Configuration for Auth Proxy Setup.

Cisco gives you an OAuth client ID, a client secret, and a refresh token that is valid for 60 days. If the token expires before you use it with your NPS, you can raise another request.
2

Create the client account on the 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

To verify the values you entered match with what you were given, run XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> get
3

Enter the NPS Proxy URL, and set the token refresh interval (30 minutes recommended):

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

XSP_CLI/Applications/NotificationPushServer/CloudNPSService> set VOIPTokenRefreshInterval 1800
4

(For Android notifications) Add the Android application IDs to the FCM applications context on the NPS.

For Webex app on Android: XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add com.cisco.wx2.android

For UC-One app on Android: XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add com.broadsoft.connect
5

(For Apple iOS notifications) Add the application ID to the APNS applications context, making sure to omit the Auth key – set it to empty.

For Webex app on iOS: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared

For UC-One app on iOS: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared
6

Configure the following NPS URLs:

Table 2.

XSP CLI Context

Parameter

Value

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

Configure the following NPS connection parameters to the recommended values shown:

Table 3.

XSP CLI Context

Parameter

Value

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

Check if the Application Server is screening application IDs, because you may need to add the Webex apps to the allow list:

  1. Run AS_CLI/System/PushNotification> get and check the value of enforceAllowedApplicationList. If it is true, you need to complete this sub task. Otherwise, skip the rest of the sub task.

  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”

Restart NPS and Test Push Notifications

1

Restart the XSP:

bwrestart
2

Test call notifications to Android by making calls from a BroadWorks subscriber to the calling client on Android. Verify that call notification appears on the Android device.

Note: If push notifications start failing for the UC-One android application, it is possible that there is a misconfiguration. If this is your situation, you can revert to the legacy FCM as follows:

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

  2. Restart XSP: bwrestart

  3. Check your configuration.

  4. Re-enable FCMv1 and restart the XSP.

  5. Repeat the test.
3

Test call notifications to iOS by making calls from a BroadWorks subscriber to the calling client on iOS. Verify that call notification appears on the iOS device.

Note: If push notifications start failing for the UC-One iOS application, it is possible that there is a misconfiguration. If this is your situation, you can revert to the legacy binary interface with set HTTP2Enabled false