BW ExternalPortalIntegrationGuide R170

7/21/2019 BW ExternalPortalIntegrationGuide R170

1/37

External Portal Integration Guide

Developers Guide

Release 17.0

Document Version 2

9737 Washingtonian Boulevard, Suite 350Gaithersburg, MD 20878Tel +1 301.977.9440

WWW.BROADSOFT.COM
http://www.broadsoft.com/http://www.broadsoft.com/


2/37

BroadWorks

Guide

Copyright Notice

Copyright 2011 BroadSoft, Inc.

All rights reserved.

Any technical documentation that is made available by BroadSoft, Inc. is proprietary andconfidential and is considered the copyrighted work of BroadSoft, Inc.

This publication is for distribution under BroadSoft non-disclosure agreement only.No part of this publication may be duplicated without the express written permission of

BroadSoft, Inc. 9737 Washingtonian Boulevard, Gaithersburg, MD 20878.

BroadSoft reserves the right to make changes without prior notice.

Trademarks

BroadWorksand BroadWorks AssistantEnterprise, BroadWorks AssistantMobile,

BroadWorks Call Center, BroadWorks Communicator, BroadWorks Receptionist,and BroadWorks Deployment Studio are trademarks of BroadSoft, Inc.

Microsoft, MSN, Windows, and the Windows logo are registered trademarks of MicrosoftCorporation. Other product names mentioned in this document may be trademarks orregistered trademarks of their respective companies and are hereby acknowledged.

This document is printed in the United States of America.


3/37

BROADWORKS EXTERNAL PORTAL INTEGRATION GUIDE 13-BD5015-00

2011 BROADSOFT, INC. PAGE 3 OF 37

Document Revision History

Release Version Reason for Change Date Author

15.0 1 Created document for Release 14.0

and Release 15.0.

August 27, 2008 Simon Cadieux

15.0 1 Edited and published document. September 25, 2008 Andrea Fitzwilliam

15.0 2 Replaced HTTP_BWS_USERID byHTTPBWUSERID inTable 1Custom HTTP Headersfor EV65118.

December 15, 2008 Goska Auerbach

15.0 2 Edited changes and publisheddocument.

January 16, 2009 Andrea Fitzwilliam

16.0 1 Created Release 16.0 from Release15.0, Document Version 2.

February 7, 2009 Roberta Boyle

17.0 1 Created Release 17.0 from Release16.0, Document Version 1.

February 2, 2010 Yves Racine


March 26, 2010 Margot Hovey-Ritter

17.0 2 Updated section6 Third-Party

System Integrationfor EV 140594.

Replaced references to the WebServer by references to the XtendedServices Platform (Xsp) throughoutthe document for EV 144811.

April 28, 2011 Goska Auerbach


November 15, 2011 Patricia Renaud


4/37



Table of Contents

1 Purpose ...........................................................................................................................................8

2 Overview..........................................................................................................................................9

2.1 Web Portal Application Integration ........................................................................................... 11

2.1.1 Redirection with User ID and Password .......................................................................... 11

2.1.2 Redirection using External Authentication ...................................................................... 11

2.2 Direct Client Application Integration .......................................................................................... 11

2.3

Third-Party System Integration ................................................................................................. 11

2.4 Portal Integration Implementation Flowchart ........................................................................... 12

3 External Authentication Prerequisites .................................................................................... 13

3.1 Basic Xtended Services Platform Configuration ...................................................................... 13

3.2 External Authentication Specific Configuration ........................................................................ 13

3.2.1

External Authentication Flag and Password Rules on Application Server .................... 13

3.2.2 Access Control Lists ......................................................................................................... 15

4 Web Portal Application Integration ......................................................................................... 16

4.1 Web Portal Integration through Redirection ............................................................................. 16

4.2 Web Portal Integration using External Authentication ............................................................. 16

4.2.1 External Authentication using Embedded Agent ............................................................ 17

4.2.2 External Authentication for Non-embedded Agent ......................................................... 21

4.2.3 Security Considerations ................................................................................................... 25

5 Direct Client Application Integration ....................................................................................... 28

5.1

Direct Client Integration with Regular Authentication .............................................................. 28

5.2 External Authentication using Web-based Authentication Server .......................................... 28

5.2.1 Open Client Server Web-based External Authentication Message Flow ...................... 30

5.2.2 Configuration ..................................................................................................................... 30

5.2.3 WAS Authentication Request and Response Specification ........................................... 31

5.2.4 WAS Login Request and Response Specification ......................................................... 31

6 Third-Party System Integration ................................................................................................ 33

7 Appendix A: Integration with Netegri ty SiteMinder ............................................................. 34

7.1 Hardware Considerations ......................................................................................................... 34

7.2 Authentication Process.............................................................................................................. 34

7.3

Authorization Process ............................................................................................................... 34

7.4 Policy Server Installation ........................................................................................................... 35

7.5

Custom HTTP Headers ............................................................................................................. 35

7.6 Sharing Policy Server Polices Across Clusters ....................................................................... 35

7.7 Policy Server High Availability................................................................................................... 35

7.8 Web Agent Installation .............................................................................................................. 36

7.9 Single Sign-On Configuration ................................................................................................... 36


5/37



7.10

Agent Key Management ........................................................................................................... 36

7.11 Provisioning End Users and Administrators ............................................................................. 36

7.12

Levels of Protection ................................................................................................................... 37

7.13 Session Management ............................................................................................................... 37

7.14

Cross-site Scripting and Escaped Characters in URLs ........................................................... 37


6/37



Table of Figures

Figure 1 Direct Web Portal Integration through Redirection .................................................................... 9Figure 2 Web Portal Integration with External Authentication .................................................................. 9Figure 3 Direct Client Integration ............................................................................................................. 10Figure 4 Third-Party System Integration

................................................................................................. 10Figure 5 Portal Integration Mechanisms Flowchart ................................................................................ 12Figure 6 Utilities Password Rules (System Level) ............................................................................... 13Figure 7 Utilities Password Rules (Service Provider) .......................................................................... 14Figure 8 External Authentication using Embedded Agent ..................................................................... 17Figure 9 User Login using Custom HTTP Headers ................................................................................ 18Figure 10 Custom HTTP Header Dialog in Netegrity SiteMinder Policy Server

................................... 20Figure 11 End User Login using new_session.jsp .................................................................................. 22Figure 12 OCI Client External Authentication through WAS

.................................................................. 28Figure 13 Open Client Server Web-based External Authentication Message Flow ............................. 30Figure 14 OCI External Authentication for Third-Party Systems ........................................................... 33


7/37



List of Tables

Table 1 Custom HTTP Headers .............................................................................................................. 21Table 2 External Authentication Error Codes .......................................................................................... 21Table 3 Parameters Supported by new_session.jsp .............................................................................. 25


8/37



1 Purpose

