Appendix

Configure XSP Authentication Service (with mTLS)

Complete the procedures in this Appendix to configure the Authentication Service on BroadWorks to use mTLS authentication. In instances where CI Token Validation (with TLS) is not supported, mTLS authentication is mandatory, including the following instances:

  • If you are running R21SP1

  • If you are running R22 or higher and have multiple Webex organizations running off the same XSP server


If you are running R22 or higher, and do not have multiple Webex organizations running off the same XSP server, CI Token Validation (with TLS) is recommended for the Auth Service.

Install Authentication Service

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

  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

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

    On 21SP1:XSP_CLI/Applications/authenticationService_1.0/TokenManagement> set tokenDuration 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.

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.

Configure Trust for Authentication Service (with mTLS)

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          

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.

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