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|ADP farm, for example).

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

• Do not install other applications or services on the XSP|ADPs 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.

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.

Configure Authentication Service (with CI Token Validation)

Use this procedure to configure the Authentication Service to use CI Token Validation with TLS. This authentication method is recommended if you are running R22 or higher and your system supports it.

1. Obtaining OAuth credentials for your Webex for Cisco BroadWorks.

2. Install the following patches on each XSP|ADP server. Install the patches that are appropriate to your release:

   • For R22:

     AP.platform.22.0.1123.ap376508

     AP.xsp.22.0.1123.ap376508

     AP.xsp.22.0.1123.ap368601

   • For R23:

     AP.xsp.23.0.1075.ap376509

     AP.platform.23.0.1075.ap376509

   • For R24—no patch required

   Any reference to XSP includes either XSP or ADP.

3. Install the AuthenticationService application on each XSP|ADP service.

   1. Run the following command to activate the AuthenticationService application on the XSP|ADP to the /authService context path.

      XSP|ADP_CLI/Maintenance/ManagedObjects> activate application AuthenticationService 22.0_1.1123/authService

   2. Run this command to deploy the AuthenticationService on the XSP|ADP:

      XSP|ADP_CLI/Maintenance/ManagedObjects> deploy application /authServiceBroadWorks SW Manager deploying /authService...

4. Starting with Broadworks build 2022.10, the certificates authorities that are coming with Java are no longer automatically included to the BroadWorks trust store when switching to a new version of java. The AuthenticationService opens a TLS connection to Webex to fetch the access token, and needs to have the following in its truststore to validate the IDBroker and Webex URL:

   • IdenTrust Commercial Root CA 1

   • Go Daddy Root Certificate Authority - G2

   Verify that these certificates are present under the following CLI

   ADP_CLI/System/SSLCommonSettings/Trusts/Defaults> get

   If not present, run the following command to import the default Java trusts:

   ADP_CLI/System/SSLCommonSettings/Trusts/Defaults> importJavaCATrust

   Alternatively, you can manually add these certificates as trust anchors with the following command:

   ADP_CLI/System/SSLCommonSettings/Trusts/BroadWorks> updateTrust <alias> <trustAnchorFile>

   If the ADP is upgraded from a previous release, then the certificate authorities from the old release are automatically imported to the new release and will continue to be imported until they are manually removed.

   The AuthenticationService application is exempt from the validatePeerIdentity setting under ADP_CLI/System/SSLCommonSettings/GeneralSettings, and always validates the peer Identity. See the Cisco Broadworks X509 Certificate Validation FD for more info on this setting.

5. Configure the Identity Providers by running the following commands on each XSP|ADP server:

   XSP|ADP_CLI/Applications/AuthenticationService/IdentityProviders/Cisco> get

   • set clientId client-Id-From-Step1

   • set enabled true

   • set clientSecret client-Secret-From-Step1

   • set ciResponseBodyMaxSizeInBytes 65536

   • set issuerName <URL>—For the URL, enter the IssuerName URL that applies to your CI Cluster. See following table.

   • set issuerUrl <URL>—For the URL, enter the IssuerUrl that applies to your CI Cluster. See the following table.

   • set tokenInfoUrl <IdPProxy URL>—Enter the IdP Proxy URL that applies to your Teams Cluster. See the second table that follows.

   Table 1. Set issuerName and issuerURL

   If CI Cluster is...	Set issuerName and issuerURL to...
   US-A	https://idbroker.webex.com/idb
   EU	https://idbroker-eu.webex.com/idb
   US-B	https://idbroker-b-us.webex.com/idb
   If you don't know your CI Cluster, you can obtain the information from the Customer details in Help Desk view of Control Hub.

   Table 2. Set tokenInfoURL

   If Teams Cluster is...	Set tokenInfoURL to...(IdP Proxy URL)
   ACHM	https://broadworks-idp-proxy-a.wbx2.com/broadworks-idp-proxy/api/v1/idp/authenticate
   AFRA	https://broadworks-idp-proxy-k.wbx2.com/broadworks-idp-proxy/api/v1/idp/authenticate
   AORE	https://broadworks-idp-proxy-r.wbx2.com/broadworks-idp-proxy/api/v1/idp/authenticate
   If you don't know your Teams Cluster, you can obtain the information from the Customer details in the Help Desk view of Control Hub. For testing, you can verify that the tokenInfoURL is valid by replacing the "idp/authenticate" portion of the URL with "ping".

6. Specify the Webex entitlement that must be present in the user profile in Webex by running the following command:

   XSP|ADP_CLI/Applications/AuthenticationService/IdentityProviders/Cisco/Scopes> set scope broadworks-connector:user

7. Configure Identity Providers for Cisco Federation using the following commands on each XSP|ADP server:

   XSP|ADP_CLI/Applications/AuthenticationService/IdentityProviders/Cisco/Federation> get

   • set flsUrl https://cifls.webex.com/federation

   • set refreshPeriodInMinutes 60

   • set refreshToken refresh-Token-From-Step1

8. Run the following command to validate that your FLS configuration is working. This command will return the list of Identity Providers:

   XSP|ADP_CLI/Applications/AuthService/IdentityProviders/Cisco/Federation/ClusterMap> Get

9. Configure Token Management using the following commands on each XSP|ADP server:

   • XSP|ADP_CLI/Applications/AuthenticationService/TokenManagement>

   • set tokenIssuer BroadWorks

   • set tokenDurationInHours 720

10. Generate and Share RSA Keys. You must generate keys on one XSP|ADP then copy them to all other XSP|ADPs. This is due to the following factors:

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

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

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

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

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

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

    3. The key store location is not configurable. Export the keys:

       XSP|ADP_CLI/Applications/authenticationService/KeyManagement> exportKeys

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

    5. Import the keys on each of the other XSP|ADPs:

       XSP|ADP_CLI/Applications/authenticationService/KeyManagement> importKeys /var/broadworks/tmp/authService.keys

11. Provide the authService URL to the web container. The XSP|ADP’s web container needs the authService URL so it can validate tokens. On each of the XSP|ADPs:

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

       XSP|ADP_CLI/System/CommunicationUtility/DefaultSettings/ExternalAuthentication/AuthService> set url http://127.0.0.1:80/authService

    2. Add the authentication service URL to the container:

       XSP|ADP_CLI/Maintenance/ContainerOptions> add tomcat bw.authservice.authServiceUrl http://127.0.0.1:80/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|ADP.

Remove Client Authentication Requirement for Auth Service (R24 only)

If you have the Authentication Service configured with CI Token validation on R24, you also need to remove the Client Authentication Requirement for the Authentication Service. Run the following CLI command:

ADP_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/WebApps> set <interfaceIp> <port> AuthenticationService clientAuthReq false

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|ADP

1. Sign in to the XSP|ADP and navigate to XSP|ADP_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|ADP_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|ADP and navigate to XSP|ADP_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|ADP and navigate to XSP|ADP_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|ADP 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|ADP 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|ADP_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 Device Management on XSP|ADP, Application Server, and Profile Server

Profile Server and XSP|ADP are mandatory for Device Management. They must be configured according to instructions in the BroadWorks Device Management Configuration Guide.