BroadWorks provides many features that allow for the seamless integration of externalportals or third-party applications with BroadWorks own provisioning interfaces such as theBroadWorks web portal interface or Open Client Interface (OCI). This allows for theintegration of BroadWorks in an environment comprised of multiple web portals and/orthird-party applications while offering the end user an experience that does not requiremultiple logins (that is, Single Sign-On).

When the external portal or third-party application has knowledge of user passwords, itcan leverage normal login transactions and the servlet to integrate to BroadWorks whilepassing the known password as a parameter, and eliminate the need for the user to enterit manually.

However, BroadWorks External Authentication also provides the ability for a customer tostore user passwords in a separate database and delegate the authentication of users toan external policy server or authority.

BroadWorks External Authentication is characterized by:

The ability to create user accounts in BroadWorks without passwords, as well as adepartment administrator, group administrator, and service provider administratoraccounts without passwords.

The ability to integrate an external policy server or authority with BroadWorks.

BroadWorks allows for the integration of three types of applications:

Redirection between web portal applications

OCI client applications running on end users system

Complete OCI-based third-party systems

This document describes how to use the mechanisms provided by BroadWorks, includingexternal authentication, in each of the three situations.


9/37



2 Overview

BroadWorks can be integrated to web portal applications, direct client applications, orthird-party systems (that is, clients that use the BroadWorks OCI, including OCI-Client[OCI-C] and/or Open Client Interface-Provisioning [OCI-P]).

The different scenarios can be used simultaneously to build complex applications. Theapplication of the different scenarios is not exclusive.

The end user is either automatically logged in through redirection with ID and passwordpassed as parameters or authenticated on the third-party web portal using the policyserver:

Automatically logged in through redirection with ID and password passed asparameters. In this case, the password is stored on BroadWorks (that is, externalauthentication is not used) and the redirecting web portal has knowledge of userpasswords. This is shown inFigure 1.

Figure 1 Direct Web Portal Integration through Redirection

Authenticated on the third-party web portal using the policy server. In this case, thepolicy server has authority over authentication, and passwords are not stored onBroadWorks. The same policy server or authority is used when authenticating theuser on the BroadWorks Web Portal upon redirection. This is shown inFigure 2.

Figure 2 Web Portal Integration with External Authentication

Third-PartyPortal

BroadWorks HTTPWeb Portal Traffic

Redirection

Third-PartyPortal

Password or

Policy Server

BroadWorks HTTPWeb Portal Traffic

Authentication

Authentication


10/37



Figure 3shows the second situation, in which an OCI-based application is running on theend-user system and connects to BroadWorks. The password or policy server is used byBroadWorks to authenticate the end user in the system.

Figure 3 Direct Client Integration

Figure 4shows a scenario in which an end user connects to a third-party system runningoutside of BroadWorks. This third-party system then connects to BroadWorks through theOCI. In this scenario, BroadWorks assumes that users have already been authenticated

by the third-party system.

Figure 4 Third-Party System Integration

This section provides a high-level view of the needs for the three types of applications andindicates the various sections that provide more information on the implementation.

Third-PartySystem

OCI

End Users

Password orPolicy Server

OCIAuthentication


11/37



2.1 Web Portal Application Integration

Web portal applications are capable of dynamically or statically redirecting a user oradministrator to the appropriate BroadWorks Xtended Services Platform (Xsp).

2.1.1 Redirection with User ID and Password

If the redirecting web portal has access to passwords stored on BroadWorks, it can simplyredirect the user to a uniform resource locator (URL), giving the user ID, and password asparameters. Therefore, users are not required to enter their passwords twice.

For more information, see section4.1Web Portal Integration through Redirection.

2.1.2 Redirection using External Authentication

BroadWorks supports two external authentication mechanisms for web portals, theembedded and the non-embedded mechanisms.

In the embedded mechanism, an application (such as the Netegrity SiteMinder suite of

products) is packaged on the BroadWorks Xtended Services Platform, provides protectionfor web sites, and offers Single Sign-On integration among the Xtended ServicesPlatforms.

In the non-embedded mechanism, the external portal must use a generic authenticationmechanism on BroadWorks, which allows a list of preauthorized hosts to log on toBroadWorks without authentication.

Note that regardless of the mechanism used, the Call Manager, Attendant Console,BroadWorks AssistantEnterprise, and BroadWorks Receptionist applications can belaunched as usual, provided that the proper configuration is applied. For moreinformation, section3 External Authentication Prerequisites.

2.2 Direct Client Application Integration

BroadWorks allows for external client applications that target end users to connect throughthe Open Client Server (OCS) on an Xtended Services Platform.

Client applications that have the knowledge of user passwords can use regular OCIauthentication while using the Open Client Server. For more information, see section5.1Direct Client Integration with Regular Authentication.

Client applications that do not have access to user passwords may have to connect toBroadWorks where an operator has deployed a centralized authentication system. In thisscenario, it is possible to tie the external password database to the Open Client Serverauthentication mechanism using a Web-based Authentication Server (WAS). The WASacts as a mediator between BroadWorks and the custom authentication system. Thisscenario is described in section5.2 External Authentication using Web-based

Authentication Server.

2.3 Third-Party System Integration

Third-party systems that interact with BroadWorks through the OCI can be integrated aswell. In this scenario, it is assumed that end users are authenticated by the third-partysystem. The third-party system is considered to be a trusted entity and its address isadded to an access control list on BroadWorks. This scenario is described insection6 Third-Party System Integration.


12/37



2.4 Portal Integration Implementation Flowchart

The following flowchart helps to quickly identify the steps required to implement portalintegration and refers you to the proper sections in the document.

Portal Integration

Implementation Steps

Application

Type?

See section

4.2.1

Embedded

Mechanism?

Third Party SystemWeb Portal

Integration

See section

4.2.2

See section 6See section

5.2

Yes No

See section

4.2.3

Implement Security

Policies

Client Application

Apply basic WS farm config.

(see section 3.1)

Apply external authentication

specific config.

(see section 3.2)

External

Authentication?YesNo

See section

4.1

Application

Type?Web Portal

Integration

Client Application

See section

5.1

Figure 5 Portal Integration Mechanisms Flowchart


13/37



3 External Authentication Prerequisi tes

3.1 Basic Xtended Services Platform Configuration

All external authentication mechanisms presented in this guide assume that an XtendedServices Platform or an Xtended Services Platform server farm has been properlyconfigured. For more information on configuring the Xtended Services Platform, see theBroadWorks Xtended Services Platform Configuration Guide.

3.2 External Authentication Specific Configuration

In addition to the basic Xtended Services Platform configuration, the steps identified in thefollowing subsections must be completed for all external authentication mechanisms to beused.

3.2.1 External Authentication Flag and Password Rules on Application Server

External authentication and password rules can be set at the service provider or systemlevel on every Application Server. Along with the flag that lets customers determine(toggle) whether external authentication is used for a particular set of users, it is alsopossible to allow administrator and user IDs to be created without an associatedpassword. A user without a password can access BroadWorks only through externalauthentication.

