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? Do you want users to provide email addresses to activate their own accounts? Can you build tools to use our API? |
Public API docs at https://developer.webex.com This document |
Branding | What color and logo do you want to use? | Webex app 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, or Softphone. |
This document Feature/package matrix |
User authentication | BroadWorks, or Webex | This document |
Provisioning adapter (for flowthrough provisioning options) |
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 and the Cisco BroadWorks System Engineering Guide.
-
How will 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
Which user provisioning method suits you best?
-
Flowthrough Provisioning With Trusted Emails: By assigning the “Integrated IM&P” service on BroadWorks, the subscriber is automatically provisioned in Webex.
If you can also assert that the subscriber email addresses in BroadWorks are valid, and unique to Webex, then you can use the "trusted email" variant of flowthrough provisioning. Subscriber Webex accounts are created and activated without their intervention; they simply download the client and sign in.
Email Address is a key user attribute on Webex. Therefore the Service Provider must supply a valid email address for the user in order to provision them for 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.
-
Flowthrough Provisioning Without Trusted Emails: If you cannot trust the subscriber email addresses, you can still assign the Integrated IM&P service in BroadWorks to provision users in Webex.
With this option, the accounts are created when you assign the service, but the subscribers need to supply and validate their email addresses to activate the Webex accounts.
-
User Self-Provisioning: This option does not require IM&P service assignment in BroadWorks. You (or your customers) distribute a provisioning link instead, and the links to download the different clients, with your branding and instructions.
Subscribers follow the link, then supply and validate their email addresses to create and activate their Webex accounts. Then they download the client and sign in, and Webex fetches some additional configuration about them from BroadWorks (including their primary numbers).
-
SP Controlled Provisioning via APIs: Webex exposes a set of Public APIs that allow Service Providers to build user/subscriber provisioning into their existing workflows.
Provisioning Requirements
The following table summarizes the requirements for each provisioning method. In addition to these requirements, your deployment must meet the general system requirements that are described in this guide.
Provisioning Method |
Requirements |
---|---|
Flowthrough Provisioning (Trusted or Untrusted emails) |
The Webex provisioning API adds existing BroadWorks users to Webex automatically once the user meets requirements and you toggle the Integrated IM+P service to on. There are two flows (trusted emails or untrusted emails) which you assign via the Customer Template on Webex. BroadWorks requirements:
Webex requirements: The Customer Template includes the following settings:
|
User Self-Provisioning |
Admin provides an existing BroadWorks user with a link to the User Activation Portal. The user must log in to the portal using BroadWorks credentials and provide a valid email address. After the email is validated, Webex fetches additional user information to complete provisioning. BroadWorks requirements:
Webex requirements: The Customer Template includes the following settings:
|
SP controlled provisioning via API (Trusted or Untrusted emails) |
Webex exposes a set of public APIs that enable you to build user provisioning into your existing workflows and tools. There are two flows:
BroadWorks Requirements:
Webex Requirements:
To use the APIs, go to BroadWorks Subscribers. |
Required Patches with Flow-through Provisioning
If you are using flow-through provisioning, you must install a system patch and apply a CLI property. Refer to the below list for instructions that apply to your BroadWorks release:
For R22:
-
Install AP.as.22.0.1123.ap376508.
-
After installation, set the property
bw.msg.includeIsEnterpriseInOSSschema
totrue
from the CLI in Maintenance/ContainerOptions.For more information, see the patch notes https://www.cisco.com/web/software/286326332/154309/AP.as.22.0.1123.ap376508.txt.
For R23:
-
Install AP.as.23.0.1075.ap376509
-
After installation, set the property
bw.msg.includeIsEnterpriseInOSSschema
totrue
from the CLI in Maintenance/ContainerOptions.For more information, see the patch notes https://www.cisco.com/web/software/286326332/154325/AP.as.23.0.1075.ap376509.txt.
For R24:
-
Install AP.as.24.0.944.ap375100
-
After installation, set the property
bw.msg.includeIsEnterpriseInOSSschema
totrue
from the CLI in Maintenance/ContainerOptions.For more information, see the patch notes https://www.cisco.com/web/software/286326332/154326/AP.as.24.0.944.ap375100.txt.
After you complete these steps, you will be unable to provision new users with UC-One Collaborate services. Newly provisioned
users must be Webex for Cisco BroadWorks users.
|
Supported Language Locales
During provisioning, the language that was assigned in BroadWorks to the first provisioned administration user gets assigned automatically as the default locale for that customer organization. This setting determines the default language used for activation emails, meetings, and meeting invites under that customer organization.
Five character language locales in (ISO-639-1)_(ISO-3166) format are supported. For example, en_US corresponds to English_UnitedStates. If only a two letter language is requested (using ISO-639-1 format), the service will generate a five character language locale by combining the requested language with a country code from the template i.e. "requestedLanguage_CountryCode", if unable to get a valid locale, then the default sensible locale used based on the required language code.
The following table lists the supported locales, and the mapping that converts a two-letter language code to a five-character locale for situations where a five-character locale is not available.
Supported Language Locales (ISO-639-1)_(ISO-3166) |
If only a two-letter language code is available... |
|
---|---|---|
Language code (ISO-639-1) ** |
Use Default Sensible Locale instead (ISO-639-1)_(ISO-3166) |
|
en_US en_AU en_GB en_CA |
en |
en_US |
fr_FR fr_CA |
fr |
fr_FR |
cs_CZ |
cs |
cs_CZ |
da_DK |
da |
da_DK |
de_DE |
de |
de_DE |
hu_HU |
hu |
hu_HU |
id_ID |
id |
id_ID |
it_IT |
it |
it_IT |
ja_JP |
ja |
ja_JP |
ko_KR |
ko |
ko_KR |
es_ES es_CO es_MX |
es |
es_ES |
nl_NL |
nl |
nl_NL |
nb_NO |
nb |
nb_NO |
pl_PL |
pl |
pl_PL |
pt_PT pt_BR |
pt |
pt_PT |
ru_RU |
ru |
ru_RU |
ro_RO |
ro |
ro_RO |
zh_CN zh_TW |
zh |
zh_CN |
sv_SE |
sv |
sv_SE |
ar_SA |
ar |
ar_SA |
tr_TR |
tr |
tr_TR |
The locales es_CO, id_ID, nb_NO and pt_PT are not supported by Webex Meeting Sites. For these locales, The Webex Meetings sites will be in English only. English is the default locale for sites if no/invalid/unsupported locale is required for the site. This language field is applicable while creating an Organization and Webex Meetings site. If no language is mentioned in a post or in the subscriber's API then language from the template will be used as a default language. |
Branding
Partner administrators can use Advanced Branding Customizations to customize how the Webex App looks for the customer organizations that the partner manages. Partner administrators can customize the following settings to ensure that the Webex App reflects their company brand and identity:
-
Company logos
-
Unique Color Schemes for Light mode or Dark mode
-
Customized Support URLs
For details on how to customize branding, refer to Configure Advanced Branding Customizations.
|
Customer Templates
Customer Templates allow you to define the parameters by which customers and associated subscribers are automatically provisioned on Webex for Cisco BroadWorks. You may configure multiple Customer Templates as required, but when you onboard a customer it is associated with only one template (you cannot apply multiple templates to one customer).
Some of the primary template parameters are listed below.
Package
-
You must select a default package when you create a template (See Packages in the Overview section for details). All users who are provisioned with that template, whether by flowthrough- or self-provisioning, receive the default package.
-
You have control over the package selection for different customers by creating multiple templates and selecting different default packages in each. You could then distribute different provisioning links, or different per-enterprise provisioning adapters, depending on your chosen user provisioning method for those templates.
-
You can change the package of specific subscribers from this default, using the provisioning API (see Webex for Cisco BroadWorks API documentation or through Partner Hub (see Change User Package in Partner Hub).
-
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 Partner 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.
Make sure that you have applied the BroadWorks patches that are required for flow-through provisioning. For details, see Required Patches with Flow-through Provisioning.
|
Authentication Mode
Decide how you want subscribers to authenticate when they log in to Webex. You can assign the mode using the Authentication Mode setting in the Customer Template. The following table outlines some of the options.
This setting has no effect on login to the User Activation Portal. Users who sign in to the portal must enter their BroadWorks
user ID and password, as configured on BroadWorks, irrespective of how you configure Authentication Mode on the Customer Template.
|
Authentication Mode | BroadWorks | Webex |
Primary user identity | BroadWorks user ID | Email address |
Identity Provider |
BroadWorks.
|
Cisco Common Identity |
Multi-factor authentication? | No | Requires Customer IdP that supports multi-factor authentication. |
Credential validation path |
|
|
For a more detailed breakdown of the SSO login flow with direct authentication to BroadWorks, see SSO Login Flow.
|
UTF-8 Encoding with BroadWorks Authentication
With BroadWorks authentication, we recommend that you configure UTF-8 encoding for the authentication header. UTF-8 resolves an issue that can occur with passwords that use special characters whereby the web browser does not encode the characters properly. Using a UTF-8 encoded, base 64-encoded header resolves this issue.
You can configure UTF-8 encoding by running one of the following CLI commands on the XSP or ADP:
-
XSP_CLI/Applications/WebContainer/Tomcat/GeneralSettings> set authenticationEncoding UTF-8
-
ADP_CLI/Applications/WebContainer/Tomcat/GeneralSettings> set authenticationEncoding UTF-8
Country
You must select a country when you create a template. This country will be automatically assigned as the organisation country for all the customers that are provisioned with the template in Common Identity. Additionally, the organization country will determine the default global call-in numbers for Cisco PSTN in Webex Meeting Sites.
The site's default global call-in numbers will be set to the first available dial-in number defined in the telephony domain based on the organization's country. If the organization's country is not found in the dial-in number defined in the telephony domain, the default number of that location will be used.
S No. |
Location |
Country Code |
Country Name |
---|---|---|---|
1 |
AMER |
+1 |
US, CA |
2 |
APAC |
+65 |
Singapore |
3 |
ANZ |
+61 |
Australia |
4 |
EMEA |
+44 |
UK |
5 |
EURO |
+49 |
Germany |
Multiple Partner Arrangements
Are you going to sub-license Webex for Cisco 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 Cisco 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.
Provisioning Adapter Proxy
For added security, the Provisioning Adapter Proxy lets you use an HTTP(S) proxy on the Application Delivery Platform for flowthrough provisioning between the AS and Webex. The proxy connection creates an end-to-end TCP tunnel that relays traffic between the AS and Webex, thereby negating the need for the AS to connect to the public internet directly. For secure connections, TLS can be used.
This feature requires that you set up the proxy on BroadWorks. For details, see Cisco BroadWorks Provisioning Adapter Proxy Feature Description.
Minimum Requirements
Accounts
All subscribers that you are provisioning for Webex must exist in the BroadWorks system that you integrate with Webex. You can integrate multiple BroadWorks systems if necessary.
All subscribers must have BroadWorks licenses and a primary number or extension.
Webex uses email addresses as primary identifiers for all users. If you are using flowthrough provisioning with trusted emails, then your users must have valid addresses in the email attribute in BroadWorks.
If your template uses BroadWorks authentication, you can copy subscriber email addresses into the Alternate ID attribute in BroadWorks. This makes it possible for users to sign into Webex using their email addresses and their BroadWorks passwords.
Your admins must use their Webex accounts to sign in to Partner Hub.
It is not supported to onboard a BroadWorks administrator to Webex for Cisco BroadWorks. You can only onboard BroadWorks calling
users who have a primary number and/or extension. If you are using flowthrough provisioning, users must also be assigned the
Integrated IM&P service.
|
Servers in Your Network and Software Requirements
-
BroadWorks instance(s) with minimum version R22. See BroadWorks Software Requirements (in this document) for supported versions and patches. For more information, see BroadSoft products lifecycle policy section in BroadSoft Lifecycle Policy and BroadWorks Software Compatibility Matrix.
-
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) or Application Delivery Platform (ADP) meeting the following requirements:
-
Authentication service (BWAuth)
-
XSI actions and events interfaces
-
DMS (device management web application)
-
CTI interface (Computer Telephony Intergration)
-
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 Webex client certificate chain installed as trust anchors)
-
Mutual TLS (mTLS) authentication for CTI interface (Requires the public Webex client certificate chain installed as trust anchors)
-
-
A separate XSP/ADP 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 delivers push notifications for messaging and presence).
This server must be on R22 or later.
-
We mandate a separate XSP/ADP 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 for more on XSP scale.
Webex App Platforms
To download the English version of the Webex App, go to https://www.webex.com/webexfromserviceproviders-downloads.html. The Webex App is available on:
-
Windows PCs/laptops
-
Apple PCs / laptops with MacOS
-
iOS (Apple store)
-
Android (Play store)
-
Web browsers (go to https://teams.webex.com/)
Localized Versions
To download a localized version of the Webex App, use one of these links:
-
https://origin-webex-uat.cisco.com/ko/webexfromserviceproviders-downloads.html (Korean)
-
https://origin-webex-uat.cisco.com/fr/webexfromserviceproviders-downloads.html (French)
-
https://origin-webex-uat.cisco.com/pt/webexfromserviceproviders-downloads.html (Portuguese)
-
https://origin-webex-uat.cisco.com/zh-tw/webexfromserviceproviders-downloads.html (Chinese Traditional)
-
https://origin-webex-uat.cisco.com/zh-cn/webexfromserviceproviders-downloads.html (Chinese Simplified)
-
https://origin-webex-uat.cisco.com/ja/webexfromserviceproviders-downloads.html (Japan)
-
https://origin-webex-uat.cisco.com/es/webexfromserviceproviders-downloads.html (Spain)
-
https://origin-webex-uat.cisco.com/de/webexfromserviceproviders-downloads.html (German)
-
https://origin-webex-uat.cisco.com/it/webexfromserviceproviders-downloads.html (Italian)
Physical Phones and Accessories
-
Cisco IP phones:
-
Cisco IP Phone 6800 Series with Multiplatform Firmware
-
Cisco IP Phone 7800 Series with Multiplatform Firmware
-
Cisco IP Phone 8800 Series with Multiplatform Firmware
See https://www.cisco.com/c/en/us/products/collaboration-endpoints/ip-phones/multiplatform-firmware.html for models and more information.
-
-
We support third party phones in the same way as with other BroadWorks integrations. However, they do not yet have contacts and presence integration with Webex for Cisco BroadWorks.
-
Adapters:
-
Cisco ATA 191 Multiplatform Analog Telephone Adapter
-
Cisco ATA 192 Multiplatform Analog Telephone Adapter
See https://www.cisco.com/c/en/us/products/unified-communications/ata-190-series-analog-telephone-adapters/index.html for models and more information.
-
-
Headsets:
-
Cisco Headset 500 Series
See https://www.cisco.com/c/en/us/products/collaboration-endpoints/headset-500-series/index.html for models and more information.
-
-
Room OS Devices:
-
Webex Room and Room Kit Series
-
Webex Desk Series
-
Webex Board Series
-
Device Integration
For details on how to onboard and service Room OS and MPP devices for Webex for Cisco BroadWorks, see Device Integration Guide for Webex for Cisco BroadWorks.
Device Profiles
Following are the DTAF files you need to load onto your Application Servers to support the Webex App as a calling client.
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 the Webex App.
To download the latest device profiles, go to the Application Delivery Platform Software Downloads site to get the latest DTAF files. These downloads work for both ADP and XSP.
Client Name |
Device Profile Type and Package name |
---|---|
Webex Mobile Template |
Identity/Device Profile Type: Connect - Mobile DTAF: Config file: |
Webex Tablet Template |
Identity/Device Profile Type: Connect - Tablet DTAF: Config file: |
Webex Desktop Template |
Identity/Device Profile Type: Business Communicator - PC DTAF: Config file: |
Identify/Device Profile
All Webex for Cisco BroadWorks users must have an Identity/Device Profile assigned in BroadWorks that uses one of the above device profiles in order to make calls using the Webex App. The profile provides the configuration that allows the user to place calls.
Obtaining OAuth credentials for your Webex for Cisco BroadWorks
Raise a service request with your onboarding agent or with Cisco TAC to provision Cisco OAuth for your Cisco Identity Provider Federation account.
Use the following request title for respective features:
-
XSP AuthService Configuration' to configure service on XSP.
-
'NPS Configuration for Auth Proxy Setup' to configure NPS to use authentication proxy.
-
CI User UUID Sync' for CI user UUID sync. For more details on this feature, see: Cisco BroadWorks support for CI UUID.
-
Configure BroadWorks to enable Cisco Billing for BroadWorks and Webex For BroadWorks Subscriptions.
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, you can raise another request.
If you already obtained Cisco OAuth Identity Provider credentials, complete a new service request to update your credentials. |
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 the Webex app supports for authentication are listed in Supported Certificate Authorities for 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 over CTI Interface
When connecting to the CTI interface, Webex presents a client certificate as part of Mutual TLS authentication. The Webex client certificate CA/chain certificate is available for download via Control Hub.
To download the certificate:
Sign in to Partner Hub, got to
and click the download certificate link.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 the certificate requirements in these three cases:
(Option) Certificate Requirements for TLS-bridge Proxy
-
Webex presents a publicly signed client certificate to the proxy.
-
The proxy trusts the Cisco internal CA that signed the client certificate. You can download this CA / chain from Control Hub and add it to the proxy’s trust store. The publicly signed XSP server certificate is also loaded into the proxy.
-
The proxy presents the 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
The CN of the internal certificate must be bwcticlient.webex.com.
-
When generating internal client certificates for the proxy, note that SAN certificates are not supported. Internal server certificates for the XSP can be SAN.
-
Public certificate authorities may not be willing to sign certificates with the proprietary BroadWorks OID that is required. In the case of a bridging proxy, you may be forced to use an internal CA to sign the client certificate that the proxy presents to the XSP.
-
-
The XSPs trust the internal CA.
-
The XSPs present an internally signed server certificate.
-
The proxy trusts the internal CA.
-
The Application Server’s ClientIdentity contains the CN of the internally signed client certificate presented to the XSP by the proxy.
(Option) Certificate Requirements for TLS-passthrough Proxy or XSP in DMZ
-
Webex presents a Cisco internal CA-signed client certificate to the XSPs.
-
The XSPs trust the Cisco internal CA that signed the client certificate. You can download this CA / chain from Control Hub and add it to the proxy’s trust store. The publicly signed XSP server certificate is also loaded into the XSPs.
-
The XSPs present the publicly signed server certificates to Webex.
-
Webex trusts the public CA that signed the XSPs’ server certificates.
-
The Application Server ClientIdentity contains the CN of the Cisco-signed client certificate presented to the XSP by Webex.
Prepare Your Network
For more information on connections that are used by Webex for Cisco BroadWorks, see: Network Requirements for Webex for Cisco BroadWorks. This article has the list of IP addresses, ports and protocols required to configure your firewall Ingress and Egress rules.
Network Requirements for Webex Services
The preceding Ingress and Egress Rules firewall tables document only the connections that are specific to Webex for Cisco BroadWorks. For general information on connections between the Webex app and the Webex cloud, see Network Requirements for Webex Services. This article is generic to Webex, but the following table identifies the different sections of the article and how relevant each section is to Webex for Cisco BroadWorks.
Section of Network Requirements Article |
Relevance of Information |
---|---|
Informational |
|
Transport protocols and encryption ciphers for cloud registered Webex apps and devices |
Informational |
Must read |
|
Must read |
|
Domains and URLs that need to be accessed for Webex Services |
Must read |
Optional |
|
Optional |
|
Optional |
|
Optional |
|
Optional |
|
Optional |
|
Webex Services for FedRAMP customers |
N/A |
Additional Information
For additional information, see Webex App Firewall Whitepaper (PDF).
BroadWorks Redundancy Support
The Webex Cloud Services and the Webex Client Apps that need to access the partner’s network fully support the Broadworks XSP redundancy provided by the partner. When an XSP or site is unavailable for planned maintenance or unplanned reason, the Webex services & apps are able to advance to another XSP or site provided by the partner in order to complete a request.
Network Topology
The Broadworks XSPs can be deployed directly on the Internet, or can reside in a DMZ fronted by a load balancing element such as the F5 BIG-IP. To provide geo-redundancy, the XSPs can be deployed in two (or more) datacenters, each can be fronted by a load balancer, each having a public IP address. If the XSPs are behind a load balancer, the Webex microservices and App see only the IP address of the load balancer and Broadworks appears to have just one XSP, even if there are multiple XSPs behind.
In the example below, the XSPs are deployed at two sites, Site A and Site B. There are two XSPs fronted by a Load Balancer at each site. Site A has XSP1 and XSP2 fronted by LB1, and Site B has XSP3 and XSP4 fronted by LB2. Only the Load Balancers are exposed on the public network, and the XSPs are in the DMZ private networks.
Webex Cloud Services
DNS Configuration
The Webex Cloud microservices must be able to find the Broadworks XSP server(s) for connecting to the Xsi interfaces, authentication service and CTI.
Webex Cloud microservices will perform DNS A/AAAA lookup of the configured XSP hostname and connect 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 first IP in the list will be selected. SRV lookup are not currently supported.
Example: The partner’s DNS A Record for discovery of Round-Robin balanced internet-facing XSP server/Load Balancers.
Record Type |
Name |
Target |
Purpose |
---|---|---|---|
A |
|
|
Points to LB1 (Site A) |
A |
|
|
Points to LB2 (Site B) |
Failover
When the Webex microservices send a request to the XSP/Load Balancer and the request fails, several things can happen:
-
If the failure is due to a network error (ex: TCP, SSL), the Webex microservices mark the IP as blocked and immediately perform a route advance to the next IP.
-
If an error code (HTTP 5xx) is returned, the Webex microservices mark the IP as blocked and immediately perform a route advance to the next IP.
-
If no HTTP response is received within 2 seconds, the request times out and the Webex microservices mark the IP as blocked and perform a route advance to the next IP.
Each request is tried 3 times before a failure is reported back to the microservice.
When an IP is in the blocked list, it will not be included in the list of addresses to try when sending a request to a XSP. After a predetermined period of time, a blocked IP expires and goes back in the list to try when another request is made.
If all IP addresses are blocked, the microservice will still try to send the request by randomly selecting an IP address from the blocked list. If successful, that IP address is removed from the blocked list.
Status
The status of the connectivity of the Webex Cloud services to the XSPs or Load Balancers can be seen in Control Hub. Under a BroadWorks Calling Cluster, a connection status is displayed for each of these interfaces:
-
XSI Actions
-
XSI Events
-
Authentication Service
The connection status is updated when the page is loaded or during input updates. The connections statuses can be:
-
Green: When the interface can be reached on one of the IPs in the A record lookup.
-
Red: When all IPs in the A record lookup are unreachable and the interface is unavailable.
The following services use the microservices to connect to the XSPs and are impacted by the XSP interface availability:
-
Webex App Login
-
Webex App token refresh
-
Untrusted email/self activation
-
Broadworks Service Health Check
Webex App
DNS Configuration
The Webex App accesses the Xtended Services Interface (XSI-Actions & XSI-Events) and Device Management Service (DMS) services on the XSP.
To find the XSI service, the Webex App performs DNS SRV lookup for _xsi-client._tcp.<webex app xsi domain>
. The SRV points to the configured URL for the XSP hosts or load balancers for the XSI service. If SRV lookup is not available,
the Webex App falls back to A/AAAA lookup.
The SRV can resolve to multiple A/AAAA targets. However, each A/AAAA record must map to a single IP address only. If there are multiple XSPs in a DMZ behind the load balancer/edge device, it is required that the load balancer be configured to maintain session persistence to route all requests of the same session to the same XSP. We mandate this configuration because the client's XSI-event heartbeats must go to the same XSP that is used to establish the event channel.
In Example 1, the A/AAAA record for webex-app-xsp.example.com does not exist, and does not need to. If your DNS requires that one A/AAAA record must be defined, then only 1 IP address should be returned. Regardless, the SRV must still be defined for the Webex App. If the Webex App uses the A/AAAA name that resolves to more than one IP address, or if the load balancer/edge element does not maintain session persistence, the client eventually sends heartbeats to an XSP where it did not establish an event channel. This results in the channel being torn down, and also in significantly more internal traffic which impairs your XSP cluster performance. Because the Webex Cloud and Webex App have different requirements in A/AAAA record lookup, you must use a separate FQDN for
the Webex Cloud and Webex App to access your XSPs. As shown in the examples, Webex Cloud uses A record |
Example 1—Multiple XSPs, each behind separate load balancers
In this example, the SRV points to mutiple A records with each A record pointing to a different load balancer at a different site. The Webex App will always use the first IP address in the list and will only move to the next record if the first is down.
Record Type |
Record |
Target |
Purpose |
---|---|---|---|
SRV |
|
|
Client discovery of Xsi interface |
SRV |
|
|
Client discovery of Xsi interface |
A |
|
|
Points to LB1 (site A) |
A |
|
|
Points to LB2 (site B) |
Example 2—Multiple XSPs behind a single load balancer (with TLS Bridge)
For the initial request, the load balancer selects a random XSP. That XSP returns a cookie that the Webex App includes in future requests. For future requests, the load balancer uses the cookie to route the connection to the correct XSP, ensuring that the event channel doesn't break.
Record Type |
Record |
Target |
Purpose |
---|---|---|---|
SRV |
|
|
Load balancer |
A |
LB.example.com |
|
IP address of load balancer (XSPs are behind load balancer) |
DMS URL
During the login process, the Webex App will also retrieve the DMS URL to download its config file. The host in the URL will parsed and the Webex App will perform DNS A/AAAA lookup of the host to connect to the XSP that hosts the DMS service.
Example: DNS A Record for discovery of Round-Robin balanced internet-facing XSP server/Load Balancers by Webex App to download config files through DMS:
Record Type |
Name |
Target |
Purpose |
---|---|---|---|
A |
|
|
Points to LB1 (site A) |
A |
|
|
Points to LB2 (site B) |
How Webex App Finds XSP Addresses
The client attempts to locate the XSP nodes using the following DNS flow:
-
Client initially retrieves Xsi-Actions/Xsi-Events URLs from 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:
-
Client performs an SRV lookup for _xsi-client._tcp.<xsi domain>
-
If the SRV lookup returns one or more A/AAAA targets:
-
The client does A/AAAA lookup for those targets and caches the returned IP addresses.
-
The client connects to one of the targets (and therefore its A/AAAA record with a single IP address) based on the SRV priority, then weight (or at random if they’re all equal).
-
-
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.
As noted, the A/AAAA record must resolve to one IP address for the same reasons.
-
-
(Optional) You may subsequently provide custom XSI-Actions/XSI-Events details in the device configuration for the Webex app, 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>
-
These configuration parameters take precedence over any configuration in your BroadWorks Cluster in Control Hub.
-
If they exist, the client will compare against the original XSI address it received via the BroadWorks Cluster configuration.
-
If there is any difference detected, the client will re-initialize its XSI Actions/ XSI Events connectivity. The first step in this is to perform the same DNS lookup process listed under step 1 – this time requesting a lookup for the value in the %XSI_ROOT_WXT% parameter from its configuration file.
Make sure to create the corresponding SRV records if you use this tag to change the Xsi interfaces.
-
Failover
During login, the Webex App performs a DNS SRV lookup for _xsi-client._tcp.<xsi domain>, builds a list of hosts, and connects to one of the hosts based on the SRV priority, then weight. This connected host becomes the selected one for all future requests. An event channel is then opened to the selected host and a heartbeat is sent regularly to verify the channel. All requests sent after the first one include a cookie that is returned in the HTTP response, therefore, it’s important that the load balancer keeps session persistence (affinity) and always sends requests to the same backend XSP server.
If a request or a heartbeat request to a host fails, several things can happen:
-
If the failure is due to network error (ex: TCP, SSL), the Webex App route advances immediately to the next host on the list.
-
If an error code (HTTP 5xx) is returned, the Webex App marks that IP address as blocked and route advances to the next host on the list.
-
If a response is not received within a period of time, then the request is considered failed due to timeout and the next requests are sent to the next host. However, the timed out request is considered as failed. Some requests are retried after failure (with increasing retry time). The requests that the assumed non vital are not retried.
When a new host is tried successfully, it becomes the new selected host if the host is present in the list. After the last host in the list is tried, the Webex App will rollover to the first one.
In the case of heartbeat, if there are two consecutive request failures, the Webex App will re-initialize the event channel.
Note that the Webex App does not perform fail-back, and DNS service discovery is performed only once at sign-in.
During sign-in, the Webex App tries to download the config file through the XSP/Dms interface. It performs a A/AAAA record lookup of the host in the retrieved DMS URL and connects to the first IP. It will first try to send the request to download the config file using a SSO token. If this fails for any reason, it will try again but with the device username and password.