Deploy Webex for BroadWorks

Deployment Overview

The following diagrams represent the typical order of your deployment tasks for the different user provisioning modes. Many of the tasks are common to all provisioning modes.

Figure 1. Tasks required for deploying flow-through provisioning
Shows the order of tasks required for deploying Webex for BroadWorks with flow-through provisioning and trusted emails
Figure 2. Tasks required for deploying flowthrough provisioning without trusted emails
Shows the order of tasks required for deploying Webex for BroadWorks with flow-through provisioning without emails
Figure 3. Tasks required for deploying user self-provisioning
Shows the order of tasks required for deploying Webex for BroadWorks with self-activation

Partner Onboarding for Cisco Webex for BroadWorks

Each Webex for BroadWorks Service Provider or Reseller needs a to be setup as a Partner Organization for Cisco Webex for BroadWorks. If you have an existing Cisco Webex Partner Organization, this can be used.

In order to complete the necessary onboarding, you must execute your Webex for BroadWorks paperwork and new partners must accept the online Indirect Channel Partner Agreement (ICPA). When these steps are completed, Cisco Compliance will create a new Partner Org in Partner Hub (if needed) and send an email with authentication details to the Admin of Record in your paperwork. At the same time, your Partner Activation and/or Customer Success Program Manager will contact you to start your onboarding.

Configure Services on Your Webex for BroadWorks XSPs

We require that the NPS application be run on a different XSP. Requirements for that XSP are described in Configure Call Notifications from your Network.

You need the following applications / services on your XSPs.

Service/Application

Authentication required

Service/application purpose

Xsi-Events

TLS (server authenticates itself to clients)

Call control, service notifications

Xsi-Actions

TLS (server authenticates itself to clients)

Call control, actions

Device management

TLS (server authenticates itself to clients)

Calling configuration download

Authentication Service

mTLS (client and server authenticate each other)

User authentication

Computer Telephony Integration

mTLS (client and server authenticate each other)

Telephony presence

This section describes how to apply the required configurations for TLS and mTLS on these interfaces, but you should reference existing documentation to get the applications installed on your XSPs.

Co-Residency Requirements

  • Authentication Service must be co-resident with Xsi applications, because those interfaces must accept long-lived tokens for service authorization. The authentication service is required to validate those tokens.

  • Authentication service and Xsi can run on the same port if required.

  • You may separate the other services/applications as required for your scale (dedicated device management XSP farm, for example).

  • You may co-locate the Xsi, CTI, Authentication Service, and DMS applications.

  • Do not install other applications or services on the XSPs that are used for integrating BroadWorks with Webex.

  • Do not co-locate the NPS application with any other applications.

Xsi Interfaces

Install and configure the Xsi-Actions and Xsi-Events applications as described in Cisco BroadWorks Xtended Services Interface Configuration Guide.

Install Authentication Service

Install Authentication Service

On BroadWorks R22 and up, you don’t need to install the authentication service, as it’s a managed application.