External authentication and password rules can be set using theAdministrator web pagesor using the Application Server command line interface (CLI).

Using the Administrator Web Pages

The Password Rulesweb page at the system level, as shown inFigure 6,hasAllow usersto be created on web portal check box allowing the administrators to enable or disable the

creation of new users without passwords. External authentication can be turned on at thesystem level when System and Provisioning Administrators; all other Administrators andUsers use external authenticationbutton is selected.

Figure 6 Utilities Password Rules (System Level)


14/37



The Password Rulespage at the service provider level, shown inFigure 7,has twooptions as well:

The Group Administrators and Users use external authenticationbutton is used toturn external authentication on or off.

TheAllow users to be created on web portalcheck box is used to allow new users to

be created without passwords (within this service provider).

Figure 7 Utilities Password Rules (Service Provider)

Using the CLITo set external authentication at the system level, the following Application Server CLIcommand must be issued:

AS_CLI / Subscr i berMgmt / PasswordRul es> set rul esAppl yTosysAdmi nsOnl yOt her sUseExt ernal Auth

To enable the creation of users without passwords (system-wide), the following commandmust be issued:

AS_CLI / Subscr i berMgmt / PasswordRul es> set al l owWebAddExt ernal AuthUser strue

At the service provider level, the following commands are used:

AS_CLI / Subscr i berMgmt / Servi ceProvi der/ PasswordRul es> set rul esAppl yTogroupAdmi nsAndUser sExternal Auth

AS_CLI / Subscr i berMgmt / Servi ceProvi der/ PasswordRul es> setal l owWebAddExt ernal AuthUser s t rue


15/37



3.2.2 Access Control Lists

First, the loopback address must be added to the external authentication access controllist (ACL) on the host where the Open Client Server (and the corresponding XtendedServices Platform) resides. This is because Tomcat on the Xtended Services Platformmust be able to bypass authentication for OCI-P traffic going through the collocated Open

Client Server for applications such as Attendant Console and Call Manager.XSP_CLI / Appl i cat i ons/ OpenCl i ent Server / External Aut hent i cat i on/ AccessCont rol Li st> add 127. 0. 0. 1 l ocal host

Secondly, the address of all Xtended Services Platforms and their collocated Open ClientServer must be added to the external authentication ACL for alltarget Application Servers.For example, if the Xtended Services Platform server farm is comprised of two servers(192.168.1.1 and 192.168.1.2), then you would enter:

AS_CLI / System/ NetworkAccessLi st s/ Ext Aut h> add 192. 168. 1. 1 XSP1Done.

AS_CLI / System/ NetworkAccessLi st s/ Ext Aut h> add 192. 168. 1. 2 XSP2Done.


16/37



4 Web Portal Application Integration

4.1 Web Portal Integration through Redirection

Redirecting a user to the BroadWorks web portal without having to enter the userspassword twice is simply a matter of passing the user ID and password as parameters tothe BroadWorks web portals login servlet. This can be done using Hypertext TransferProtocol (HTTP) redirection or by securing HTTP if the BroadWorks web portal has secureHTTP support enabled.

The URL to which the user must be redirected has the following format:

htt p: / / / servl et / Logi n?User I D=&Password=

where:

is the fully qualified domain name (FQDN) of the

BroadWorks Xtended Services Platform server farm

is the user ID of the user

is the password of the user

4.2 Web Portal Integration using External Authentication

The external authentication mechanism that allows for web portal integration has twovariations:

A specialized (embedded) mechanism based on custom HTTPheaders

A generic (non-embedded) mechanism secured by an access control list

The specialized mechanism, which is easier to configure and implement, is described firstin section4.2.1 External Authentication using Embedded Agent,followed by the genericmechanism described in section4.2.2 External Authentication for Non-embedded Agent.Section4.2.3 Security Considerationsaddresses the security needed for the solution.


17/37



4.2.1 External Authentication using Embedded Agent

This mechanism uses the custom HTTPheader functionality, provided by applicationssuch as Netegrity SiteMinder Web Agent, to pass the required authentication parametersto the BroadWorks web application. End users, department administrators, groupadministrators, and service provider administrators can be authenticated by this

mechanism.

Figure 8 External Authentication using Embedded Agent

In this scenario, BroadSoft provides the Application Server cluster, the Network Servercluster, and the External Xtended Services Platform server farm. The customer integratesthe BroadWorks web application into the existing portal, developing custom code in theform of a portal application. It is the customers responsibility to set up an application suchas Netegrity SiteMinder that can ensure authentication/authorization and Single Sign-Onsupport for the entire portal, including the BroadWorks web application.


18/37



4.2.1.1 User Login

The steps for external authentication with custom HTTP headers for a user (end user oradministrator) login are shown inFigure 9,which is followed by a description of each step.Note that for simplicity only one Application Server and External Xtended ServicesPlatform pair in the Application Server cluster are shown.

Figure 9 User Login using Custom HTTP Headers

Note that there is a prerequisite for the BroadWorks system to have external

authentication password rules enabled. For more information, see section3.2.1 ExternalAuthentication Flag and Password Rules on Application Server.

1) The user logs in to the customers portal web server.

2) The Netegrity SiteMinder application authenticates and authorizes the user. From thispoint on it is assumed that Single Sign-On is configured among all Xtended ServicesPlatforms involved. At some point, the user clicks on a link for the BroadWorksCommPilot web application, including the CommPilot Call Manager (if applicable).

3) The portal application redirects the end users browser to the Xtended ServicesPlatform server farm FQDN or Web Server collocated with an Application Server, andspecifically to the Java Serverpage (JSP) that expects custom HTTPheaders, forexample:

ht t p: / / xsp_server _f arm_f qdn/ ea_l ogi n. j sp orht t p: / / appl i cat i on_server_cl uster_f qdn/ ea_l ogi n. j sp

The Netegrity Siteminder Web Agent (or equivalent application) running alongside theXtended Services Platform intercepts the HTTP request and contacts the policyserver (or equivalent application) for instructions.

4) The Web Agent checks that the user is authorized to access the BroadWorks webapplication.
http://xsp_server_farm_fqdn/ea_login.jsphttp://a_fqdn/ea_login.jsphttp://a_fqdn/ea_login.jsphttp://xsp_server_farm_fqdn/ea_login.jsp


19/37



5) Based on the users authentication and authorization, the Web Agent inserts customHTTP headers identifying the user to the BroadWorks web application.

As part of this step, the Web Agent can optionally specify a portal login URL to whichthe BroadWorks web application redirects the user when the BroadWorks websession is terminated. (Usually a user is presented with the BroadWorks Login page

when the web session is terminated.)6) The Xtended Services Platform uses the location application programming interface

(API) on the Network Server to dynamically resolve the addresses of the ApplicationServers in the users hosting cluster.

