Updates for Version R21SP1

Install XSP Authentication Service (R21SP1)

Use the following procedures to install the AuthService on the BroadWorks server only if you are running R21SP1.

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.