Prepare Your Environment

Decision Points

Consideration Questions to answer Resources

Architecture & Infrastructure

How many XSPs?

How do they take mTLS?

Cisco BroadWorks System Capacity Planner

Cisco BroadWorks System Engineering Guide

XSP CLI Reference

This document

Customer and user provisioning

Can you assert that you trust emails in BroadWorks?

Can you build tools to use our API?

Public API docs

This document

Branding What color and logo do you want to use? Teams branding article
Templates What are your different customer use cases? This document
Subscriber Features per customer/enterprise/group Choose package to define level of service per template. Basic, Standard, Premium

This document

Feature/package matrix

User authentication BroadWorks, or Webex This document
Provisioning adapter

Do you already use Integrated IM&P, eg for UC-One SaaS?

Do you intend to use multiple templates?

Is there a more common use case anticipated?

This document

Application Server CLI reference

Architecture & Infrastructure

  • What kind of scale do you intend to start with? It is possible to scale up in future, but your current usage estimate should drive infrastructure planning.

  • Work with your Cisco account manager / sales representative to size your XSP infrastructure, according to the Cisco BroadWorks System Capacity Planner (https://xchange.broadsoft.com/node/473873) and theCisco BroadWorks System Engineering Guide (https://xchange.broadsoft.com/node/422649).

  • How will Cisco Webex make Mutual TLS connections to your XSPs? Directly to the XSP in a DMZ, or via TLS proxy? This affects your certificate management, and the URLs you use for the interfaces. (We do not support unencrypted TCP connections to the edge of your network).

Customer and User Provisioning

Use APIs or flowthrough provisioning?

  • SP Controlled Provisioning via APIs: Cisco Webex expose a set of Public APIs that allow Service Providers to build user/subscriber provisioning into their existing workflows.

  • Flowthrough Provisioning: By assigning the “Integrated IM&P” service on BroadWorks, the subscriber is automatically provisioned on Cisco Webex.

Email Address is a key user attribute on Cisco Webex. Therefore the Service Provider must supply a valid email address for the user in order to provision them for Cisco Webex services. This must be in the user’s Email ID attribute in BroadWorks. We recommend that you copy it into the Alternate ID attribute as well.

Branding

You can apply a logo and a single color (for the navigation bar) to the Webex Teams client. The User Activation Portal uses the same settings.

Customer Templates

Customer Templates allow you to define the parameters by which customer and associated subscribers are automatically provisioned on Cisco Webex for BroadWorks.You may configure multiple Customer Templates as required. Some of the primary parameters are listed below.

Package

  • If leveraging Flowthrough Provisioning, the package applies to all subscribers using a particular provisioning adapter. You have some control over this by using multiple templates, and setting the provisioning URL on a per enterprise basis.

  • You can change the package of specific subscribers from this default, using the provisioning API (see Integrating with Webex for BroadWorks Provisioning API in the Reference section).

  • See Packages in the Overview section for details.

  • You cannot change a subscriber’s package from BroadWorks. The assignment of the Integrated IM&P service is either on or off; if the subscriber is assigned this service in BroadWorks, the Control Hub template associated with that subscriber’s enterprise’s provisioning URL defines the package.

Reseller and Enterprises or Service Provider and Groups?

  • The way your BroadWorks system is configured has an impact on flow through provisioning. If you are a reseller with Enterprises, then you need to enable Enterprise mode when you create a template.
  • If your BroadWorks system is configured in Service Provider mode, you can leave the Enterprise mode switch off in your templates.
  • If you plan to provision customer organizations using both BroadWorks modes, you must use different templates for groups and enterprises.

Authentication Mode

How will customers’ subscribers authenticate?

Authentication Mode BroadWorks Webex
Primary user identity BroadWorks user ID Email address
Identity Provider

BroadWorks.

Authentication is facilitated by an intermediary service hosted by Cisco Webex.

Cisco Common Identity
Multi-factor authentication? No Requires Customer IdP that supports multi-factor authentication.

Credential validation path

  1. Browser is launched where user supplies email to initial login flow and discover their authentication mode.

  2. Browser is then redirected to a Cisco Webex hosted BroadWorks login page (This page is brandable)

  3. User supplies BroadWorks user id and password on the login page.

  4. User credentials are validated against BroadWorks.

  5. On success, an authorization code is obtained from Cisco Webex. This is used to obtained necessary access tokens for Cisco Webex services.

  1. Browser is launched where user supplies email to initial login flow and discover their authentication mode.

  2. Browser is redirect to IdP (either Cisco Common Identity or Customer IdP) where they will be presented with a login portal.

  3. User supplies appropriate credentials on login page

  4. Multi-factor Authentication may take place if the Customer IdP supports this.

  5. On success, an authorization code is obtained from Cisco Webex. This is used to obtained necessary access tokens for Cisco Webex services.

Multiple Partner Arrangements

Are you going to sub-license Webex for BroadWorks to another service provider? In this case, each service provider will need a distinct partner organization in Webex Control Hub to allow them provision the solution for their customer base.

Provisioning Adapter and Templates

When you are using flowthrough provisioning, the provisioning URL that you enter in BroadWorks is derived from the template in Control Hub. You can have multiple templates, and therefore multiple provisioning URLs. This enables you to select, on an enterprise by enterprise basis, which package to apply to subscribers when they are granted the Integrated IM&P service.

You need to consider whether you want to set a system level provisioning URL as a default provisioning path, and which template you want to use for that. This way, you only need to explicitly set the provisioning URL for those enterprises that need a different template.

Also, bear in mind that you may already be using a system level provisioning URL, for example with UC-One SaaS. If that is the case, you may opt to preserve the system level URL for provisioning users on UC-One SaaS, and override for those enterprises moving to Webex for BroadWorks. Alternatively, you may want to go the other way and set the system level URL for Webex for BroadWorks, and reconfigure those enterprises you want to keep on UC-One SaaS.

The configuration choices related to this decision are detailed in Configure Application Server with Provisioning Service URL in the Deploy Webex for BroadWorks section.

Minimum Requirements

Accounts

Webex uses email addresses as primary identifiers for all users. Your enterprise admin and group admin users must have valid addresses in the email attribute in BroadWorks. We recommend that you also copy the addresses into the Alternate ID attributes in BroadWorks. This makes it possible for the admins to sign into Control Hub using their email addresses and their BroadWorks passwords.

Servers in Your Network and Software Requirements

  • BroadWorks instance(s) with minimum version R21 SP1. See BroadWorks Software Requirements (in this document) for supported versions and patches. See also Lifecycle Management - BroadSoft Servers.


    R21 SP1 is only supported until mid-2021. Even though you can currently integrate Webex with R21 SP1, we strongly recommend R22 or later for integration with Webex.

  • The BroadWorks instance(s) should include at least the following servers:

    • Application Server (AS) with BroadWorks version as above

    • Network Server (NS)

    • Profile Server (PS)

  • Public-facing XSP Server(s)meeting the following requirements:

    • Authentication service (BWAuth)

    • XSI actions and events interfaces

    • DMS (device management web application)

    • TLS 1.2 with a valid certificate (not self-signed) and any intermediates required. Requires System Level Admin to facilitate enterprise lookup.

    • Mutual TLS (mTLS) authentication for Authentication Service (Requires the public Cisco Webex client certificate chain installed as a trust anchor on the public XSP)

  • A separate XSP server acting as a “Call Notifications Push Server” (an NPS in your environment used to push call notifications to Apple/Google. We call it “CNPS” here to distinguish it from the service in Webex that deliver push notifications for messaging and presence).

  • We mandate a separate XSP server for CNPS because the unpredictability of the load from Webex for BWKS cloud connections could negatively impact the performance of the NPS server, with the result of increasing notification latency. See the Cisco BroadWorks System Engineering Guide (https://xchange.broadsoft.com/node/422649) for more on XSP scale.

Physical Phones and Accessories

Device Profiles

These are the DTAF files you need to load onto your Application Servers to support Webex Teams as calling clients. They are the same DTAF files as used for UC-One SaaS, however there is a new config-wxt.xml.template file that is used for Webex Teams.

Client Name Device Profile Type and Package name

Webex Teams Mobile Template

https://xchange.broadsoft.com/support/uc-one/connect/software

Identity/Device Profile Type: Connect - Mobile

DTAF: ucone-mobile-ucaas_DTAF-#.#.#.###.zip

Config file: config-wxt.xml

Webex Teams Desktop Template

From https://xchange.broadsoft.com/support/uc-one/communicator/software

Identity/Device Profile Type: Business Communicator - PC

DTAF: ucone-desktop-ucaas_DTAF-#.#.#.###.zip

Config file: config-wxt.xml

Order Certificates

Certificate Requirements for TLS Authentication

You will need Security Certificates, signed by a well-known Certificate Authority and deployed on your Public facing XSPs, for all required applications. These will be used to support TLS certificate verification for all inbound connectivity to your XSP servers.

These certificates should include your XSP public fully qualified domain name as Subject Common Name or Subject Alternate Name.

The exact requirements for deploying these server certificates depends on how your public facing XSPs are deployed:

  • Via a TLS bridging proxy

  • Via a TLS pass-through proxy

  • Directly to the XSP

The following diagram summarizes where the CA-signed public server certificate needs to be loaded in these three cases:

The publicly supported CAs that Webex Teams supports for authentication are listed in Supported Certificate Authorities for Cisco Webex Hybrid Services.

TLS Certificate Requirements for TLS-bridge Proxy

  • The publicly signed server certificate is loaded into the proxy.

  • The proxy presents this publicly signed server certificate to Webex.

  • Webex trusts the public CA that signed the proxy’s server certificate.

  • An internal CA signed certificate can be loaded onto the XSP.

  • The XSP presents this internally signed server certificate to the proxy.

  • The proxy trusts the internal CA that signed the XSP server certificate.

TLS Certificate Requirements for TLS-passthrough Proxy or XSP in DMZ

  • The publicly signed server certificate is loaded into the XSPs.

  • The XSPs present publicly signed server certificates to Webex.

  • Webex trusts the public CA that signed the XSPs’ server certificates.

Additional Certificate Requirements for Mutual TLS Authentication against AuthService

Cisco Webex interacts with the Authentication Service over a mutual TLS authenticated connection. This means Webex presents a client certificate and the XSP must validate it. In order to trust this certificate, use the Webex CA certificate chain to create a trust anchor on XSP (or proxy). The certificate chain is available for download via Partner Hub:

  1. Go to Settings > BroadWorks Calling > View Clusters.

  2. Select your configured BroadWorks Calling Cluster.

  3. Click the download certificate link.


You can also get the certificate chain from https://bwks-uap.webex.com/assets/public/CombinedCertChain.txt.

The exact requirements for deploying this Webex CA certificate chain depends on how your public facing XSPs are deployed:

  • Via a TLS bridging proxy

  • Via a TLS pass-through proxy

  • Directly to the XSP

The following diagram summarizes where the Webex CA certificate chain must be deployed in these three cases.

Mutual TLS Certificate Requirements for TLS-bridge Proxy

  • Webex presents a Webex CA signed client certificate to the proxy.

  • The Webex CA certificate chain is deployed on the proxy trust store, so the proxy trusts the client certificate.

  • The publicly signed XSP server certificate is also loaded into the proxy.

  • The proxy presents a publicly signed server certificate to Webex.

  • Webex trusts the public CA that signed the proxy’s server certificate.

  • The proxy presents an internally signed client certificate to the XSPs.

    This certificate must have the x509.v3 extension field Extended Key Usage populated with the BroadWorks OID 1.3.6.1.4.1.6431.1.1.8.2.1.3 and the TLS clientAuth purpose. E.g.:

    X509v3 extensions:

    X509v3 Extended Key Usage:

    1.3.6.1.4.1.6431.1.1.8.2.1.3, TLS Web Client
                  Authentication 

    When generating internal client certificates for the proxy, note that SAN certificates are not supported. Internal server certificates for the XSP can be SAN.

  • The XSPs trust the internal CA.

  • The XSPs present an internally signed server certificate.

  • The proxy trusts the internal CA.

Mutual TLS Certificate Requirements for TLS-passthrough Proxy or XSP in DMZ

  • Webex presents a Webex CA signed client certificate to the XSPs.

  • The Webex CA certificate chain is deployed on the XSPs’ trust store, so the XSPs trust the client certificate.

  • The publicly signed XSP server certificate is also loaded into the XSPs.

  • The XSPs present publicly signed server certificates to Webex.

  • Webex trusts the public CA that signed the XSPs’ server certificates.

Prepare Your Network

Connection Map

The following diagram illustrates integration points. The point of the diagram is to show that you need to review IPs and Ports for connections into and out of your environment. The connections that are used by Webex for BroadWorks are described in the following tables.

The firewall requirements for the normal functioning of the client application however are listed as references since they are already documented on help.webex.com.

Firewall Configuration

The connection map and the following tables describe the connections and protocols required between the clients (on or off the customer’s network), your network, and the Webex platform.

We only document the connections specific to Webex for BroadWorks. We do not show the generic connections between Teams and the Webex cloud, which are documented at:

EMEA Ingress Rules

(Into your network)

Purpose Source Protocol Destination Destination Port

WebexCloud

CTI/Auth/XSI

18.196.116.47

35.156.83.118

35.158.206.190

216.151.128.0/19

69.26.160.0/19

173.37.32.0/20

144.254.96.0/20

HTTPS

Your XSP

443

Webex Teams Client App

Xsi/DMS

Any

HTTPS

Your XSP

443

Webex Teams VoIP endpoints SIP

Any

SIP

Your SBC

SP configured TCP

EMEA Egress Rules

(Out of your network)

Purpose

Source

Protocol

Destination

Destination Port

User Provisioning via APIs

Your Application Server

HTTPS

webexapis.com

443

Proxy Push Notifications(production service)

Webex Common Identity

APNS and FCM services

Your NPS Server

HTTPS

https://nps.uc-one.broadsoft.com/ *

https://idbroker.webex.com

Any IP address*

443

User Provisioning via BroadWorks Provisioning Adapter

Your BroadWorks AS

HTTPS

https://broadworks-provisioning-bridge-*.wbx2.com/

(where * could be any letter. Your exact provisioning URL is available in the template you create in Partner Hub)

443

* We cannot provide a list of IP addresses because we do not have a fixed set for the NPS Auth proxy. You need to allow outbound connections from NPS to any IP address anyway, because APNS and FCM also do not have a fixed set of IP addresses.

USA Ingress Rules

(Into your network)

Purpose

Source

Protocol

Destination

Destination Port

WebexCloud

CTI/Auth/XSI

18.221.216.175

18.217.166.80

13.58.232.148

216.151.128.0/19

69.26.160.0/19

173.37.32.0/20

144.254.96.0/20

HTTPS

CTI

Your XSP

TLS 443

Webex Teams Client App   

Xsi/DMS

Any

HTTPS

Your XSP

443

Webex Teams VoIP endpoints SIP

Any

SIP

Your SBC

SP configured TCP

USA Egress Rules

(Out of your network)

Purpose

Source

Protocol

Destination

Destination Port

User Provisioning via APIs

Your Application Server

HTTPS

webexapis.com

443

Proxy Push Notifications(production service)

Webex Common Identity

APNS and FCM services

Your NPS Server

HTTPS

https://nps.uc-one.broadsoft.com/ *

https://idbroker.webex.com

Any IP address*

443

User Provisioning via BWKS Provisioning Adapter

Your BroadWorks AS

HTTPS

https://broadworks-provisioning-bridge-*.wbx2.com/

(where * could be any letter. Your exact provisioning URL is available in the template you create in Partner Hub)

443

* We cannot provide a list of IP addresses because we do not have a fixed set for the NPS Auth proxy. You need to allow outbound connections from NPS to any IP address anyway, because APNS and FCM also do not have a fixed set of IP addresses.

DNS Configuration

Webex for BroadWorks clients must be able to find your BroadWorks XSP server(s) for authentication, authorization, call control, and device management.

The Webex cloud must be able to find your BroadWorks XSP server(s) for connecting to the Xsi interfaces and authentication service.

You may need to record multiple DNS entries if you have different XSP servers for different purposes.

How Cisco Webex Cloud Finds XSP Addresses

Cisco Webex Cloud services will perform DNS A/AAAA lookup of the configured XSP hostname and connects to the returned IP Address. This could be a load balancing edge element, or it could be the XSP server itself. If multiple IP Addresses are returned, the initial entry in the list will be selected.

Examples 2 & 3 below capture A/AAAA records mapping to single and multiple IP addresses respectively.

In the multiple IP Address scenario, we recommend that you configure your DNS entries to rotate in a round robin manner, to distribute the client connections from Webex.

How Clients Find XSP Addresses

The client attempts to locate the XSP nodes using the following DNS flow:

  1. Client initially retrieves Xsi-Actions/Xsi-Events URLs from Cisco Webex cloud (you entered them when creating the associated BroadWorks Calling Cluster). The Xsi hostname/domain is parsed from the URL and the client performs SRV lookup as follows:

    1. Client performs an SRV lookup for _xsi-client._tcp.<xsi domain>

      (See following example 1)

    2. If the SRV lookup returns one or more targets:

      The client does A/AAAA lookup for those targets and caches the returned IP addresses.

      The client connects to the SRV port on one of the returned IP addresses. It chooses an address based on the SRV priority, then weight (or at random if they’re all equal).

    3. If the SRV lookup does not return any targets:

      The client does A/AAAA lookup of the Xsi root parameter and then tries to connect to the returned IP address. This could be a load balancing edge element, or it could be the XSP server itself.

      (See following examples 2 and 3)

  2. (Optional) You may subsequently provide custom XSI-Actions/XSI-Events details in the device confguration for the Webex Teams client, using the following tags:

    
    <protocols>
        <xsi>
            <paths>
                <root>%XSI_ROOT_WXT%</root>
                <actions>%XSI_ACTIONS_PATH_WXT%</actions>
                <events>%XSI_EVENTS_PATH_WXT%</events>
            </paths>
        </xsi>
    </protocols>
    1. These configuration parameters take precedence over any configuration in your BroadWorks Cluster in Control Hub.

    2. If they exist, the client will compare against the original XSI address it received via the BroadWorks Cluster configuration.

    3. If there is any difference detected, the Client will re-initialize it’s XSI Actions/ XSI Events connectivity. The first step in this is to perform the same DNS lookup process listed under step 1 – this time using the %XSI_ROOT_WXT% parameter from the configuration file.


      Make sure to create the corresponding SRV records if you use this tag to change the Xsi interfaces.

Example DNS Records

Table 1. Example 1: DNS SRV records for client discovery of multiple internet facing XSP servers

Record type

Record

Target

Purpose

SRV

_xsi-client._tcp.your-xsp.example.com.

xsp01.example.com

Client discovery of Xsi interface

SRV

_xsi-client._tcp.your-xsp.example.com.

xsp02.example.com

Client discovery of Xsi interface

A

xsp01.example.com.

198.51.100.48

Lookup of XSP IP

A

xsp02.example.com.

198.51.100.49

Lookup of XSP IP

Table 2. Example 2: DNS A Record for discovery of load balancer fronting XSP server pool

Record type

Name

Target

Purpose

A

your-xsp.example.com.

198.51.100.50

Lookup of edge load balancer IP

Table 3. Example 3: DNS A Record for discovery of Round-Robin balanced internet-facing XSP server pool

Record type

Name

Target

Purpose

A

your-xsp.example.com.

198.51.100.48

Lookup of XSP IP

A

your-xsp.example.com.

198.51.100.49

Lookup of XSP IP

XSP Nodes DNS Recommendations

  • You should use a single A/AAAA record:

    • if you need to resolve a load balancing reverse proxy to the XSP servers

  • You should use round-robin A/AAAA records:

    •  if you have multiple internet facing XSP servers

  • You must use DNS Service Discovery if you:

    • Need directory search in environments with multiple XSPs.

    • Have pre-existing integrations that require SRV discovery.

    • Have unique configurations where standard A/AAAA records are insufficient.