7) The Xtended Services Platform logs the user in the first available Application Server inthe cluster, starting with the primary server.

8) The ea_login JSPpage redirects the users browser to the starting page in theBroadWorks web application, and the user can use all functionality of the BroadWorksweb application.

When there is invalid data in the custom HTTPheaders (for example, unknown user),the Application Server generates a Simple Network Management Protocol (SNMP)

trap, and the user is redirected to the BroadWorks Login page. As part of theprevious step, the Web Agent can optionally specify an unknown user URL wherethe user is redirected instead.

9) (This step is not shown.) If applicable, the users CommPilot Call Manager starts in anew window.

The same sequence applies whether the user is logging into the External XtendedServices Platform or the collocated Web Server on the Application Server. Of course, theNetegrity Siteminder Web Agent (or equivalent) must be installed alongside the ApacheStronghold web server on the respective machines.

Selected steps are described in more detail in the following sections.

4.2.1.2 Determine BroadWorks Application Server Address

The Network Server cluster must have at all times, current information indicating theApplication Server cluster hosting a particular user. (In general, the Network Server cancontain data from many Application Server clusters.) The External Xtended ServicesPlatform uses the Network Server portal interface to determine the Application Servercluster associated with the user that is in the process of logging in.

The Network Server returns the addresses of each individual server in the ApplicationServer cluster hosting a user. The Xtended Services Platform uses the primary server tolog the user in, if available, and falls back to the secondary server, if the primary server isnot available. In the latter case, the session silently reverts back to the primary serverwhen it becomes available (that is, the user does not notice any disruption in the session).This is true for both administrator and end-user logins.

4.2.1.3 Redirect to ea_login.jsp

The ea_login.jsppage is the entry point for the external authentication mechanism usingcustomHTTPheaders. The portal application should construct the redirect uniformresource locator (URL) dynamically, based on the address returned by the location APIquery to the Network Server, as follows:

prot ocol : / / xtended_servi ces_pl at f orm_address/ ea_l ogi n. j sp


20/37



The protocol used to build the redirect URL uses the secure sockets layer (SSL) setting onthe target Xtended Services Platform. If the SSL setting is off or on, the protocol shouldbe HTTP. If full SSL support is enabled on the target BroadWorks Xtended ServicesPlatform, the protocol should be HTTPS. If HTTPS is not used in the latter scenario, thelogin still works, but the user is presented with an unnecessary security-related warning inthe browser.

4.2.1.4 Insert Custom HTTP Headers

The methodology used to insert the custom HTTP headers into the HTTP requestdepends on the application that is used. The Netegrity SiteMinder Web Agent insertscustom HTTPheaders when such an instruction is configured in the Response object onthe corresponding SiteMinder policy server. The dialog used to insert a dynamic valueinto a custom HTTPheader is shown inFigure 10.

NOTE: In SiteMinder, the name of the HTTP variable has the HTTP_ prefix twice.

Figure 10 Custom HTTP Header Dialog in Netegrity SiteMinder Policy Server

The custom HTTPheaders expected by the BroadWorks web applications ea_login.jspare listed inTable 1.

Name Default Value Description

HTTPBWUSERID None (This header is required.) The end users or administratorsuser ID in the BroadWorks system.The value can contain the @domainending, if required.


21/37




HTTP_BW_DOMAIN "" The part after the @ sign in theuser ID, if required, and if notalready provided in theHTTPBWUSERIDheader.Specifically, if a @ is present in the

HTTPBWUSERIDheader value, theHTTP_BW_DOMAIN value isignored.

HTTP_BW_UNKNOWN_USER_URL

By default, error cases areredirected to the BroadWorksweb application login form, at:/Login/index.jsp?EA_ERR=xxx.

The user is redirected to thespecified URL when the user ID(and/or domain) are missing or arenot recognized by BroadWorks. Aninformational alarm is raised.

If this URL ends with a ? character,the appropriate externalauthentication error code isappended, in the form:unknownUserURLEA_ERR=xxx.(For the codes, see section4.2.1.5Error Codes.)

HTTP_BW_PORTAL_LOGIN_URL

/Login/index.jsp or /Logout,depending on the cause ofredirection.

When an administrator ends aBroadWorks session, or when anend user is forced to log in again forsome reason, the end user isredirected to this target URL.

Table 1 Custom HTTP Headers

These custom HTTPheaders are only required for the ea_login.jsppage. There is noneed to provide these values after that point. Therefore, the policy server can have aspecific rule for that page and a general response-less rule for the entire BroadWorks webapplication.

4.2.1.5 Error CodesThe following error codes are appended to the unknownUserURL (if the URL ends withthe ? character) in case of authentication failure, to help troubleshoot the externalauthentication problem.

Value Description

EA_ERR=001 External authentication password rules are not enabled on this system.

EA_ERR=002 Unknown or missing user ID. (This includes the case when the domain is requiredbut not provided, either as part of the user ID or separately.)

EA_ERR=003 The external authentication client is not on the access control list. (This errorcode does not apply to the custom HTTP headers scenario.)

EA_ERR=004 System error.

Table 2 External Authentication Error Codes

4.2.2 External Authentication for Non-embedded Agent

The generic external authentication mechanism is a JSP that accepts the BroadWorksuserId as an HTTPparameter, using a GET or POST method. To prevent unauthorizedaccess, an access control list provides additional protection. The mechanism is HTTP-


22/37



based; however the external authentication client application does not have to be abrowser. The requirements for the external authentication client are to be able to send anHTTP command to the JSP on the BroadWorks Xtended Services Platform and acceptthe subsequent HTTP redirection instruction. Such a client could be integrated into thecustomers portal application, to be invoked when the user or administrator requestsaccess to the BroadWorks web application.

4.2.2.1 User Login

The steps for generic external authentication for a user login (end user or administrator)are shown inFigure 11. For simplicity, the primary Application Server in the hosting

Application Cluster server and one External Xtended Services Platform in the XtendedServices Platform server pool are shown.

Figure 11 End User Login using new_session.jsp

The prerequisites on the BroadWorks system are that:

External authentication password rules are enabled.

The server on which the portal application is running is added to the externalauthentication ACL.

1) The user logs into the customers portal web server. At some point, the user clicks ona link for the BroadWorks CommPilot web application, which includes the CommPilotCall Manager (if applicable).

2) The portal application opens a Transmission Control Protocol (TCP) connection to theidentified Xtended Services Platform on port 80 (HTTP), and sends the following two-line text request:

GET / new_sessi on. j sp?userI d=userId HTTP/ 1. 1Host : address_of_xtended_services_platform


23/37



NOTE: The parameters can also be sent by the POST method.

As part of this step, the portal application can (optionally) specify a portal login URL

to which the BroadWorks web application redirects the user when the BroadWorksweb session is terminated. (Usually, the user is presented with the BroadWorks Loginpage when the web session is terminated.)