On BroadWorks 21SP1, the authentication service is an unmanaged application. Install it by completing the following steps:

  1. Download authenticationService_1.0.war (web application resource) file from Xchange (https://xchange.broadsoft.com/node/499012).

    On each XSP used with Webex, do the following:

  2. Copy the .war file to a temporary location on the XSP, such as /tmp/

  3. Install authentication service application with the following CLI context and command:

    XSP_CLI/Maintenance/ManagedObjects> install application /tmp/authenticationService_1.0.war

Configure Authentication Service

BroadWorks long-lived tokens are generated and validated by the authentication service hosted on your XSPs.

Requirements

  • The XSP servers hosting the Authentication Service must have an mTLS interface configured.

  • XSPs must share the same keys for encrypting/decrypting BroadWorks long lived tokens. Copying these keys to each XSP is a manual process.

  • XSPs must be synchronized with NTP.

Configuration Overview

The essential configuration on your XSPs includes:

  • Deploy the authentication service.

  • Configure token duration to at least 60 days (leave the issuer as BroadWorks).

  • Generate and share RSA keys across XSPs.

  • Provide the authService URL to the web container.

Deploy the Authentication Service on XSP

On each XSP used with Webex:

  1. Activate the authentication service application on the path /authService (you must use this path):

    XSP_CLI/Maintenance/ManagedObjects> activate application authenticationService <version> /authService

    (where <version> is 1.0 for the unmanaged application on 21SP1, or your BroadWorks version for 22 or later).

  2. Deploy the application:

    XSP_CLI/Maintenance/ManagedObjects> deploy application /authService

Configure Token Duration

  1. Check the existing token configuration (hours):

    On 21SP1:XSP_CLI/Applications/authenticationService_1.0/TokenManagement> get

    On 22 and later: XSP_CLI/Applications/authenticationService/TokenManagement> get

  2. Set the duration to 60 days (max is 180 days):

    On 21SP1:XSP_CLI/Applications/authenticationService_1.0/TokenManagement> set tokenDuration 1440

    On 22 and later: XSP_CLI/Applications/authenticationService/TokenManagement> set tokenDurationInHours 1440

Generate and Share RSA Keys

  • You must use the same public/private key pairs for token encryption/decryption across all instances of the authentication service.

  • The key pair is generated by the authentication service when it is first required to issue a token.

Because of these two factors you need to generate keys on one XSP then copy them to all other XSPs.


If you cycle keys or change the key length, you need to repeat the following configuration and restart all the XSPs.

  1. Select one XSP to use for generating a key pair.

  2. Use a client to request an encrypted token from that XSP, by requesting the following URL from the client’s browser:

    https://<XSP-IPAddress>/authService/token?key=BASE64URL(clientPublicKey)

    (This generates a private / public key pair on the XSP, if there wasn’t one already)

  3. (21SP1 only) Check the configurable key location using the following command:

    XSP_CLI/Applications/authenticationService_1.0/KeyManagement> get

  4. (21SP1 only) Take note of the returned fileLocation parameter.

  5. (21SP1 only) Copy the whole fileLocation directory, which contains public and private subdirectories, to all other XSPs.

  6. (R22 and later) The key store location is not configurable. Export the keys:

    XSP_CLI/Applications/authenticationService/KeyManagement> exportKeys

  7. (R22 and later) Copy the exported file /var/broadworks/tmp/authService.keys to the same location on the other XSPs, overwriting an older .keys file if necessary.

  8. (R22 and later) Import the keys on each of the other XSPs:

    XSP_CLI/Applications/authenticationService/KeyManagement> importKeys /var/broadworks/tmp/authService.keys

Provide the authService URL to the web container

The XSP’s web container needs the authService URL so it can validate tokens.

On each of the XSPs:

  1. Add the authentication service URL as an external authentication service for the BroadWorks Communications Utility:

    XSP_CLI/System/CommunicationUtility/DefaultSettings/ExternalAuthentication/AuthService> set url http://127.0.0.1/authService

  2. Add the authentication service URL to the container:

    XSP_CLI/Maintenance/ContainerOptions> add tomcat bw.authservice.authServiceUrl http://127.0.0.1/authService

    This enables Cisco Webex to use the Authentication Service to validate tokens presented as credentials.

  3. Check the parameter with get.

  4. Restart the XSP.

Configuring TLS and Ciphers on the HTTP Interfaces (for XSI and Authentication Service)

The Authentication Service, Xsi-Actions, and Xsi-Events applications use HTTP server interfaces. Levels of TLS configurability for these applications are as follows:

Most general = System > Transport > HTTP > HTTP Server interface = Most specific

The CLI contexts you use to view or modify the different SSL settings are:

Specificity CLI context
System (global)

XSP_CLI/System/SSLCommonSettings/JSSE/Ciphers>

XSP_CLI/System/SSLCommonSettings/JSSE/Protocols>

Transport protocols for this system

XSP_CLI/System/SSLCommonSettings/OpenSSL/Ciphers>

XSP_CLI/System/SSLCommonSettings/OpenSSL/Protocols>

HTTP on this system

XSP_CLI/Interface/Http/SSLCommonSettings/Ciphers>

XSP_CLI/Interface/Http/SSLCommonSettings/Protocols>

Specific HTTP server interfaces on this system

XSP_CLI/Interface/Http/HttpServer/SSLSettings/Ciphers>

XSP_CLI/Interface/Http/HttpServer/SSLSettings/Protocols>

Reading HTTP Server TLS Interface Configuration on the XSP

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/Http/HttpServer>

  2. Enter the get command and read the results. You should see the interfaces (IP addresses) and, for each, whether they are secure and whether they require client authentication.

Apache tomcat mandates a certificate for each secure interface; the system generates a self-signed certificate if it needs one.

XSP_CLI/Interface/Http/HttpServer> get

Adding TLS 1.2 Protocol to the HTTP Server Interface


This procedure applies to R22 and later. To configure TLS version on R21(SP1), you must use the XSP platform container option bw.apache.sslenabledprotocols.

The HTTP interface that is interacting with the Cisco Webex cloud must be configured for TLSv1.2. The cloud does not negotiate earlier versions of the TLS protocol.

To configure the TLSv1.2 protocol on the HTTP Server interface:

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/Http/HttpServer/SSLSettings/Protocols>

  2. Enter the command get <interfaceIp> 443 to see which protocols are already used on this interface.

  3. Enter the command add <interfaceIp> 443 TLSv1.2 to ensure that interface can use TLS 1.2 when communicating with the cloud.

Editing TLS Ciphers Configuration on the HTTP Server Interface


This procedure applies to R22 and later. To configure TLS ciphers on R21(SP1), you must use the XSP platform container option bw.apache.sslciphersuite.

To configure the required ciphers:

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/Http/HttpServer/SSLSettings/Ciphers>

  2. Enter the command get <interfaceIp> 443 to see which ciphers are already used on this interface. There must be at least one from the Cisco recommended suites (see XSP Identity and Security Requirements in the Overview section).

  3. Enter the command add <interfaceIp> 443 <cipherName> to add a cipher to the HTTP Server interface.


    The XSP CLI requires the IANA standard cipher suite name, not the openSSL cipher suite name. For example, to add the openSSL cipher ECDHE-ECDSA-CHACHA20-POLY1305 to the HTTP server interface, you would use: XSP_CLI/Interface/Http/HttpServer/SSLSettings/Ciphers>add 192.0.2.7 443 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

    See https://ciphersuite.info/ to find the suite by either name.

Configure mTLS for AuthenticationService

Configure Trust (R21 SP1)
  1. Sign in to Partner Hub.

  2. Go to Settings > BroadWorks Calling and click Download Webex CA Certificate to get CombinedCertChain.txt on your local computer.


    This file contains two certificates. You need to split the file before you upload it to the XSPs.

  3. Split the certificate chain into two certificates:

    1. Open combinedcertchain.txt in a text editor.

    2. Select and cut the first block of text, including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, and paste the text block into a new file.

    3. Save the new file as broadcloudroot.txt.

    4. Save the original file as broadcloudissuing.txt.

      The original file should now only have one block of text, surrounded by the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  4. Copy both text files to a temporary location on the XSP you are securing, e.g. /tmp/broadcloudroot.txt and /tmp/broadcloudissuing.txt.

  5. Sign in to the XSP and navigate to /XSP_CLI/Interface/Http/ClientAuthentication>

  6. Run the get command and read the chainDepth parameter.

    (chainDepth is 1 by default, which is too low for the Webex chain which has two certificates)

  7. If the chainDepth is not already greater than 2, run set chainDepth 2.

  8. (Optional) Run help updateTrust to see the parameters and command format.

  9. Upload the certificate files to new trust anchors:

    XSP_CLI/Interface/Http/ClientAuthentication/Trusts> updateTrust webexclientroot /tmp/broadcloudroot.txt

    XSP_CLI/Interface/Http/ClientAuthentication/Trusts> updateTrust webexclientissuing /tmp/broadcloudissuing.txt


    webexclientroot and webexclientissuing are example aliases for the trust anchors; you can use your own.

  10. Confirm both certificates are uploaded:

    /XSP_CLI/Interface/Http/ClientAuthentication/Trusts> get

Configure Trust (R22 and later)

  1. Sign in to Control Hub with your partner administrator account.

  2. Go to Settings > BroadWorks Calling and click Download Webex CA Certificate to get CombinedCertChain.txt on your local computer.


    This file contains two certificates. You need to split the file before you upload it to the XSPs.

  3. Split the certificate chain into two certificates:

    1. Open combinedcertchain.txt in a text editor.

    2. Select and cut the first block of text, including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, and paste the text block into a new file.

    3. Save the new file as broadcloudroot.txt.

    4. Save the original file as broadcloudissuing.txt.

      The original file should now only have one block of text, surrounded by the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  4. Copy both text files to a temporary location on the XSP you are securing, e.g. /tmp/broadcloudroot.txt and /tmp/broadcloudissuing.txt.

  5. (Optional) Run help UpdateTrust to see the parameters and command format.

  6. Upload the certificate files to new trust anchors:

    XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexclientroot /tmp/broadcloudroot.txt

    XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexclientissuing /tmp/broadcloudissuing.txt


    webexclientroot and webexclientissuing are example aliases for the trust anchors; you can use your own.

  7. Confirm the anchors are updated:

    XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts> get

      Alias   Owner                                   Issuer
    =============================================================================
    webexclientissuing    BroadCloud Commercial Issuing CA – DA3     BroadCloud Commercial Trusted Root CA
    webexclientroot       BroadCloud Commercial Trusted Root CA      BroadCloud Commercial Trusted Root CA[self-signed]

(Option) Configure mTLS at the HTTP interface/port level

It is possible to configure mTLS at the HTTP interface/port level or on a per-web application basis.

The way you enable mTLS for your application depends on the applications you are hosting on the XSP. If you are hosting multiple applications that require mTLS, you should enable mTLS on the interface. If you only need to secure one of several applications that use the same HTTP interface, you can configure mTLS at the application level.

When configuring mTLS at the HTTP interface/port level, mTLS is required for all hosted web applications accessed via this interface/port.

  1. Sign in to the XSP whose interface you're configuring.

  2. Navigate to XSP_CLI/Interface/Http/HttpServer> and run the get command to see the interfaces.

  3. To add an interface and require client authentication there (which means the same as mTLS):

    XSP_CLI/Interface/Http/HttpServer> add IPAddress Port Name true true

    See the XSP CLI documentation for detail. Essentially, the first true secures the interface with TLS (server certificate is created if required) and the second true forces the interface to require client certificate authentication (together they are mTLS).

For example:

XSP_CLI/Interface/Http/HttpServer> get

Interface Port Name Secure Client Auth Req Cluster Fqdn
         =======================================================
         192.0.2.7 443 xsp01.collab.example.net true false 
         192.0.2.7 444 xsp01.collab.example.net true true

In this example, mTLS (Client Auth Req = true) is enabled on 192.0.2.7 port 444. TLS is enabled on 192.0.2.7 port 443.

(Option) Configure mTLS for specific web applications

It is possible to configure mTLS at the HTTP interface/port level or on a per-web application basis.

The way you enable mTLS for your application depends on the applications you are hosting on the XSP. If you are hosting multiple applications that require mTLS, you should enable mTLS on the interface. If you only need to secure one of several applications that use the same HTTP interface, you can configure mTLS at the application level.

When configuring mTLS at the application level, mTLS is required for that application regardless of the HTTP server interface configuration.

  1. Sign in to the XSP whose interface you're configuring.

  2. Navigate to XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/WebApps> and run the get command to see which applications are running.

  3. To add an application and require client authentication for it (which means the same as mTLS):

    XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/WebApps> add IPAddress Port ApplicationName true

    See the XSP CLI documentation for detail. The application names are enumerated there. The true in this command enables mTLS.

For example:

XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/WebApps> add 192.0.2.7 443 AuthenticationService true

The example command adds the AuthenticationService application to 192.0.2.7:443 and requires it to request and authenticate certificates from the client.

Check with get:

XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/WebApps> get

Interface Ip Port Application Name Client Auth Req
         ===================================================
         192.0.2.7 443 AuthenticationService      true          

Configure Device Management on XSP, Application Server, and Profile Server

Profile Server and XSP are mandatory for Device Management. They must be configured according to instructions in the BroadWorks Device Management Configuration Guide (https://xchange.broadsoft.com/node/1031995).

CTI Interface and Related Configuration

The “inmost to outmost” configuration order is listed below. Following this order is not mandatory.

  1. Configure Application Server for CTI Subscriptions

  2. Configure XSPs for mTLS Authenticated CTI Subscriptions

  3. Open Inbound Ports for Secure CTI Interface

  4. Subscribe Your Webex Organization to BroadWorks CTI Events

Configure Application Server for CTI Subscriptions

Update the ClientIdentity on Application Server with the common name (CN) of the client certificate. If you are using a TLS-bridging proxy, it is the CN of the internally signed certificate that the proxy presents to the XSP. Otherwise, it is the CN of the Webex for BroadWorks CTI client certificate.

For each Application Server you are using with Webex, add the certificate identity to the ClientIdentity as follows:

AS_CLI/System/ClientIdentity> add bwcticlient.webex.com


The common name of the Webex for BroadWorks client certificate is bwcticlient.webex.com.

Configure TLS and Ciphers on the CTI Interface

The levels of configurability for the XSP CTI interface are as follows:

Most general = System > Transport > CTI Interfaces > CTI interface = Most specific

The CLI contexts you use to view or modify the different SSL settings are:

Specificity

CLI Context

System (global)

(R22 and later)

XSP_CLI/System/SSLCommonSettings/JSSE/Ciphers>

XSP_CLI/System/SSLCommonSettings/JSSE/Protocols>

Transport protocols for this system

(R22 and later)

XSP_CLI/System/SSLCommonSettings/OpenSSL/Ciphers>

XSP_CLI/System/SSLCommonSettings/OpenSSL/Protocols>

All CTI interfaces on this system

(R22 and later)

XSP_CLI/Interface/CTI/SSLCommonSettings/Ciphers>

XSP_CLI/Interface/CTI/SSLCommonSettings/Protocols>

A specific CTI interface on this system

(R22 and later)

XSP_CLI/Interface/CTI/SSLSettings/Ciphers>

XSP_CLI/Interface/CTI/SSLSettings/Protocols>

Reading CTI TLS Interface Configuration on the XSP

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/CTI/SSLSettings>

    On BroadWorks R21: navigate to XSP_CLI/Interface/CTI/SSLConfiguration>

  2. Enter the get command and read the results. You should see the interfaces (IP addresses) and, for each, whether they require a server certificate and whether they require client authentication.

Adding TLS 1.2 Protocol to the CTI Interface


This procedure applies to R22 and later. To configure the TLS version on the CTI interface for R21(SP1), you must use the tomcat container option bw.cti.sslenabledprotocols.

The XSP CTI interface that is interacting with the Cisco Webex cloud must be configured for TLS v1.2. The cloud does not negotiate earlier versions of the TLS protocol.

To configure the TLSv1.2 protocol on the CTI interface:

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/CTI/SSLSettings/Protocols>

  2. Enter the command get <interfaceIp> to see which protocols are already used on this interface.

  3. Enter the command add <interfaceIp> TLSv1.2 to ensure that interface can use TLS 1.2 when communicating with the cloud.

Editing TLS Ciphers Configuration on the CTI Interface


This procedure applies to R22 and later. To configure the ciphers on the CTI interface for R21(SP1), you must use the tomcat container option bw.cti.enabledciphers.

To configure the required ciphers on the CTI interface:

  1. Sign in to the XSP and navigate to XSP_CLI/Interface/CTI/SSLSettings/Ciphers>

  2. Enter the get command to see which ciphers are already used on this interface. There must be at least one from the Cisco recommended suites (see XSP Identity and Security Requirements in the Overview section).

  3. Enter the command add <interfaceIp> <cipherName> to add a cipher to the CTI interface.


    The XSP CLI requires the IANA standard cipher suite name, not the openSSL cipher suite name. For example, to add the openSSL cipher ECDHE-ECDSA-CHACHA20-POLY1305 to the CTI interface, you would use: XSP_CLI/Interface/CTI/SSLSettings/Ciphers> add 192.0.2.7 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

    See https://ciphersuite.info/ to find the suite by either name.

Update Trust Anchors for CTI Interface (R22 and later)

This procedure assumes the XSPs are either internet-facing or face the internet via pass-through proxy. The certificate configuration is different for a bridging proxy (see TLS Certificate Requirements for TLS-bridge Proxy).

For each XSP in your infrastructure that is publishing CTI events to Webex, do the following:

  1. Sign in to Partner Hub.

  2. Go to Settings > BroadWorks Calling and click Download Webex CA Certificate to get CombinedCertChain.txt on your local computer.


    This file contains two certificates. You need to split the file before you upload it to the XSPs.

  3. Split the certificate chain into two certificates:

    1. Open combinedcertchain.txt in a text editor.

    2. Select and cut the first block of text, including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, and paste the text block into a new file.

    3. Save the new file as broadcloudroot.txt.

    4. Save the original file as broadcloudissuing.txt.

      The original file should now only have one block of text, surrounded by the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  4. Copy both text files to a temporary location on the XSP you are securing, e.g. /tmp/broadcloudroot.txt and /tmp/broadcloudissuing.txt.

  5. Sign in to the XSP and navigate to /XSP_CLI/Interface/CTI/SSLCommonSettings/ClientAuthentication/Trusts>

  6. (Optional) Run help updateTrust to see the parameters and command format.

  7. Upload the certificate files to new trust anchors:

    XSP_CLI/Interface/CTI/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexroot /tmp/broadcloudroot.txt

    XSP_CLI/Interface/CTI/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexissuing /tmp/broadcloudissuing.txt


    webexroot and webexissuing are example aliases for the trust anchors; you can use your own.

  8. Confirm the anchors are updated:

    XSP_CLI/Interface/CTI/SSLCommonSettings/ClientAuthentication/Trusts> get

      Alias   Owner                                   Issuer
    =============================================================================
    webexissuing    BroadCloud Commercial Issuing CA – DA3     BroadCloud Commercial Trusted Root CA
    webexroot       BroadCloud Commercial Trusted Root CA      BroadCloud Commercial Trusted Root CA[self-signed]
  9. Allow clients to authenticate with certificates:

    XSP_CLI/System/CommunicationUtility/DefaultSettings/ExternalAuthentication/CertificateAuthentication> set allowClientApp true

Update Trust Anchors for CTI Interface (R21)

This procedure assumes the XSPs are either internet-facing or face the internet via pass-through proxy. The certificate configuration is different for a bridging proxy (see TLS Certificate Requirements for TLS-bridge Proxy).

For each XSP in your infrastructure that is publishing CTI events to Webex, do the following:

  1. Sign in to Partner Hub.

  2. Go to Settings > BroadWorks Calling and click Download Webex CA Certificate to get CombinedCertChain.txt on your local computer.


    This file contains two certificates. You need to split the file before you upload it to the XSPs.

  3. Split the certificate chain into two certificates:

    1. Open combinedcertchain.txt in a text editor.

    2. Select and cut the first block of text, including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, and paste the text block into a new file.

    3. Save the new file as broadcloudroot.txt.

    4. Save the original file as broadcloudissuing.txt.

      The original file should now only have one block of text, surrounded by the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  4. Copy both text files to a temporary location on the XSP you are securing, e.g. /tmp/broadcloudroot.txt and /tmp/broadcloudissuing.txt.

  5. Sign in to the XSP and navigate to /XSP_CLI/Interface/CTI/SSLConfiguration/ClientAuthentication/Trusts>

  6. (Optional) Run help updateTrust to see the parameters and command format.

  7. Update new trust anchors with the certificates:

    /XSP_CLI/Interface/CTI/SSLConfiguration/ClientAuthentication/Trusts> updateTrust webexroot /tmp/broadcloudroot.txt

    /XSP_CLI/Interface/CTI/SSLConfiguration/ClientAuthentication/Trusts> updateTrust webexissuing /tmp/broadcloudissuing.txt

    (where “webexroot” and "webexissuing" are example aliases for the trust anchors, you can choose your own)

  8. Confirm both certificates are uploaded:

    /XSP_CLI/Interface/CTI/SSLConfiguration/ClientAuthentication/Trusts> get

    XSP_CLI/Interface/CTI/SSLConfiguration/ClientAuthentication/Trusts> get
                 Alias                                   Owner                                           Issuer
    ===========================================================================================================
         webexissuing   BroadCloud Commercial Issuing CA - DA3 BroadCloud Commercial Trusted Root CA
            webexroot   BroadCloud Commercial Trusted Root CA  BroadCloud Commercial Trusted Root CA[self-signed]
  9. Allow clients to authenticate with certificates:

    XSP_CLI/System/CommunicationUtility/DefaultSettings/ExternalAuthentication/CertificateAuthentication> set allowClientApp true

Add CTI Interface and Enable mTLS

  1. Add the CTI SSL interface.

    The CLI context depends on your BroadWorks version. The command creates a self-signed server certificate on the interface, and forces the interface to require a client certificate.

    • On BroadWorks 22 and 23.0:

      XSP_CLI/Interface/CTI/SSLSettings> add <Interface IP> true true

    • On BroadWorks 21.sp1:

      XSP_CLI/Interface/CTI/SSLConfiguration> add <Interface IP> true true

  2. Enable and define the secure CTI port on XSPs:

    XSP_CLI/Interface/CTI> set securePortEnabled true

    XSP_CLI/Interface/CTI> set securePort 8012

  3. Replace the server certificate and key on the XSP's CTI interfaces. You need the IP address of the CTI interface for this; you can read it from the following context:

    • On BroadWorks 22 and 23.0:

      XSP_CLI/Interface/CTI/SSLSettings> get

    • On BroadWorks 21.sp1:

      XSP_CLI/Interface/CTI/SSLConfiguration> get

      Then run the following commands to replace the interface’s self-signed certificate with your own certificate and private key:

      On BroadWorks 22.0 and 23.0:

      XSP_CLI/Interface/CTI/SSLSettings/Certificates> sslUpdate <interface IP> keyFile </path/to/certificate key file>

      XSP_CLI/Interface/CTI/SSLSettings/Certificates> sslUpdate <interface IP> certificateFile </path/to/server certificate>

      On BroadWorks 21.sp1:

      XSP_CLI/Interface/CTI/SSLConfiguration> sslUpdate <interface IP> keyFile </path/to/certificate key file>

      XSP_CLI/Interface/CTI/SSLConfiguration> sslUpdate <interface IP> certificateFile </path/to/server certificate>

  4. Restart the XSP.

Open Inbound Ports for Secure CTI Interface

Open the secure port for CTI on your firewall (TCP 8012 by default) for an inbound TLS connection to your XSP CTI interface.

To check that the secure port is enabled, and its port number:

  1. Sign in to the XSP CLI and navigate to the XSP_CLI/Interface/CTI> context.

  2. Enter get.

Among other information, you should see the following:

securePortEnabled = true

securePort = 8012

This ensures that Webex can initiate an encrypted connection.

Webex only uses the secure port, so we recommend that you set portEnabled = false to disable the unsecured port.

Enable Access to BroadWorks CTI Events on Cisco Webex

You need to add and validate the CTI interface when you configure your clusters in Partner Hub. See Configure Your Partner Organization in Control Hub for detailed instructions.

  • Specify the CTI address by which Cisco Webex can subscribe to BroadWorks CTI Events.

  • CTI subscriptions are on a per-subscriber basis and are only established and maintained while that subscriber is provisioned for Webex for BroadWorks.

Call Settings Webview

Call Settings Webview (CSWV) is an application hosted on XSP (or ADP) to enable users to modify their BroadWorks call settings through a webview that they see in the soft client. There is a detailed CSWV Solution Guide at https://xchange.broadsoft.com/node/1050149.

Webex Teams makes use of this feature to provide users with access to common BroadWorks call settings that are not native to Webex Teams.

If you want your Webex for BroadWorks subscribers to access call settings beyond the defaults available in Webex Teams, you need to deploy Call Settings Webview feature.

Call Settings Webview has two components:

  • Call Settings Webview application, hosted on a Cisco BroadWorks XSP (or ADP).

  • Webex Teams, which renders the call settings in a Webview.

User Experience

  • Windows users: Click profile picture, then Settings > Calling > Self Care.

  • Mac users: Click profile picture, then Preferences > Calling > Self Care

Deploy CSWV on BroadWorks

Install Call Settings Webview on XSPs

CSWV application must be on the same XSP(s) that host the Xsi-Actions interface in your environment. It is an unmanaged application on XSP, so you need to install and deploy a web archive file.

  1. Sign in to Xchange and search for "BWCallSettingsWeb" in the software download section.

  2. Find and download the most recent version of the file.

    For example, BWCallSettingsWeb_1.7.5_1.war (https://xchange.broadsoft.com/node/1054451) was the most recent at the time of writing.

  3. Install, activate, and deploy the web archive according to the Xtended Service Platform Configuration Guide for your XSP version. (R23 version is https://xchange.broadsoft.com/node/1033484).

    1. Copy the .war file to a temporary location on the XSP, such as /tmp/.

    2. Navigate to the following CLI context and run the install command:

      XSP_CLI/Maintenance/ManagedObjects> install application /tmp/BWCallSettingsWeb_1.7.5_1.war

      The BroadWorks software manager validates and installs the file.

    3. [Optional] Delete /tmp/BWCallSettingsWeb_1.7.5_1.war (this file is no longer required).

    4. Activate the application:

      XSP_CLI/Maintenance/ManagedObjects> activate application BWCallSettingsWeb 1.7.5 /callsettings

      The name and version are mandatory for any application, but for CSWV you must also provide a contextPath because it is an unmanaged application. You can use any value that is not used by another application, for example, /callsettings.

    5. Deploy the Call Settings application on the selected context path:

      XSP_CLI/Maintenance/ManagedObjects> deploy application /callsettings

  4. You can now predict the call settings URL that you will specify for clients, as follows:

    https://<XSP-FQDN>/callsettings/

    Notes:

    • You must supply the trailing slash on this URL when you enter it in the client configuration file.

    • The XSP-FQDN must match the Xsi-Actions FQDN, because CSWV needs to use Xsi-Actions, and CORS is not supported.

  5. Repeat this procedure for other XSPs in your Webex for BroadWorks environment (if necessary)

The Call Settings Webview application is now active on the XSPs.

Additional Configuration for XSP R21

If you're deploying the CSWV application on an R21 XSP:

  1. Navigate to the call settings application context and run get to read its configuration: XSP_CLI/Applications/BWCallSettingsWeb_1.7.5/General> get

    You should see the following parameters and values:

    xsiActionsContextOrURL=/com.broadsoft.xsi-actions
    displayCriteriaOrScheduleName=criteria
    applicationMode=prod
    
  2. Use set (if necessary) to change the parameters to the values shown above.

  3. Repeat for other R21 XSPs if necessary.

Configure Webex Teams to Use Call Settings Webview

For more detail on client configuration, see Webex Teams for BroadWorks Client Configuration Guide on Xchange for your Webex Teams version. For example, the September 2020 version of this file is at https://xchange.broadsoft.com/node/1054075

There's a custom tag in the Webex Teams configuration file that you can use to set the CSWV URL. This URL shows the call settings to the users through the application's interface.

<config>
    <services>
        <web-call-settings target="%WEB_CALL_SETTINGS_TARGET_WXT%">
            <url>%WEB_CALL_SETTINGS_URL_WXT%</url>
        </web-call-settings>

In the Webex Teams configuration template on BroadWorks, configure the CSWV URL in the %WEB_CALL_SETTINGS_URL_WXT% tag.

If you do not explicitly specify the URL, the default is empty and the call settings page is not visible to the users.

  1. Make sure you have the latest configuration templates for Webex Teams (see Device Profiles).

  2. Set the Web Call Settings Target to csw:

    %WEB_CALL_SETTINGS_TARGET_WXT% csw

  3. Set the Web Call Settings URL for your environment, for example:

    %WEB_CALL_SETTINGS_URL_WXT% https://yourxsp.example.com/callsettings/

    (You derived this value when deploying the CSWV application)

  4. The resulting client configuration file should have an entry as follows:
    <web-call-settings target="csw">
        <url>https://yourxsp.example.com/callsettings/</url>
    </web-call-settings>

Configure Call Push Notifications From Your Network

In this document we use the term Call Notifications Push Server (CNPS) to describe an XSP-hosted application that runs in your environment. Your CNPS works with your BroadWorks system to be aware of incoming calls to your users, and pushes notifications of those to the Google Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs) notification services.

Those services notify the mobile devices of Webex for BroadWorks subscribers that they have incoming calls on Webex Teams.

For more information about NPS, see https://xchange.broadsoft.com/node/485737.

A similar mechanism in Webex works with Webex messaging and presence services to push notifications to the Google (FCM) or Apple (APNS) notification services. Those services in turn notify the mobile Teams users of incoming messages or presence changes.

NPS Proxy Overview

For compatibility with Webex for BroadWorks, your CNPS has to 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 the run-time branded 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 Webex for BroadWorks 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.

The BroadWorks patches for the feature are available on Xchange: https://xchange.broadsoft.com/node/1046235

For more information, see the Push Server for VoIP in UCaaS Feature Description on Xchange: https://xchange.broadsoft.com/node/1045458

Considerations for Existing NPS to be Used with Webex for BroadWorks

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

  • You must not change from GCM API to FCM v1 API before you have the NPS Proxy configured. You must only change over while configuring NPS to use NPS Proxy.

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

Configure your NPS to Work with the NPS Proxy

Prerequisite: XSP R22 or later, with NPS activated. Patched with https://xchange.broadsoft.com/node/1046235

  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.

    You’ll get the OAuth client ID, client secret, and a refresh token that is valid for 60 days from Cisco. If the token expires before you use it with your NPS, you can raise another request.

  2. 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

  3. 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 client-Secret-From-Step1

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

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

    • Webex Teams for Android: com.cisco.wx2.android

    • Android UC-One/SAAS: com.broadsoft.connect

    XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add applicationId com.cisco.wx2.android

  5. (For Android notifications) Enable the FCM v1 API on the NPS.

    XSP_CLI/Applications/NotificationPushServer/FCM> set V1Enabled true


    This step can be performed prior to configuring the NPS Proxy, but only if you are not already using this NPS for UC-One. You can set V1enabled false to revert to using the GCM API key.

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

    • Webex Teams iOS:XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> add com.cisco.squared

    • iOS UC-One/SAAS: XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens>add com.broadsoft.uc-one

  7. Restart the XSP:

    bwrestart

  8. Test call notifications by making calls from a BroadWorks subscriber to two Teams mobile users. Verify that call notification appears on iOS and Android devices.

Migrating from FCM to FCMv1

The XSP-to-host NPS must meet the following requirements:

  • There is only one NPS app in a deployment. If you're using Mobile Collaborate/Connect and or SaaS implementing Webex for BroadWorks, you must share this single NPS app.

  • We recommend that the NPS be on a dedicated XSP/ADP and that the NPS is the only NPS app on the XSP, to eliminate interference with the delivery of Push notifications.

  • More information on the new ADP server can be found on the Application Delivery Platform.

IOS HTTP/2 Support

  • You must be on r22+ or r23 XSP. An r22 / r23 XSP is compatible to run in parallel with an r21 stack if the XSP only runs NPS and the AS is r21.sp1. See the BroadWorks Compatibility Matrix for more information.

  • If you have deployed any iOS apps non-Cisco/BroadSoft, those apps must be configured to use the HTTP/2 APNS protocol.

  • XSP/ADPs that already support the Collaborate or SaaS BroadWorks app need to be migrated to HTTP/2. For instructions, see HTTP/2 Support to Notification Push Server for APNS.

  • Additional steps for HTTP2 for SaaS clients:

    1. Login to your BAM portal.

    2. Select Configuration > BroadWorks.

    3. In the Notification Push Server section, select Release 22 in the drop-down menu, then follow the instructions.

Android FCMv1 /HTTPv1

  • If you have deployed any Android apps Non-Cisco/BroadSoft, those apps must be configured to use the FCMv1 keys.

  • If the XSP/ADP currently supports the Connect or UC-One SaaS app, then FCMv1 keys cannot be enabled prior to the next step in the XSP/ADP configuration. 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.

Install the following required patches:

R22

  • AP.xsp.22.0.1123.ap369607

  • AP.platform.22.0.1123.ap369607

  • AP.xsp.22.0.1123.ap374677

  • AP.xsp.22.0.1123.ap375206

R23

  • AP.xsp.23.0.1075.ap369607

  • AP.platform.23.0.1075.ap369607

  • AP.xsp.23.0.1075.ap374677

  • AP.xsp.23.0.1075.ap375206

XSP Setup

Important: If the XSP/ADP is already supporting the Android UC-One SaaS or Connect clients, then FCMv1 keys must only be enabled during this process. If the XSP/ADP does not already support these clients, then FCMv1 keys can be enabled before completing the steps below.

Once you complete all of the steps in Migrating from FCM to FCMv1 above, complete the steps below using the OAuth client ID, client secret, and a refresh token provided to you by Cisco.

Note the following:

  • Steps 1 – 3 can be done without affecting any existing setups.

  • Step 4 can be done before this setup if the UC-One SaaS or Connect client is not supported on the XSP; otherwise, it must be done during this setup (see Important note above about FCMv1 keys).

  • Step 5 must be done during this setup. It cannot be done beforehand.

  1. Set the CI OAuth client information as sent to you by Cisco:

    XSP_CLI/Applications/NotificationPushServer/CiscoCI/Client> get
    clientId = ******
    clientSecret = ******
    refreshToken = ******
  2. Set the UCaaS cloud URL. The staging FQDN is nps.stage.broadsoft.cloud, and production is is nps.uc-one.broadsoft.com.

    XSP_CLI/Applications/NotificationPushServer/CloudNPSService> get
    url = https://<ucaas_fqdn>/nps/
    VOIPTokenRefreshInterval = 1800
  3. Add the appropriate Android clients to FCM, depending on whether the service provider will be using the UC-One client, the Webex client, or both.

    Android UC-One/SAAS: com.broadsoft.connect
    Android WebEx Teams: com.cisco.wx2.android
    
    Example:
    XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add com.cisco.wx2.android
    ...Done
  4. Enable the FCM v1 keys.

    XSP_CLI/Applications/NotificationPushServer/FCM> set V1Enabled true
  5. Verify the Timers and Timeouts values are as shown below; if not, make the necessary changes.

    XSP_CLI/Applications/NotificationPushServer/FCM> get
    tokenTimeToLiveInSeconds = 3600
    connectionPoolSize = 10
    connectionTimeoutInMilliseconds = 3000
    connectionIdleTimeoutInSeconds = 600
  6. Verify the URLs are as listed:

    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
  7. For iOS, ensure the appropriate apps (UC-One and/or Webex Teams) do not have auth keys associated with them.

    iOS UC-One/SAAS: com.broadsoft.uc-one
    iOS WebEx Teams: com.cisco.squared
    
    
    XSP_CLI/Applications/NotificationPushServer/APNS/Production/Tokens> get
                                        App Id  Auth Key Id
    =======================================================
                             com.cisco.squared
         com.broadsoft.enterprise.uc-one-teams   D36WVNTQHD
                        com.cisco.webexcalling   CJYT2F4FXN
  8. Restart XSP by executing the bwrestart command, and test to verify functionality. If everything works correctly, the FCM/GCM API key for the SaaS Android app and the older APNS key for the SaaS iOS app can be removed from the box.

Google PUSH config for Webex for Broadworks FCMv1, and/or Migrating UC Legacy Apps to FCMv1

All legacy apps, such as Connect, must be migrated to FCM HTTPv1 (oauth) keys. Complete the following steps to migrate an existing FCM application on HTTP keys (basic auth) to HTTPv1.


These steps are not required for clients using just Webex for BroadWorks.

  1. Log in to the FCM Admin SDK at console.firebase.google.com

  2. Select the appopriate Android application.

  3. In the General tab, note the project ID.

  4. Select the Service Accounts tab.

    To create a new service account:

    1. To create a new service account, click Create New Service Account.

    2. Click Create a New Private Key.

    3. Download the key to a secure location.

    To update an existing service account:

    1. Click View Existing Service Accounts.

    2. Identify the service account to use, then in the menu on the right, select Create a New Private Key.

    3. Download the key to a secure location.

  5. Copy the key to the XSP.

  6. Configure the project ID and key:

    XSP_CLI/Applications/NotificationPushServer/FCM/Projects> add <project id> <path/to/key/file>
    ...Done
    
    
    XSP_CLI/Applications/NotificationPushServer/FCM/Projects> get
      Project ID  Accountkey
    ========================
      my_project    ********
  7. Configure the application:

    XSP_CLI/Applications/NotificationPushServer/FCM/Applications> add <app id> projectId <project id> ...Done XSP_CLI/Applications/NotificationPushServer/FCM/Applications> get Application ID Project ID ============================== my_app my_project
  8. Enable FCM HTTPv1:

    XSP_CLI/Applications/NotificationPushServer/FCM> set V1Enabled true
    ...Done
  9. Restart XSP by executing the bwrestart command.

  10. If XSP also provides call PNs for UC-One SaaS, then validate and disable FCM HTTPv1 keys until the UC-One app is added later on this guide.

Connect SaaS Clients

If you were using GCM with your CNPS, then you need to reconfigure your CNPS to use FCM.

For more information, see the Communicator (Android) Migration to Firebase Method of Procedure at https://xchange.broadsoft.com/node/499312.

The GCM and FCM APIs are compatible. Complete the following steps:

  1. Set the FCM URL for your push notification messages. The old URL is https://gcm-http.googleapis.com/gcm/send and the new one is https://fcm.googleapis.com/fcm/send.

    You can change this by issuing the following command:

    XSP_CLI/Applications/NotificationPushServer/GCM> set url https://fcm.googleapis.com/fcm/send

  2. Restart the XSP.

Configure Your Partner Organization in Control Hub

Configure Your BroadWorks Clusters

[once per cluster]

This is done for the following reasons:

  • To enable Webex cloud to authenticate your users against BroadWorks (via XSP-hosted authentication service).

  • To enable Webex Teams clients to use Xsi interface for call control.

  • To enable Webex to listen for CTI events published by BroadWorks (telephony presence).


The cluster wizard automatically validates the interfaces as you add them. You can continue editing the cluster if any of the interfaces do not validate successfully, but you cannot save a cluster if there are invalid entries.

We prevent this because a misconfigured cluster could cause issues that are difficult to solve.

What you need to do:

  1. Sign in to Partner Hub (admin.webex.com) with your partner administrator credentials.

  2. Open Settings page from the side menu, and find BroadWorks Calling settings.

  3. Click Add Cluster.

    This launches a wizard where you supply your XSP interfaces (URLs). You can add a port to the interface URL if you are using a non-standard port.

  4. Name this cluster and click Next.

    The cluster concept here is simply a collection of interfaces, typically collocated on an XSP server or farm, that enable Webex to read information from your Application Server (AS). You may have one XSP per AS cluster, or multiple XSPs per cluster, or multiple AS clusters per XSP. Scale requirements for your BroadWorks system are out of scope here.

  5. Add your XSI Actions and XSI Events URLs and click Next.

  6. Add your CTI Interface URL and click Next.

  7. Add your Authentication Service URL.

  8. Review your entries on the final screen, and then click Create. You should see a success message.

    Partner Hub passes the URLs to various Webex microservices that test the connections to the supplied interfaces.

  9. Click View Clusters and you should see your new cluster, and whether the validation succeeded.

Testing the Connections to Your BroadWorks Interfaces

  1. Sign in to Partner Hub (admin.webex.com) with your partner administrator credentials.

  2. Open Settings page from the side menu, and find BroadWorks Calling settings.

  3. Click View Clusters.

  4. Partner Hub initiates connectivity tests from the various microservices towards the interfaces in the clusters.

    After the tests complete, the cluster list page shows status message next to each cluster.

    You should see green Success messages. If you see a red Error message, click the affected cluster name to see which setting is causing the problem. For example, if the connection to the Authentication Service failed, check that you correctly configured the XSPs for mTLS authentication and uploaded the Webex Certificate Chain to the trust store of the XSP interface.

Configure your Customer Templates

Customer templates are the way that you will apply shared configuration to one or more customers. You must associate each template with a cluster (that you created in previous section).

You can create as many templates as you need.

  1. Sign in to Partner Hub (admin.webex.com) with your partner administrator credentials.

  2. Open Settings page from the side menu, and find BroadWorks Calling settings.

  3. Click Add Template.

    This launches a wizard where you can supply configuration for customers that will use this template.

  4. Use the dropdown, or start typing, to choose the cluster you want to use with this template.

  5. Enter a name for the template, then click Next.

  6. Configure your provisioning mode, using these recommended settings:

    Table 1. Recommended Template Settings for Different Provisioning Modes

    Setting Name

    Flowthrough provisioning with trusted emails

    Flowthrough provisioning without emails

    User self-provisioning

    Enable BroadWorks Flow Through Provisioning (includes provisioning account credentials if On)

    On

    Supply the provisioning Account Name and Password as per BroadWorks configuration.

    On

    Supply the provisioning Account Name and Password as per BroadWorks configuration.

    Off

    Automatically Create New Organizations in Control Hub

    On

    On

    On

    User Verification

    Trust Broadworks emails

    Untrusted Emails

    Untrusted Emails

    First user provisioned is admin

    Recommended*

    Recommended*

    Not applicable

    Allow users to self activate

    Not applicable

    Not applicable

    Required

    • Notes from the table:

    • † This switch ensures that a new customer organization is created if a subscriber’s email domain does not match an existing Webex organization.

      This should always be on, unless you are using a manual ordering and fulfilment process (via Cisco Commerce Workspace) to create customer organizations in Webex (before you start provisioning users in those organizations). That option is often referred to as the "Hybrid Provisioning" model, and is out of the scope of this document.

    • * The first user to whom you assign Integrated IM&P in BroadWorks takes the customer administrator role if a new customer organization is created in Webex. Choose this setting to give you some control over who takes the role. If you uncheck this setting, then the first user to become active in the new organization becomes the customer administrator.

      You can modify the customer user roles in Partner Hub after provisioning, if necessary.

  7. Enable BroadWorks Enterprise Mode if the customers you provision with this template are enterprises in BroadWorks. If they are groups, leave this switch off.

    If you have a mix of enterprises and groups in your BroadWorks, you should create different templates for those different cases.

  8. Choose which country you use for this template.

    The country you choose matches customer organizations that are created with this template to a particular region. At present, the region could be (EMEAR) or (North America and rest of world). See the country to region mappings in this spreadsheet.

  9. Select the default services package for customers using this template (see Packages in the Overview section); either Basic, Standard, or Premium.

  10. Select the default authentication mode (either BroadWorks Authentication or Webex Authentication) for customers using this template (see Authentication Mode in the Prepare your Environment section).

  11. Select your Service Provider Email Address from the dropdown (you can type some characters in a search box, to find the address if there is a long list).

    This email address identifies the administrator within your Partner organization who will be granted delegated admin access to any new customer organizations created with the customer template.

  12. Choose whether you want the email address to be pre-filled on the login page.

    You should only use this option if you selected BroadWorks Authentication and have also have put the users’ email addresses in the Alternate ID attribute in BroadWorks. Otherwise, they will need to use their BroadWorks username. The login page gives an option to change user, if necessary, but this may lead to login issues.

  13. Enter a Service Provider Brand Name.

    This name is used in the automated email message from Webex, that invites users to validate their email addresses.

  14. Review your entries on the final screen. You can click the navigation controls at the top of the wizard to go back and change any details. Click Create.

    You should see a success message.

  15. Click View Templates and you should see your new template listed with any other templates.

  16. Click the template name to modify or delete the template, if necessary.

    You do not need to re-enter the provisioning account details. The empty password/password confirm fields are there to change the credentials if you need to, but leave them empty to keep the values you gave to the wizard.

  17. Add more templates if you have different shared configurations you want to provide to customers.


    Keep the View Templates page open, as you need template details for a following task.

Configure Application Server with Provisioning Service URL


This task is only required for flow through provisioning.

Patch Application Server

  1. Apply the patch ap373197 (See BroadWorks Software Requirements in the Reference section).

  2. Change to the Maintenance/ContainerOptions context.

  3. Enable the provisioning URL parameter:

    /AS_CLI/Maintenance/ContainerOptions> add provisioning bw.imp.useProvisioningUrl true

Get the Provisioning URL(s) from Partner Hub

Refer to the Cisco BroadWorks Application Server Command Line Interface Administration Guide for details (Interface > Messaging and Service > Integrated IM&P) of the AS commands.

  1. Sign in to Partner Hub and go to Settings > BroadWorks Calling.

  2. Click View Templates.

  3. Select the template you’re using to provision this enterprise/group’s subscribers in Webex.

    The template details display in a flyout pane on the right. If you haven’t yet created a template, you need to do that before you can get the provisioning URL.

  4. Copy the Provisioning Adapter URL.

Repeat this for other templates if you have more than one.

(Option) Configure System-Wide Provisioning Parameters on Application Server


You may not want to set system-wide provisioning and service domain if you are using UC-One SaaS. See Decision Points in the Prepare your Environment section.

  1. Sign in to the Application Server and configure the messaging interface.

    1. AS_CLI/Interface/Messaging> set provisioningUrl EnterValueFromPartnerHubTemplate

    2. AS_CLI/Interface/Messaging> set provisioningUserId EnterValueFromPartnerHubTemplate

    3. AS_CLI/Interface/Messaging> set provisioningPassword EnterValueFromPartnerHubTemplate

    4. AS_CLI/Interface/Messaging> set enableSynchronization true

  2. Activate the Integrated IMP interface:

    1. /AS_CLI/Service/IntegratedIMP> set serviceDomain example.com

    2. /AS_CLI/Service/IntegratedIMP/DefaultAttribute> set userAttrIsActive true


You must enter the fully qualified name for the provisioningURL parameter, as it was given in Control Hub. If your Application Server cannot access DNS to resolve the hostname, then you must create the mapping in the /etc/hosts file on the AS.

(Option) Configure Per-Enterprise Provisioning Parameters on Application Server

  1. In BroadWorks UI, open the enterprise you want to configure, and go to Services > Integrated IM&P.

  2. Select Use service domain and enter a dummy value (Webex ignores this parameter. You could use example.com).

  3. Select Use Messaging Server.

  4. In the URL field, paste the provisioning URL you copied from your template in Partner Hub.


    You must enter the fully qualified name for the provisioningURL parameter, as it was given in Partner Hub. If your Application Server cannot access DNS to resolve the hostname, then you must create the mapping in the /etc/hosts file on the AS.

  5. In the Username field, enter a name for the provisioning administrator. This must match the value on the template in Partner Hub.

  6. Enter a password for the provisioning administrator. This must match the value on the template in Partner Hub.

  7. For Default User Identity for IM&P ID, select Primary.

  8. Click Apply.

  9. Repeat for other enterprises you want to configure for flow through provisioning.

Customize and Provision Clients

Users download and install their generic Webex Teams clients, for desktop or mobile (see Teams Client Platforms in the Prepare Your Environment section). Once the user authenticates, the client registers against the Cisco Webex cloud for messaging and meetings, retrieves its branding info, discovers its BroadWorks service info and downloads its calling configuration from BroadWorks Application Server (via DMS on XSP).

You configure the calling parameters for Webex Teams clients in BroadWorks (as normal). You configure branding, messaging, and meeting parameters for the clients in Control Hub. You do not directly modify a configuration file.

These two sets of configurations can overlap, in which case the Webex configuration supersedes the BroadWorks configuration.

Add Webex Teams Configuration Templates to BroadWorks Application Server

Webex Teams clients are configured with DTAF files. The clients download a configuration XML file from the Application Server, via the Device Management service on the XSP.

  1. Get the required DTAF files (see Device Profiles in the Prepare Your Environment section).

  2. Check that you have the right tag sets in BroadWorks System > Resources > Device Management Tag Sets.

  3. For each client you're provisioning:

    1. Download and extract the DTAF zip file for the particular client.

    2. Import DTAF files to BroadWorks at System > Resources > Identity/Device Profile Types

    3. Open the newly added device profile for editing and enter the XSP farm FQDN and Device Access Protocol.

    4. Modify the templates according to your environment (see table below).

    5. Save the profile.

  4. Click Files and Authentication and then select the option to rebuild all system files.

Name

Description

Codec Priority

Configure priority order for the audio and video codecs for VoIP calls

TCP, UDP and TLS

Configure the protocols used for SIP signaling and media

RTP Audio and Video Ports

Configure port ranges for RTP audio and video

SIP options

Configure various options related to SIP (SIP INFO, use rport, SIP proxy discovery, refresh intervals for registration and subscription, etc.)

Customize Clients in Control Hub

There are separate branding configurations for desktop and mobile clients, so you must repeat this branding process if using both:

  1. Sign in to Control Hub and go to Configuration > Clients.

  2. Locate the Branding area of the client configuration page.

  3. Update logo and primary navigation bar color. For more information, see Add Your Company Branding to Webex Teams.


The User Activation Portal uses the same logo you add for Client Branding.

Customize Problem Reporting and Help URLs

See https://help.webex.com/n0cswhcb “Customize Branding and Problem Reporting for Customers”.

Configure Your Test Organization for Webex for BroadWorks

Before you begin

With Flowthrough Provisioning

You must configure all the XSP services, and the partner organization in Control Hub, before you can perform this task.

1

Assign Service in BroadWorks:

  1. Create a test enterprise under your service provider enterprise in BroadWorks, or create a test group under your Service Provider (depends on your BroadWorks setup).

  2. Configure the IM&P service for that enterprise, to point to the template you are testing (retrieve the provisioning adapter URL and credentials from Control Hub customer template).

  3. Create test subscribers in that enterprise / group.

  4. Give the users unique email addresses in the email field in BroadWorks. Copy those into the Alternate ID attribute as well.

  5. Assign the Integrated IM&P service to those subscribers.


     

    This triggers the creation of the customer organization and the first users, which takes several minutes. Please wait a little while before trying to sign in with your new users.

2

Verify Customer Organization and Users in Control Hub:

  1. Sign in to Control Hub with your partner administrator account.

  2. Go to Customers and verify that your new customer organization is in the list (name follows the group name or enterprise name, from BroadWorks).

  3. Open the customer organization and verify that the subscribers are users in that organization.

  4. Verify that the first subscriber to whom you assigned the Integrated IM&P service has become the customer administrator of that organization.

User Testing

1

Download the Webex Teams client on two different machines.

2

Sign in as your test users on the two machines.

3

Make test calls.