Appendix

The below procedures replace the procedures in the topic Configure Services on Your Webex for Cisco BroadWorks XSPs. Complete these procedures only if you are using mTLS for the Authentication Service rather than CI Token Validation. These procedures are mandatory if you are running multiple Webex organizations off the same XSP server. Otherwise, they are optional.

Note	If you aren't running multiple Webex organizations off the same XSP server, CI Token Validation (with TLS) is recommended for the Auth Service. Refer to Configure Services on Your Webex for Cisco BroadWorks XSPs for details on how to configure the Authentication service and other services.

Xsi Interfaces

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

Only one instance of the Xsi-Events applications should be deployed on the XSP/ADP used for the CTI interface.

All Xsi-Events used for integrating Broadworks with Webex must have the same callControlApplicationName defined under Applications/Xsi-Events/GeneralSettings. For example:

ADP_CLI/Applications/Xsi-Events/GeneralSettings> get

callControlApplicationName = com.broadsoft.xsi-events

When a user is onboarded to Webex, Webex creates a subscription for the user on the AS in order to receive telephony events for presence and call history. The subscription is associated with the callControlApplicationName and the AS uses it to know to which Xsi-Events to send the telephony events.

Note	Changing the callControlApplicationName, or not having the same name on all Xsi-Events webapps will impact subscriptions and telephony events functionality.

Configure Authentication Service (with mTLS)

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 your BroadWorks version).

2. Deploy the application:

   XSP_CLI/Maintenance/ManagedObjects> deploy application /authService

Configure Token Duration

1. Check the existing token configuration (hours):

   XSP_CLI/Applications/authenticationService/TokenManagement> get

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

   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.

Note	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. The key store location is not configurable. Export the keys:

   XSP_CLI/Applications/authenticationService/KeyManagement> exportKeys

4. Copy the exported file /var/broadworks/tmp/authService.keys to the same location on the other XSPs, overwriting an older .keys file if necessary.

5. 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 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:

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

The HTTP interface that is interacting with the 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

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.

   Note

   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 Trust for Authentication Service (with mTLS)

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 CombinedCertChain2023.txt on your local computer.

   Note	These files contain two sets of two certificates. You need to split the files before you upload them to the XSPs. All files are required.

3. Split the certificate chain into two certificates - combinedcertchain2023.txt.

   1. Open combinedcertchain2023.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 root2023.txt.

   4. Save the original file as issuing2023.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. /var/broadworks/tmp/root2023.txt and /var/broadworks/tmp/issuing2023.txt.

5. Sign in to the XSP and navigate to /XSP_CLI/Interface/CTI/SSLCommonSettings/ClientAuthentication/Trusts>. (Optional) Run help UpdateTrust to see the parameters and command format.

6. Upload the certificate files to new trust anchors - 2023

   XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexclientroot2023 /var/broadworks/tmp/root2023.txt
   XSP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts> updateTrust webexclientissuing2023 /var/broadworks/tmp/issuing2023.txt

   Note	All aliases must have a different name. webexclientroot, webexclientroot2023, webexclientissuing, and webexclientissuing2023 are example aliases for the trust anchors; you can use your own as long as all four entries are unique.

7. Confirm the anchors are updated:

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

     Alias   Owner                                   Issuer
   =============================================================================
   webexclientissuing2023       Internal Private TLS SubCA      Internal Private Root
   webexclientroot2023       Internal Private Root      Internal Private Root[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.

Where to go Next

For configuration, you can rejoin the main document flow at CTI Interface and Related Configuration.