3) The Xtended Services Platform uses the location API on the Network Server todynamically resolve the addresses of the Application Servers in the users hostingcluster.

4) The Xtended Services Platform checks that the server hosting the portal application isin the ACL for external authentication, and that external authentication is turned on forthe target Application Server.

5) The Xtended Services Platform logs the user in the primary (or secondary, if primaryis not available) Application Server of the hosting cluster.

6) The new_session.jsppage responds by generating an HTTP redirection response,such as:

HTTP/ 1. 1 302Date: dateServer : St ronghol d/ 4. 0c Set - Cooki e: J SESSI ONI D=; Pat h=/Set - Cooki e: J SESSI ONI D=; Pat h=/Locat i on:ht t ps: / / address_of_xtended_servi ces_pl at f orm/ servl et / Logi n?l ogi nToken=t oken&ASAddress=asaddress

Cont ent - Lengt h: 0Cont ent - Type: t ext / ht ml

When there is invalid data in the custom HTTPheaders (for example, unknown user),the Application Server generates an SNMP trap, and the user is redirected to theBroadWorks Login page. As part of the previous step, the portal application can(optionally) specify an unknown user URL where the user is redirected instead.

7) The portal application parses the response and identifies the redirection URL, which itthen presents as is to the users browser. The user either clicks on a link or theusers browser is redirected automatically to that URL by some other mechanism.

8) The Login servlet accepts the Login page and redirects the users browser to thestarting page in the BroadWorks web application, and the user can use all thefunctionality of the BroadWorks web application.

9) (This step is not shown.) If applicable, the users CommPilot Call Manager starts in anew window.

The same sequence applies whether the user is logging into the External XtendedServices Platform or the collocated Web Server on the Application Server.

Selected steps are described in more detail in the following sections.
https://address_of_xtended_services_platform/servlet/Login?loginToken=tokenhttps://address_of_xtended_services_platform/servlet/Login?loginToken=tokenhttps://address_of_xtended_services_platform/servlet/Login?loginToken=tokenhttps://address_of_xtended_services_platform/servlet/Login?loginToken=tokenhttps://address_of_xtended_services_platform/servlet/Login?loginToken=token


24/37



4.2.2.2 Prerequisite for Portal Server in External Authentication ACL

The server on which the portal application is running must be added to the externalauthentication access control list, using the Application Server CLI from theAS_CLI/System/NetworkAccessLists/ExtAuthlevel.

4.2.2.3 Send HTTP Request to new_session.jsp

The request can be sent over SSL, if SSL support is enabled (on or full) on the targetXtended Services Platform. The supported parameters for the GET or POST method areshown inTable 3.


userId None (This parameter is mandatory.) The end users or administratorsuser ID in the BroadWorkssystem. The user ID can containthe @domain, if required.

domain "" The part after the @ sign in theuser ID, if required, and if notalready provided in the userIdparameter.

unknownUserURL By default, error cases are redirected tothe BroadWorks web application loginform, at:

/Login/index.jsp?EA_ERR=xxx

A URL-encoded target URL usedwhen the user ID and/or domainis unknown or missing. If theunknownUserURLparameter isprovided, it is used instead of thedefault redirect URL on error.

If this URL ends with a ?character, the appropriateexternal authentication error codeis appended in the form:unknownUserURLEA_ERR=xxx.(For the codes, see section4.2.1.5 Error Codes.)

portalLoginURL /Login/index.jsp or /Logout, dependingon the cause of redirection.

When an administrator ends aBroadWorks session, or when anend user is forced to log in againfor some reason, they areredirected to this URL-encodedtarget URL.

Note that this value is storedwithin the users HTTP sessioncookie. If the HTTP sessionexpires due to inactivity, theportalLoginURL value cannot beretrieved. In this case, the user isredirected to the default loginpage of the BroadWorks portal.


25/37




serverName The server name of the XtendedServices Platform used by the externalauthentication client (that is, the portalapplication) to invoke new_session.jsp.

This parameter can be used toforce the user to be redirected tothe Login servlet on serverName,rather than to the XtendedServices Platform through which

the portal application connectedto new_session.jsp.

The only meaningful values arethe server names of the ExternalXtended Services Platform andthe collocated Web Server of thetarget hosting/primary ApplicationServer.

Table 3 Parameters Supported by new_session.jsp

4.2.2.4 Response from new_session.jsp

The new_session.jspconstructs the redirect URL dynamically, based on the followingparameters:

protocol : / / address_of _web_server / servl et/ Logi n?l ogi nToken=t oken&ASAddress=asaddress

The protocol used in building the redirect URL depends on the SSL setting on the targetXtended Services Platform . If the SSL setting is off or on, the protocol is HTTP. Iffull SSL support is enabled on the target BroadWorks Xtended Services Platform ; theprotocol is HTTPS.

The address_of_web_server is the Xtended Services Platform through which the portalapplication invoked new_session.jsp, unless this is overridden by using the serverNameparameter.

The token is an internal BroadWorks value mapped to the userId provided tonew_session.jsp. The token allows the user to log in without a password. It is valid for 60seconds, after which it expires, that is, the portal application must redirect the user to thereturned URL within 60 seconds.

The as address is the address of the Application Server on which the token has beenprepared and is valid.

Note that the value of the portalLoginURLparameter can also appear in the redirect URL,under the name redirectURL, if originally provided when invoking new_session.jsp.

4.2.2.5 Redirect User

As mentioned in section4.2.2.4 Response from new_session.jsp,the portal applicationmust redirect the user to the returned URL within 60 seconds. If this URL is used afterthat period, the user is redirected to the Loginpage, unless the portalLoginURLparameterwas provided to new_session.jsp.

4.2.3 Securit y Considerations

Whichever external authentication mechanism is used, it is important to note the followingsecurity concerns:

Secure socket layer (SSL) support


26/37



Unauthorized login attempts through the BroadWorks Login page

BroadWorks password expiry

BroadWorks web application session expiry

Protecting ea_login.jsp from unauthorized access

Protecting new_session.jsp from unauthorized access

Cookie issues

This section describes these security concerns.

4.2.3.1 SSL Support

BroadWorks Application Servers and External Xtended Services Platforms support SSL,either on selected pages (SSL is on) or on all pages in the web application (SSL is full).Whether on or full, the SSL setting should be the same in all the servers in a cluster,that is, the two Application Servers and the two External Xtended Services Platforms.Otherwise, users receive unnecessary security warnings in their browsers.

4.2.3.2 Unauthorized Login Attempts through BroadWorks Login Page

The BroadWorks Loginpage at /Logincan still be accessed when external authenticationpassword rules are enabled. This is because system administrators and provisioningadministrators still have to log in through the Loginpage. On the other hand, this meansthat the Loginpage is exposed to unauthorized login attempts from anyone who hasaccess to it. If required, access to the Login page at/Loginshould be blocked by someother means (such as Netegrity SiteMinder), for those categories of users that aremanaged by external authentication.

NOTE: TheLoginpage cannot be used if a particular user has a blank password onBroadWorks. Such attempts are refused, with no additional configuration. The same holds true

for the login API part of the BroadWorks portal API.

4.2.3.3 BroadWorks Password Expiry

When external authentication password rules are enabled, and if the end user, departmentadministrator, group administrator, or service provider administrator password is blank,then the BroadWorks password expiry mechanism does not apply. On the other hand, ifthese users do have a password in BroadWorks, it can expire based on the passwordexpiry setting, regardless of external authentication.

4.2.3.4 BroadWorks Web Application Session Expiry

When external authentication password rules are enabled, BroadWorks web applicationsessions do not expire for end users, department administrators, group administrators, orservice provider administrators. This is true whether or not the web application sessionwas initiated through external authentication. Session timeouts for these types of usersare supposed to be managed externally, using Netegrity SiteMinder or a similarapplication.


27/37



4.2.3.5 Protect ea_login.jsp from Unauthorized Access

If the custom HTTPheaders mechanism is not used, but external authentication passwordrules are enabled, then the ea_login.jsppage should be protected from unauthorizedaccess. Using a modified web browser capable of sending the custom HTTP headerswould enable anyone knowing only the user ID for a user to log in as that end user,

department, group, or service provider administrator. Protecting this page can be assimple as adding a redirect statement in the Apache configuration files, sending therequestor to the /Login page instead.

4.2.3.6 Protect new_session.jsp from Unauthorized Access

Although new_session.jsp is protected by an ACL, this still leaves open the possibility ofsomeone using a web browser from an address in the ACL. If the new_session.jsp isinvoked from such a browser, any user ID of an existing end user, department, group, orservice provider administrator can be provided, and the web browser is redirected to thestarting page for that user. Therefore, it is imperative to restrict access to the machinefrom which new_session.jsp is invoked, in terms of using a web browser or installing abrowser, if one is not installed.

4.2.3.7 Cookie Issues

For obvious reasons, accessing the BroadWorks web application through externalauthentication does not create the user ID/password cookie that is an option whenaccessing the web application through the Loginpage (that is, by clicking on theRemember Passwordcheck box). However, if the BroadWorks system has beenupgraded from an existing system on which users or administrators had such cookies andexternal authentication password rules are enabled, the following restrictions may apply:

Existing login cookies may not be sufficient to log in.

Existing login cookies may be invalidated.

4.2.3.7.1 Existing Login Cookies May Not be Sufficient to Log In

When external authentication is enabled in password rules, existing login cookiescontaining the BroadWorks users user ID/password may no longer be sufficient to accessthe web application, depending on the external authentication configuration and the waythe user is accessing the BroadWorks Login page.

New user ID/password cookies can still be created by logging in through the Login pagefor the convenience of system administrators and provisioning administrators. However,this is redundant and there is no particular reason to do this for those types of userscovered by external authentication. Even then, cookies can only be created by users oradministrators whose BroadWorks passwords are not blank.

4.2.3.7.2 Existing Login Cookies May be Invalidated

In addition to the previous restriction, when external authentication is enabled in passwordrules, user or administrator passwords can be set to blank by the operations supportsystem (OSS) provisioning system. In this case, such user or administrators existing logincookies are invalidated.


28/37



5 Direct Client Application Integration

BroadWorks OCI-P and OCI-C protocols allow for third-party clients to performBroadWorks provisioning or call control.

5.1 Direct Client Integration with Regular Authentication

Clients can connect to the Open Client Server (OCS) on External Xtended ServicesPlatforms and use regular OCI-P and OCI-C authentication when they have knowledge ofuser IDs and passwords.

OCI authentication is covered in BroadWorks Application Server Provisioning InterfaceSpecification.

5.2 External Authentication using Web-based Authent ication Server

When External Xtended Services Platforms are deployed, clients can connect to the OpenClient Server to communicate using the OCI protocol without involving regular

BroadWorks authentication. Authentication is then achieved by integrating anintermediate server between the password database or policy server and the Open ClientServer.

The Open Client Server can be set up to interact with an external authentication authorityusing a proprietary protocol built on HTTP requests and responses (Web-based

Authentication Server). In this case, the Open Client Server relies on the WAS to provideAuthentication services. In this scenario, the customer provides the WAS, implementingthe following protocol.

This mechanism involves the use of a Web-based Authentication Server, which serves asan external authority to authenticate users.

Figure 12 OCI Client External Authentication through WAS

The role of the WAS is to act as an intermediate server between the Open Client Serverand an External Authentication policy server/service. The WAS is basically used to

OCS

Password DB orolic server

WAS


29/37



abstract or provide a front end to any authentication system (that is not provided byBroadSoft) used by a customer. The customer is responsible for providing a WAS-compliant application that interacts with their own policy server.

The interaction between client applications and the Open Client Server is unchangedevenwhen the external authentication mode is enabled, that is, there is no impact on

either the externally exposed OCI-P or the OCI-C API.In this mode, the Open Client Server intercepts the OCI AuthenticationRequest andLoginRequest messages coming from the client application, and tries to authenticate theuser connection with a Web-based Authentication Server, instead of proxying themdirectly to the target Application Server.

The Open Client Server communicates with the WAS using a predefined set of messages.The protocol used is HTTP, as the WAS acronym suggests. The set of messages issimilar to those used by OCI for the two-steps authentication mechanism.

To avoid passing clear text passwords in messages, the concept of nonce used for OCIauthentication is reused when communicating with the WAS. Hence, the authenticationsequence is divided in two steps:

1) Obtain a temporary nonce that the client must use to hash the password.2) Send the login request using the hashed password.

As described above, the message exchange occurs in two steps. The set of messagesexchanged between the Open Client Server and the WAS is defined as follows:

Authentication request

Authentication response

Login request

Login response

The requests (and responses) used for external authentication between the Open ClientServer and the WAS use XML, which is similar to what is used by OCI transactions

(regardless as to whether the login request coming from the client is for OCI-C or OCI-P).

The WAS web services request is sent by the Open Client Server to authenticateusers with the ID and password specified by the client applications.

BroadWorks does not provide any implementation of a WAS. This means that theresponsibility is on the customer to build/create a web service (server) that collectsthis login information and service it via HTTP(s).

The messages are exchanged between the Open Client Server and the WAS, usingHTTP-based communication, allowing XML messages to be transported uponHTTP(s). When sending an authentication or login request, the user ID and passwordare transmitted as parameters to the URL specified by the customer when configuringexternal authentication on the Open Client Server. The WAS response is sent anXML document. Following is a description of the schema of this document.

The timeout period for WAS communication is set (as with the Network Server locationlookup) to 8 seconds.

If any error occurs during the communication with the WAS (timeout, HTTP error, orprocessing error returned by the WAS), the Open Client Server falls back with the normalmessage flow, that is, it tries to log in the user on the Application Server, and log the error(at the WARNING level, in the OpenClientServer channel) in the Open Client Server log.


30/37



5.2.1 Open Client Server Web-based External Authentication Message Flow

Figure 13 Open Client Server Web-based External Authentication Message Flow

As can be seen inFigure 13,the Open Client Server relies on the fact that the ApplicationServer accepts login requests without passwords from the Open Client Server host toinitialize a session (OCI-C or OCI-P) once the user has been successfully authenticatedthrough the WAS.

5.2.2 Configuration

The use of a WAS as an authentication mechanism can be configured at the Open ClientServer CLI in the following context:

AS_CLI / OpenCl i ent Server> getcl i ent Por t = 2208capProxy = t rueossProxy = t ruensProxy = t rueconnRetryI nt erval Seconds = 60

syst emDomai n = what ever. broadsof t . com useExternalAuthentication = true

externalAuthenticationUrl = http://server/servlet/authenticationservlet

provi si onToSecondary = f al se

When using a WAS, the useExternalAuthentication flag must be set to true, and theexternalAuthenticationUrl should be set to the address of the server, servlet, or commongateway interface (CGI) application that answers to WAS-compliant requests.

Client OCS WAS AS

1. AuthenticationRequest

2. AuthenticationRequest

3. Auth. Response

4. Auth. Response

5. LoginRequest6. LoginRequest

8. LoginRequest (w/o pwd)

Session initialized

9. LoginResponse

7. LoginResponse

10. LoginResponse


31/37



NOTE: If the flag is set to false, theexternalAuthenticationUrl parameter has no effect.However, if the flag is set to true, the URL parameter must point to a valid WAS address.

5.2.3 WAS Authentication Request and Response Specif ication

An authentication request is sent by the Open Client Server to the WAS, using parametersto the URL that are specified by the customer. Following is a list of parameters sent by theOpen Client Server:

Parameter Possible Values

Operation authenticate

userId @ as specified in clientsauthentication request.

The Open Client Server adds the default systemdomain if no one is specified in the clientsauthentication request.

Therefore, if the customer provisioned a URL for external authentication, that ishttp://server/servlet/authenticationservlet,the HTTP request would be sent to the WAS asa get request with the following URL:

ht t p: / / server / servl et / aut hent i cat i onservl et ?operat i on=aut hent i cat e&user I d=user @domai n

The WAS is expected to respond with an XML message in the body of the HTTPresponse, with the following format:

The nonce is returned by the WAS in the AuthenticationResponse. The errorCode isexpected to be 0 when the authentication is successful. In case of error, the WAS isexpected to return an XML document in the same format, with nonce being set to emptystring and an error code that is one of the following values:

Error Code Error

1 User not found.

3 Error processing request.

Would be used, for example, if SiteMinder couldnot be reached, and so on.

5.2.4 WAS Login Request and Response Specification

A login request is sent by the Open Client Server to the WAS using parameters to theURL that are specified by the customer. Following is a list of parameters sent by the OpenClient Server:


operation login
http://server/servlet/authenticationservlethttp://server/servlet/authenticationservlethttp://server/servlet/authenticationservlet


32/37




userId @ as specified in clientsauthentication request.

The Open Client Server adds the default systemdomain if no one is specified in the clients

authentication request.

hashedPwd The hashed password, as specified in the originallogin request sent by the client and computedusing MD5 hashing and the nonce valuereturned by the WAS.

If the customer provisioned a URL for external authentication, that ishttp://server/servlet/authenticationservlet,the HTTP request would be sent to the WAS asa get request with the following URL:

ht t p: / / server / servl et / aut hent i cat i onservl et ?operat i on=l ogi n&user I d=user@domai n&hashedPwd=abc123def

The WAS is expected to respond with an XML message in the body of the HTTP

response, with the following format:

The errorCode is expected to be 0 when the authentication is successful. In case oferror, the WAS is expected to return an XML document in the same format, with an errorcode that is one of the following values:

Error Code Error

1 User not found.

2 Invalid password provided.

3 Error processing request.

Would be used, for example, if SiteMinder could not be reached, and so on.
http://server/servlet/authenticationservlethttp://server/servlet/authenticationservlethttp://server/servlet/authenticationservlet


33/37



6 Third-Party System Integration

In a third-party system integration scenario, you can bypass the authentication processand automatically accept login requests from trusted hosts using the externalauthentication network access control list (ACL) of the Open Client Server. In this case, itis the responsibility of the third-party system to make sure users are authenticated.BroadWorks assumes in this case that incoming requests are trusted from the systemhosting the third-party application.

Figure 14 OCI External Authentication for Third-Party Systems

Any trusted host from which you want login requests (OCI-P or OCI-C) without passwordsto be accepted automatically must be added to the access list, providing its static IPaddress. In this case, the authentication request preceding the login request (thetransaction used to obtain a nonce to encrypt the password) is not required, since thepassword does not need to be provided. The session can be established directly bysending a login request.

The ACL is accessible through the CLI. On the Application Server, trusted hosts can beadded to the access list using the following context: For login requests going through theOpen Client Server (OCS), trusted hosts can be configured using the CLI in the followingcontext:

XSP_CLI / Appl i cat i on/ OpenCl i ent Server / External Aut hent i cat i on/ AccessCont rolLi st>

Third-PartySystem

OCS


34/37



7 Appendix A: Integration with Netegrity SiteMinder

The following sections describe specific concerns regarding the integration of BroadWorksExternal Xtended Services Platform and/or collocated Web Server on the ApplicationServer with Netegrity SiteMinder. In addition, there is a description of the custom HTTPheaders external authentication mechanism in section4.2.1 External Authentication usingEmbedded Agent.

7.1 Hardware Considerations

The Web Agent is integrated with the Apache Stronghold web server on the ExternalXtended Services Platform that fronts the Application Server machine. If an ExternalXtended Services Platform is not deployed, or if protection is required for the collocatedWeb Server, then the Web Agent can be installed on the Application Server machine aswell. To enforce access control, the Web Agent interacts with the policy server, where allauthorization and authentication decisions actually take place.

The policy server can be an existing server in the customers web portal deployment. It

can be installed on the External Xtended Services Platform or on a new machine that thecustomer provides and installs. Installing the policy server on the Application Servermachine is not recommended.

7.2 Authent ication Process

The Web Agent intercepts all user (browser) requests for resources (HTML files, JSPpages, servlets, graphics, and so on) and checks with the policy server as to whether therequested resource is protected. If the resource is unprotected, the access requestproceeds directly to the Xtended Services Platform.

If the resource is protected, the Web Agent determines which authentication method isrequired to access the requested resource. Typically, the credentials required are a nameand password, but the customer can decide to use any SiteMinder-supported

authentication scheme. The Web Agent challenges the users for their credentials,according to the authentication method required by the policy server. The users thenrespond with the appropriate credentials. The Web Agent passes these credentials backto the policy server, which uses them to authenticate the users against a user directory.

7.3 Authorization Process

When a user attempts to access a protected resource, the policy server first authenticatesthe user, as previously explained. Users are then authorized to access resources basedon policies. The Web Agent can also forward additional user-specific attributes, inparticular the user ID in the BroadWorks system, to the web application in the form of aresponse. A user is authorized as follows:

The SiteMinder agent sends the details of the HTTP request along with the usersidentity to the policy server for authorization.

The policy server determines which policies protect the resource in question andwhether the policies apply to the user attempting access.

The policy server communicates its decision to grant or deny user access along withthe applicable responses to the agent.

If the policy server grants access, the agent adds the user-specific attributes to theHTTPheader, which is then forwarded to the Application Server for processing.


35/37



7.4 Policy Server Installation

The policy server installation can be an existing installation shared with other parts of thecustomers web portal, or a new installation specifically for the BroadWorks webapplication. Connecting to an existing installation would be preferable, because it requiresless hardware resources and less maintenance.

Whether an existing policy server is used, or a new one is installed, the same policiesmust be created to protect the BroadWorks web application. The policy contains rules,which are assigned against a realm, which is a collection of resources. The policyrequired to protect a BroadWorks installation can be simple, with one realm that coversthe entire application. The complexity is in connecting to a user repository and obtainingthe user ID (and domain, if required) that must be passed to the BroadWorks webapplication as custom HTTP headers. When it is created, a policy is assigned againstagents, or more precisely, against agent identities, as an agent can have multipleidentities. For a BroadWorks installation, the agents have a single identity, and agentswithin the same cluster share the same policy.

7.5 Custom HTTP Headers

The ea_login.jsp JSPpage is expecting the user ID and domain information in the form ofcustom HTTPheaders, as shown inTable 1.

To authenticate the end user or administrator and obtain the custom HTTPheaderinformation, the policy server must connect to the customers user data repository, such asa Lightweight Directory Access Protocol (LDAP) directory server, NT domain, OpenDatabase Connectivity (ODBC) database, and so on. This is a customer-specificprocedure that requires custom development work.

Note that the custom HTTP headers are only needed for the ea_login.jsppage.Therefore, the realm of the BroadWorks web application can contain two rules: onecovering everything with no Response, and another covering the ea_login.jsppage with aResponse providing the custom HTTPheaders. An additional rule may be needed toblock the /Loginpage, as described in section4.2.3.2 Unauthorized Login Attempts

through BroadWorks Login Page.

7.6 Sharing Policy Server Polices Across Clusters

Depending on customer preferences, it might be possible to reuse the same policy serverand even the same policy for multiple Application Server clusters.

7.7 Policy Server High Availabili ty

For both installation scenarios, that is, reusing an existing policy server installation orhaving a new policy server installation, it is assumed that policy servers are redundant (tosatisfy general BroadWorks high availability requirements). In accordance with the wayhigh availability is configured in the remainder of the BroadWorks system, it is

recommended to have the policy servers in failover mode, rather than round-robin mode.


36/37



7.8 Web Agent Installation

The Web Agent is installed on the same server as the External Xtended ServicesPlatform. If protection is needed for the collocated Web Server on the Application Server,another Web Agent instance must be installed on the Application Server machine. The

version of the policy server and the Web Agent depends on compatibility with theSiteMinder version used in the rest of the customers site. In addition, a Web Agent mustbe available for the Xtended Services Platform used by the current release ofBroadWorks.

7.9 Single Sign-On Configuration

Depending on the choice of domain names in the remainder of the customers web portal,the Web Agent should be installed so as to support Single Sign-On either within onedomain or across multiple domains. If Single Sign-On spans multiple domains, a speciallyconfigured SiteMinder Agent serves as a cookie provider. The customer is expected toset up the cookie provider Agent.

According to the SiteMinder documentation, when using replicated user directories withnon-replicated policy stores in a Single Sign-On setup, the user directory must be namedidentically for all policy stores.

In addition, the policies established to protect the BroadWorks web application must notrequire a higher level of protection than the realm the end user or administrator is comingfrom elsewhere in the customer's portal. Otherwise the Web Agent forces the end user oradministrator to re-enter their credentials upon accessing the BroadWorks realm.

7.10 Agent Key Management

Web Agents use agent keys to encrypt and decrypt all SiteMinder cookies. The agentuses the agent key to encrypt cookies before sending them to a users browser and todecrypt cookies when it receives them from other Web Agents. All Web Agents need to

be aware of the same keys, and the keys must be set to the same value for all agentscommunication with a policy server. This is particularly important for agents in a SingleSign-On environment, which is preferred for a BroadWorks setup.

Therefore, agent key management must be integrated with other SiteMinder componentsin the customers web portal, according to the SiteMinder Policy Server Operations Guide.The specifics are dependent on the SiteMinder release number.

7.11 Provisioning End Users and Administrators

It is assumed that the SiteMinder Web Agent instances on External Xtended ServicesPlatforms that front an Application Server cluster connect to an existing SiteMinder policyserver that contains profiles of BroadWorks users (end users and administrators). This isalso known as a Single Sign-On configuration.

For each end user and administrator known to the policy server, a corresponding entitymust be created in the BroadWorks system, for instance, through the OCI API. Theseentities are created without specifying a password, as they are accessing the BroadWorksweb application through the Web Agent-protected External Xtended Services Platform thatfronts the Application Server.


37/37

7.12 Levels of Protection

The Web Agents are configured to offer the same level of protection for the JSP pagesand servlets in the BroadWorks web application, regardless of the user type (end user oradministrator). Once a BroadWorks end user or administrator accesses the entry point

into the web application, further authorization is performed on a per-page basis based onthe users authorization level in the BroadWorks system. This simplifies the setup of theWeb Agents, while providing an adequate level of protection.

For an increased level of protection, the different types of users in BroadWorks wouldneed different policies in the policy server. When this redundant level of protection isrequired, BroadSoft provides filters to set up the rules for the different policies (end user,department administrator, and so on), which would probably be in the form of hierarchicalrealms.

Last but not least, the web login authorization level protection is still in place, whereby theApplication Server logic refuses access to the web application through the ExternalXtended Services Platform to any administrator of a level higher than the maximum presetin the BroadWorks CLI. (The setting is found in the

AS_CLI/System/ClientSession/LoginAuthLevel level). Usually, a group administrator isthe highest level of administrator for which external web access should be allowed.

7.13 Session Management

The policy server component ensures session management, including session durationtracking. The BroadWorks web application web session duration tracking mechanismdoes not apply to end users, department, group, or service provider administrators whenexternal authentication password rules are enabled.

7.14 Cross-site Scripting and Escaped Characters in URLs

By default, SiteMinder is set to block any URLs that contain escaped characters. For

example, the

Documents

BW ExternalPortalIntegrationGuide R170