BlueZone Integration Server

BlueZone Integration Server Administrator s Guide Version 6.2 January 2013 BZIS-0602-AG-01

Notices Edition Publication date: January 2013 Book number: BZIS-0602-AG-01 Product version: BlueZone Integration Server Version 6.2 Copyright Rocket Software, Inc. or its affiliates 2010-2013. All Rights Reserved. Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners. Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. License agreement This software and the associated documentation are proprietary and confidential to Rocket Software,Inc. oritsaffiliates,arefurnishedunderlicense,andmaybeusedandcopiedonlyin accordance with the terms of such license. Note This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product. Contact information Website: www.rocketsoftware.com Rocket Software, Inc. Headquarters 774 th Avenue,Suite100 Waltham, MA 02451 1468 USA Tel: +17815774321 Fax: +16176307100 2

Contacting Global Technical Support If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or read answers to FAQs. The Rocket Customer Portal is the primary method of obtaining support. TologintotheRocketCustomerPortal,goto: www.rocketsoftware.com/support IfyoudonotalreadyhaveaRocketCustomerPortalaccount,youcanrequestonebyclicking Need an account? on the Rocket Customer Portal login page. Alternatively, you can contact Global Technical Support by email at support@rocketsoftware.com. 3

Contents Notices...2 ContactingGlobalTechnicalSupport...3 Chapter1: BlueZoneIntegrationServerintroduction...5 Applicationoverview...5 Architecture...6 Chapter2: InstallingandconfiguringBlueZoneIntegrationServer...8 Installingthird-partysoftware...8 InstallingBlueZoneIntegrationServer...9 InstallingandconfiguringBlueZoneWeb-to-Host...9 Verifyingtheoverridevalues...10 Modifyingthedefaultdatasource...10 ConfiguringtheBzIsuserdataproviders...11 ConfiguringtheCSVdataprovider...11 ConfiguringtheMicrosoftSQLServerdataprovider...12 Automaticallyappendingadomainname...14 Connectingtwodataproviders...14 AuthenticatingWindowsdomains...15 Customizingtheloginoptions...17 Customizingtheredirectoptions...18 Customizingthesignonpageappearance...18 CustomizingtheLoginController...18 Customizingthelaunchpageredirect...20 ConfiguringautomaticWindowssignon...20 InstallingandconfiguringBlueZoneIntegrationServerAdministrator...20 ConfiguringtheBzIsAdmindatasources...21 ConfiguringtheCSVdatasource...21 ConfiguringtheMicrosoftSQLServerdatasource...21 ConfiguringforwardingDAOs...23 Changingthedefaultpasswords...23 Chapter3: UsingBlueZoneIntegrationServer...25 LoggingintoBzIs...25 Modifyinguserdata...25 Chapter4: UsingBlueZoneIntegrationServerAdministrator...26 LoggingintoBzIs...26 Addinguserdata...26 Chapter5: Logfiles...27 Chapter6: Messagepages...29 Relatedinformation...30 Index...31 4

Chapter 1: BlueZone Integration Server introduction Welcome to the BlueZone Integration Server Administrator s Guide. This guide provides installation and configuration instructions of BlueZone Integration Server(BzIs) and the BlueZone Integration Server Administrator(BzIs Admin) component. BlueZone Integration Server BlueZone Integration Server is a Java web application that works with BlueZone Web-to-Host. The BlueZone Web-to-Host Wizard generates static HTML websites that distribute the BlueZone emulators from a web server to client desktop machines. BzIs merges data from your corporate data sources into standard BlueZone Web-to-Host sites, making them dynamic and allowing for the insertion of user specific data, such as LU/device names. BzIs also supports a number of login authentication schemes. BlueZone Integration Server Administrator BlueZone Integration Server Administrator is a Java web application that works with BlueZone Integration Server. The BzIs Admin is an optional component that provides a web-based interfacetoedittheuserdata. ItcanbeinstalledonthesameserverasBzIsoronadifferent serverthatpointstothesamedatabaseasbzis. Application overview This topic provides a general overview of how BlueZone Integration Server works. 1. The BlueZone Web-to-Host Wizard generates HTML files that allow for the installation, configuration, and launching of BlueZone emulators through a web browser. The behavior of BlueZone is controlled through an HTML <object> tag, which typically looks something like this: <object classid="clsid:037790a6-157n6-11d6-903d-00105aabadd3" codebase="../controls/sglw2hcm.ocx#version=-1,-1,-1,-1" id="bzw2hcm" standby="initializing BlueZone Web-to-Host " height="250" width="575" > <param name="md_s1" value="mfd.zmd" /> <param name="md_s1_lu" value="ou812" /> <param name="md_s1_port" value="99" /> TheLUname(orDevicenameinaniSeriesDisplay)isspecifiedas OU812 andtheportis 99. 2. The administrator has a database table, CSV file, or LDAP database that contains the following data: Table 1: Example CSV file contents 1 2 3 4 5 6 7 UserID Password EmailAddress Site Page LuName Port JSmith secret JSmith@domain.com Rocket Dev MyLu 23 5

Chapter 1: BlueZone Integration Server introduction When the site is create in the BzIs directory, the administrator changes the <object> tag to use the BzIs placeholder symbols: <param name="md_s1_lu" value="%s6% %s6%" /> <param name="md_s1_port" value="%s7% %s7%" /> The placeholder%s6% specifies column 6 and%s7% specifies column 7. In Table 1:Example CSVfilecontentsnoticethatcolumn6containstheLUnameandcolumn7containsthe port. 3. TheuserJSmithlogsintoBzIs. Iftheauthenticationpasses,thedataispulledfromthe data source and the user is redirected to the BlueZone Web-to-Host site. When the page that contains the above <object> tag is retrieved, BlueZone Integration Server scans the page for placeholders and replaces them with the data from the corresponding column. In this example, the following section of the <object> tag: <param name="md_s1_lu" value="%s6% %s6%" /> <param name="md_s1_port" value="%s7% %s7%" /> is converted to: <param name="md_s1_lu" value="mylu" /> <param name="md_s1_port" value="23" /> 4. After this conversion happens, the BlueZone emulator starts and assigns the LU of MyLu intothesessionthatconnectstothehostonport23. Architecture The default location of BzIs is[tomcat]/webapps/bluezone. The default location of BzIs Admin is[tomcat]/webapps/bzisadmin. Where [tomcat] is the Apache Tomcat installation location. For example, C:\Program Files\Apache Software Foundation\Tomcat 6.0. The following table shows the BlueZone Integration Server directory structure: 6

Architecture Table 2: BlueZone Integration Server and BlueZone Integration Server Administrator directory structure Subdirectory or file /logs /META-INF /Sites /WEB-INF /static login.html logout.html signon.bz /signon-windows.bz /redirect.jsp /splitter.bz Description ContainstheBzIslogfiles. Theselogfilesarecreatedonthefirstrun. Created by the JAR process. Contains metadata about the BzIs WAR. Can be deleted. Contains sites created by the BlueZone Web-to-Host Wizard. Create all sites in this folder. Contains metadata about the BzIs web application, including java class files, configuration files, data files,.jsp files, and binary libraries. Contains any files that need to be referenced from within BzIs that are notdynamic,suchaspngs,gifs,jpgs,andsoon. Virtual file. Performs login operations, including authentication, retrieval of user data, session creation, and redirection for success and failure. All calls to this file are handled by com.bluezone.w2h.controllers.logincontroller, which is configured in dispatcher-servlet.xml. Virtual File. All calls to this file are handled by com.bluezone.w2h.controllers.logoutcontroller, which is configured in dispatcher-servlet.xml. Virtual file. The standard login screen if Integration Server is configured for login/password. This virtual file maps to the physical file at /WEB-INF/jsp/signon.jsp. By default, signon.bz will post the login/password to login.html. This login information is passed into splitter.jsp by default. You can host your sign on screen anywhere and direct it into Integration Server. Virtual file. Uses an Applet to determine windows user name and computer name and redirects to the login process. The default welcome page. By default it redirects to signon.bz. Virtual file. This page directs the log in to the correct location. Modify thecodeinthispagetochangehandlingoflogins. Thisvirtualfile maps to the physical file at/web-inf/jsp/splitter.jsp. 7

Chapter 2: Installing and configuring BlueZone Integration Server To install and configure BlueZone Integration Server, installation and configuration consists of the following basic steps: 1. Install third-party software. 2. Install BlueZone Integration Server. 3. Install and configure the BlueZone Web-to-Host Wizard. 4. Modify the default data source. 5. Configure the user data providers. 6. Optional: Configure the login options. 7. Optional: Install and configure the BzIs Admin component. Installing third-party software BlueZone Integration Server and the BlueZone Integration Server Administrator component can beinstalledonthesameserverorondifferentservers. IfyouinstalltheBzIsAdmincomponent on a different server, both servers must meet these requirements. Servlet container Any servlet container By default, BlueZone Integration Server uses Apache Tomcat 6.0 and documents the installation and URL locations using the Tomcat paths. On Windows platforms, install the 32-bit/64-bit Windows Service Installer package. Tomcat must be installed to a path such as C:\Program Files\Apache Software Foundation\Tomcat 6.0. This location will be referred to as[tomcat]. Take note of the path to[tomcat], the port used, and the administrator password. Test the installation by going to the Tomcat URL, for example, http://yourserver.com:8080/. You should see the Tomcat default page. This location will be referred to as http://[tomcat-url]/. Java 1.6, or later Microsoft SQL Server (optional) BzIs and the BzIs Admin component are shipped with optional data provider classes that create a connection to a Microsoft SQL Server. The data provider classes require the Microsoft SQL ServerJDBCDriver2.0,aType4JDBCdriver. Thedriverisnotredistributableandcannotbe included in the BzIs or BzIs Admin package. IfyouwanttoconnecttoaMicrosoftSQLServer,youmustdownloadthedriverfromthe Microsoftwebsite,andinstallitonthesameserverasBzIsorBzIsAdminbeforeusingthedata providers. The following table lists the data provider classes that are supplied with each component. Refer to Configuring the Microsoft SQL Server data provider, on page 12 and Configuring the Microsoft SQL Server data source, on page 21 for more information on these provider classes. 8

Installing BlueZone Integration Server Table 3: Data provider classes Component Data provider class type BzIs BzIs Admin Login data provider class User data provider class Data provider class name com.bluezone.w2h.data.bzw2hsqllogindataprovider com.bluezone.w2h.data.mssqluserdao Security Depending on the configuration of BzIs and BzIs Admin, passwords can be entered by the users. When using passwords, it is best if the BzIs and BzIs Admin connections are SSL-secured(HTTPS). Installing BlueZone Integration Server Consult your server s documentation for more detailed instructions on installing web applications. 1. In the BlueZone CD image, open the BlueZone Integration Server folder. 2. Copy the BlueZone.war file to the[tomcat]/webapps/ folder. The WAR file expands to create the/bluezone directory. 3. Test the installation: a. In a web browser, go to http://[tomcat-url]/bluezone/. The BlueZone Integration Server sign on screen opens. b. Make note of this URL. The[tomcat]/webapps/BlueZone/ file path maps directly to http://[tomcat-url]/bluezone/. Installing and configuring BlueZone Web-to-Host 1. Install the BlueZone Web-to-Host Wizard on the server that hosts BzIs or on a computer that has access to the[tomcat]/webapps/bluezone/sites/ folder. Refer to the BlueZone Web-to-Host Administrator s Guide for more information on the Web-to-Host installation process. 2. Create a site: a. Open the Web-to-Host Wizard and click Create. b. Navigate to[tomcat]/webapps/bluezone/sites/. c. IntheFileNamefield,typeanameforthesite,forexampletypeDemo,andclickOpen. d. In the Confirm Installation window, click OK. 3. Create a launch folder: a. In the Sites window, click Next. b. Click Create. c. IntheFolderNamefield,typeanameforthelaunchfolder,forexampletypePage, and select a distribution type. d. Click OK. 4. Create a session: 9

Chapter 2: Installing and configuring BlueZone Integration Server a. In the Launch Folders window, click Next. b. Click Create. c. In the New BlueZone Session window, select a session type, for example select Mainframe, and click OK. d. Typeanameforthesession,forexampletypeMFD,andclickOK. e. In the BlueZone emulator, in the Connection Name field, type a host connection name. For example, type MyHost. f. In the Host Address field, type the host address. For example, type myhost.mydomain.com. g. Click OK twice. h. Save and close the BlueZone Display session. 5. Optional: Set the override value(s): a. In the Web-to-Host Wizard Sessions window, click Overrides. b. Determine the session value(s) that will be overridden. c. Inthefield(s),type%sn%,wherenisthecorrespondingcolumnnumberinthedata source. Forexample,intheLUNamefield,type%s6%tomaptocolumn6inthedatasource.csv file. d. Click OK. Verifying the override values If you created an override value when you configured the Web-to-Host session, verify that thevaluewasmodifiedinthelaunchpage. 1. Navigate to the[tomcat]/webapps/bluezone/sites/demo/page/ folder. 2. Open the launch_x.htm file in a text editor. 3. Ensurethattheoverridevaluesareinthelaunchpagefile. Forexample,ifyousettheLU Nameoverridevalueto%s6%,thefollowinglinewouldbeinthefile: <parm name="md_s1_lu" value="%s6%" /> Ifthelaunch_x.htmfiledoesnotcontainthisline,ensurethatyousettheLUnameoverride value when you configured Web-to-Host. Refer to Installing and configuring BlueZone Web-to-Host, on page 9 for more information. 4. Close the file. Modifying the default data source BlueZone Integration Server uses a comma separated values(.csv) file as the default data source. IfyouplantouseaMicrosoftSQLServer,youdonotneedtomodifythedefaultdata source. 1. Navigate to[tomcat]/webapps/bluezone/web-inf/data. 2. Open the bzw2h.csv file in Microsoft Excel, or a text editor. 3. Addanewuser. Forexample,theusertestwasadded: 10

Configuring the BzIs user data providers Table 4: Sample bzw2h.csv file contents 1 2 3 4 5 6 UserID Password EmailAddress Site Page LuName demo demo demo@domain.com w2h demo g7 test test test@domain.com Demo Page OU812 The value in column 6 will be placed in the BlueZone Integration Server placeholder%s6% in the[tomcat]/webapps/bluezone/sites/demo/page/launch_x.htm file. 4. Ensurethatthevaluesincolumns4and5matchavalidsiteandlaunchfolder. These values were created when Web-to-Host was configured. Refer to Installing and configuring BlueZone Web-to-Host, on page 9 for more information. 5. Save and close the file. Configuring the BzIs user data providers There is a BzUserDataProvider interface: com.bluezone.w2h.data.bzuserdataprovider. The LoginController will accept any BzUserDataProvider that uses this interface. You can write and supply your own BzUserDataProvider. You must configure either the CSV or Microsoft SQL Server data provider: Configure the CSV data provider(bzw2hcsvlogindataprovider) Configure the Microsoft SQL Server data provider(bzw2hsqllogindataprovider) The remaining data providers are optional: Automatically append a domain name(bzappendinglogindataprovider) Connect two data providers(bzchainedlogindataprovider) Authenticate Windows domains(bzldaplogindataprovider) Configuring the CSV data provider The default data provider is BzW2hCsvLoginDataProvider. 1. Navigate the[tomcat]/webapps/bluezone/web-inf folder. 2. Open the applicationcontext.xml file in a text editor. 3. Locate the bzw2hcsvlogindataprovider bean: <bean id="bzw2hcsvlogindataprovider" class="com.bluezone.w2h.data.bzw2hcsvlogindataprovider"> <property name="bzw2hcsvparser" ref="bzw2hcsvparser" /> <property name="matchignorescase" value="true" /> </bean> 4. Modify the following properties as needed: Property bzw2hcsvparser matchignorescase Value Reference to the parser bean. Determines if the login is case-sensitive. Set to false for case-sensitive login. 5. Locate the bzw2hcsvparser bean: 11

Chapter 2: Installing and configuring BlueZone Integration Server <bean id="bzw2hcsvparser" name="bzw2hcsvparser" class="com.bluezone.w2h.data.bzw2hcsvparser"> <!-- path to the CSV file that contains BzW2h formatted data --> <property name="csvresource" value="/web-inf/data/bzw2h.csv" /> <property name="emptycolumnplaceholder" value="" /> </bean> 6. Modify the following properties as needed: Property csvresource Value Location of the.csv file. emptycolumnplaceholder Contains the string that will replace any columns that are empty. Thevalueisemptybydefault. 7. Save and close the file. Configuring the Microsoft SQL Server data provider Use the bzw2hsqllogindataprovider to connect to a Microsoft SQL Server. Prerequisite Install the Microsoft SQL Server JDBC Driver 2.0 on the server that is hosting BzIs. Microsoft does not allow the redistribution of its SQL Server drivers. You must download the driver from the Microsoft website and install it to use this data provider. Procedure 1. Create a database table using the following format: Column Contents 1 User ID(string) 2 Password(string) 3 Email address(string) 4 Site name(string) 5 Page name(string) 6-16 Arbitrary data(string) 2. Name the table BzUsers. 3. Navigate to the[tomcat]/webapps/bluezone/web-inf folder. 4. Open the applicationcontext.xml file in a text editor. 5. Locate the mssqldatasource bean: <!-- bean id="mssqldatasource" class="org.springframework.jdbc.datasource.drivermanagerdatasource" p:driverclassname="com.microsoft.sqlserver.jdbc.sqlserverdriver" p:url="jdbc:sqlserver://yourserver.com;databasename=bluezone" p:username="admin" p:password="secret" /--> 6. Uncomment the mssqldatasource bean and modify the following properties: 12

Configuring the Microsoft SQL Server data provider Property url username password Value PathtotheSQLServerandthedatabasename SQL Server user name SQL Server password 7. Locate the BzW2hSqlLoginDataProvider bean. The default definition of this bean is commented out by default: <!--bean id="bzw2hsqllogindataprovider" class="com.bluezone.w2h.data.bzw2hsqllogindataprovider"> <property name="datasource" ref="mssqldatasource" /> <property name="passwordencrypted" value="true" /> <property name="passwordhasher" ref="bzw2hshapasswordhasher" /> <property name="usertablename" value="bzusers" /> <property name="useridfieldname" value="userid" /> <property name="userpasswordfieldname" value="password" /> </bean--> 8. Uncomment the BzW2hSqlLoginDataProvider bean and modify the following properties: Property datasource passwordencrypted Value Name of the data source The available values are: true: The data provider uses the provided passwordhasher property to encrypt or hash the password. false: Thepasswordissentintheclear. passwordhasher Implements the com.bluezone.w2h.crypto.passwordencryptor interface. There are two implementations provided: BzW2hBlowfishPasswordHasher class BzW2hShaPasswordHasher class Bothoftheseclassesaredefinedbydefaultin the applicationcontext.xml file. usertablename Name of the database table created in step 1. useridfieldname userpasswordfieldname The name of the column in the BzUsers table that contains User ID. The name of the column in the BzUsers table that contains Password. 9. Save and close the file. 10. In the[tomcat]/webapps/bluezone/web-inf folder, open the dispatcher-servlet.xml fileinatexteditor. 11. Locate the logincontroller bean: <bean id="login" name="logincontroller" class="com.bluezone.w2h.controllers.logincontroller"> <property name="bzuserdataprovider" ref="bzw2hcsvlogindataprovider" /> 12. Change ref="bzw2hcsvlogindataprovider" to ref="bzw2hsqllogindataprovider". 13. Saveandclosethefile. 13

Chapter 2: Installing and configuring BlueZone Integration Server 14. Restart Tomcat. Automatically appending a domain name Use the BzAppendingLoginDataProvider to append text(usually a domain name) to a user ID and pass the result into another BzLoginDataProvider. This was written originally for use with the BzLdapLoginDataProvider because the backing LDAP server often needs a PrincipalName in the form user@domain.com. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf folder. 2. Open the applicationcontext.xml file in a text editor. 3. Locate the bzappendinglogindataprovider bean. By default, the definition of this bean is commented out: <bean id="bzappendinglogindataprovider" class="com.bluezone.w2h.data.bzappendinglogindataprovider"> <property name="delegate" ref="bzldaplogindataprovider" /> <property name="append" value="@rocketsoftware.com" /> </bean> 4. Modify the following properties: Property delegate append Value The BzLoginDataProvider that the updated user ID and password combination are forwarded to. ThetexttoappendtotheuserID. 5. Save and close the file. Connecting two data providers Use the BzChainedLoginDataProvider to link two BzLoginDataProviders. First, the authentication provider is called and processes the user login ID and password. If the authentication provider succeeds, then the user login ID and password are passed into the user data provider. The user data provider then pulls custom user data from the database and passes it on. This allows user authentication information to be stored in one location(perhaps an LDAP oractivedirectoryserver)andthecustomdatatobestoredinaseconddatabase. Note The authenticationprovider can be any BzLoginDataProvider, including a BzAppendingLoginDataProvider which front ends another authenticationprovider. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf folder. 2. Open the applicationcontext.xml file. 3. Locate the bzchainedlogindataprovider bean. <bean id="bzchainedlogindataprovider" class="com.bluezone.w2h.data.bzchainedlogindataprovider"> <property name="authenticationprovider" ref="bzldaplogindataprovider" /> <property name="userdataprovider" ref="bzw2hsqllogindataprovider" /> </bean> 4. Modify the following properties: 14

Authenticating Windows domains Property authenticationprovider userdataprovider Value A reference to a configured BzLoginDataProvider bean to handle authentication. A reference to a configured BzLoginDataProvider bean to handle data retrieval. 5. Save and close the file. Authenticating Windows domains Use the BzLdapLoginDataProvider to authenticate to Windows domains through Active Directory and to LDAP servers. For more information on configuring LDAP servers, refer to [tomcat-url]/bluezone/ldap.bz. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf folder. 2. Open the applicationcontext.xml file in a text editor. 3. Locate the BzLdapLoginDataProvider bean: <bean id="bzldaplogindataprovider" class="com.bluezone.w2h.data.bzldaplogindataprovider"> <property name="anonymousbind" value="false" /> <property name="connectiontimeoutinmilliseconds" value="1000" /> <property name="bzuseridfilterargkey" value="bzuserid" /> <property name="bzuserpasswordfilterargkey" value="bzuserpassword" /> <property name="filter" value="(objectclass=*)" /> <property name="filterargs"> <list> <value>bzuserid</value> <value>bzuserpassword</value> </list> </property> <property name="providerurl" value="" /> <property name="searchbase" value="" /> <property name="searchcontrols" ref="ldapsearchcontrols" /> <property name="securityauthentication"> <null /> </property> <property name="securityprincipal"> <null /> </property> <property name="securitycredential"> <null /> </property> <property name="illegalcharsuseridstring" value="0x2c,0x2b,0x22,0x5c,0x3c,0x3e,0x3b,0x0a,0x0d,0x3d,0x2f" /> <property name="illegalcharspasswordstring" value="0x2c,0x2b,0x22,0x5c,0x3c,0x3e,0x3b,0x0a,0x0d,0x3d,0x2f" /> </bean> 4. Modify the following properties: 15

Chapter 2: Installing and configuring BlueZone Integration Server Property anonymousbind Value False by default. The switch to determine if getdata(userid) or getdata(userid,password) is used is set in LoginController.setPasswordRequired(boolean). Modify the setting in dispatcher-servlet.xml. To look up all users with no authentication: If getdata(userid) is called and AnonymousBind is true, then no security credentials are used when initializing the LDAP context, this is known as anonymous bind. Tolookupalluserswithasingleadminlogin: If getdata(userid) is called and AnonmymousBind is false, then the values of getsecurityprincipal and getsecuritycredential are used to initialize the LDAP context. To authenticate with values passed into getdata(userid, Password): If getdata(userid,password) is called, then the value of AnonymousBind is ignored and the passed values are always used to authenticate. connectiontimeoutinmilliseconds The number of milliseconds until the connection attempt times out. bzuseridfilterargkey bzuserpasswordfilterargkey filter filterargs providerurl searchbase searchcontrols If this key is listed in filterargs, then it will be replaced with the user ID passed into getdata(userid,pass). If this key is listed in filterargs, then it will be replaced with the password passed into getdata(userid,pass). See LDAP filter query references for structure of this filter string. This filter can contain replaceable values, oftheform{0}, {1}, andsoon. Thestring{0}willbe replaced with filterargs[0] and so on. See javax.naming.directory.dircontext.search() for the exact rules of the replacement. This allows for thepassingofbinarydataandsoon. The list of arguments to the filter to replace the placeholders: {0},{1}, and so on. The URL of the ldap server including port. For example, ldap://ldap.virginia.edu:389 The base DN to search. Forexample,o=University of Virginia,c=US The SearchControls object reference. 16

Customizing the login options Property securityauthentication Value The type/mode of authentication. See javax.naming.context.security_authentication for values,"none", "simple", "strong". Use <null /> for default behavior. Default behavior: If AnonymousBind is true, then no authentication is passed and the Context.SECURITY_AUTHENTICATION="none". If AnonymousBind is false then either the SecurityPrincipal and SecurityCredential, or the BzUserId and BzUserPassword, are passed and the Context.SECURITY_AUTHENTICATION="simple". securityprincipal securitycredential illegalcharsuseridstring illegalcharspasswordstring A user ID. Used with AnonymousBind. A password. Used with AnonymousBind. Specifies the illegal characters for use as a user login ID or a user password. Disallowing these characters prevents LDAP injection attacks. The BzLdapLoginDataProvider will reject attempts to use these characters as a login ID or password. ANSI/Unicode Hex values are required, '0x' prefix optional. The following characters are disallowed by default: spaceor#characteratthebeginningofastring spacecharacterattheendofastring, comma 0x2C + plus sign 0x2B " double quote 0x22 \ backslash 0x5C < left angle bracket 0x3C > right angle bracket 0x3E ; semicolon 0x3B LF line feed 0x0A CR carriage return 0x0D = equals sign 0x3D / forwards slash 0x2F 5. Save and close the file. Customizing the login options The following login options can be customized: Redirect page options Login screen appearance 17

Chapter 2: Installing and configuring BlueZone Integration Server LoginController options Launch page redirect Automatic Windows sign on Customizing the redirect options Youcanchangetheorderofthewelcomefilelist. Thewelcomefilelistdeterminestheorder thatthepagesarevisited. Or,youcanchangethefilethatthedefaultredirectpageuses. Tochangethecontentsororderofthewelcomefilelist: Navigate to the[tomcat]/webapps/bluezone/ folder. Opentheweb.xmlfileinatexteditor. Locate the <welcome-file-list> node: <welcome-file-list> <welcome-file>redirect.jsp</welcome-file> <welcome-file>index.bz</welcome-file> <welcome-file>default.htm</welcome-file> <welcome-file>index.html</welcome-file> </welcome-file-list> Modifythefilelistcontents,orderofthefiles,orboth. Saveandclosethefile. Tochangethefilethatthedefaultredirectpageuses: Navigate to the[tomcat]/webapps/bluezone folder. Opentheredirect.jspfileinatexteditor. By default, the redirect.jsp file redirects to the signon.bz, as shown below: <% response.sendredirect("signon.bz"); %> Modify the redirect file. Saveandclosethefile. Customizing the sign on page appearance Thesignon.jspfilecontrolstheappearanceofthesignonpage. Youcanmodifythisfileto changethelookandfeelofthesignonpageinthebrowser. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf/jsp folder. 2. Open the signon.jsp file in a text editor. 3. Edit the file. 4. Save and close the file. Customizing the LoginController The LoginController contains the properties that define the login options. You can modify or replace the default LoginController. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf folder. 2. Open the dispatcher-servlet.xml file in a text editor. 3. Locate the login bean. The following is the default definition: 18

Customizing the LoginController <bean id="login" name="logincontroller" class="com.bluezone.w2h.controllers.logincontroller"> <property name="bzuserdataprovider" ref="bzw2hcsvlogindataprovider" /> <property name="bzuseridkey" value="bzuserid" /> <property name="bzuserpasswordkey" value="bzuserpassword" /> <property name="bzuserdatakey" value="bzuserdata" /> <property name="loginokredirect" value="splitter.bz" /> <property name="loginfailedredirect" value="/msg-loginfailed.html" /> <!-- PasswordRequired If false, then BzUserDataProvider.getData(loginId) is called. If true, then BzUserDataProvider.getData(loginId,password) is called. --> <property name="passwordrequired" value="false" /> <property name="sessioncreationdenied" value="false" /> </bean> 4. Modify the properties as needed. The available properties and their use are: Property bzuserdataprovider bzuseridkey bzuserpasswordkey bzuserdatakey loginokredirect loginfailedredirect passwordrequired sessioncreationdenied Usage By default, this references the BzW2hCsvLoginDataProvider bean defined in the applicationcontext.xml file. This UserDataProvider can be changed. There are other default LoginDataProviders for connection to LDAP/ActiveDirectory and Microsoft SQL Server. Refer to ConfiguringtheBzIsuserdataproviders,onpage11formore information. When the user ID is received it is placed into the web application s session context under this key. When the user password is received it is placed into the web application s session context under this key. When the user s data is retrieved from the DataProvider, it is placed into a BzW2hUserDataRow object and placed into the web application s session context under this key. If the login succeeds, then the call is redirected to this file. By default, this is splitter.bz. You can modify this to point to custom code. If the login fails, then the call is redirected to this file. You can modifythistopointtocustomcode. RefertoMessagepages, on page 29 for more information. If false, then BzUserDataProvider.getData(loginId) is called. If true, then BzUserDataProvider.getData(loginId,password) is called. Advanced. If false, then the LoginController will create a web application session for this call. Default is false. If true, then the session must be created prior to the LoginController handling the request, or an error will be returned. 5. Save and close the file. 19

Chapter 2: Installing and configuring BlueZone Integration Server Customizing the launch page redirect The splitter.bz file is a virtual file, backed by the physical file splitter.jsp. By default, the splitter checks the user s session object for the BzW2hUserDataRow object. It calls BzW2hUserDataRow.getUserSite() and BzW2hUserDataRow.getUserPage(), builds the URL to thebluezonelaunchpage,andthenforwardstheusertothatpage,fromwhichthebluezone emulator is actually launched. You can modify the logic in this file, or perform additional data lookupstodirectthecallstoalaunchpage. 1. Navigate to the[tomcat]/webapps/bluezone/web-inf/jsp folder. 2. Open the splitter.jsp file in a text editor. 3. Modify file to redirect the user to any location, or to perform additional actions or setup of the session. 4. Save and close the file. Configuring automatic Windows sign on BlueZone Integration Server includes an automatic Windows sign on process. The signon-windows.bz page loads an applet that tests the user s system and determines the user IDandcomputername. Theuseristhenforwardedtotheloginprocess. Thisisnotasecuremethodofauthentication;itisintendedtobeusedinsituationswhere access to the emulator is allowed and authentication is performed on the emulator screen. It savestheuserfromhavingtoentertheiruseridtoaccesstheirsessions. Ifyouusethismethod, ensure to set LoginController passwordrequired field to false. Refer to Customizing the LoginController, on page 18 for more information. Tosetthisasthedefaultsignonmechanism: 1. Navigate to the[tomcat]/webapps/bluezone/ folder. 2. Open the redirect.jsp file in a text editor. 3. Change signon.bz to signon-windows.bz. 4. Save and close the file. Access this page at http://[tomcat-url]/bluezone/signon-windows.bz. Installing and configuring BlueZone Integration Server Administrator 1. If BzIs Admin is on a different server than BzIs, install the third-party dependencies. Refer to Installing third-party software, on page 8 for more information. 2. In a web browser, go to http://[tomcat-url]/ to test the Tomcat installation. TheTomcatdefaultpageopens. Ifitdoesnot,ensurethatTomcat6.0orlaterhasbeen installed on the server. 3. In the BlueZone CD image, open the BlueZone Integration Server folder. 4. Copy the BzIsAdmin.war file to the[tomcat]/webapps folder. 5. Verify that the installation is correct: a. Go to http://[tomcat-url]/bzisadmin/ b. Log in with the default Owner account: User name: owner Password: owner 20

Configuring the BzIs Admin data sources The BlueZone Integration Server Administrator Configure Data Source Error window opens. ThiswindowindicatesthatBzIsAdminisrunningbutitisnotconfiguredyet. 6. Configure a data source. 7. Change the default passwords. Configuring the BzIs Admin data sources YoumustconfigureeithertheCSVorMicrosoftSQLServerdatasourcefortheBzIsAdmin component. The forwarding DAO data source is optional. CSV data source Microsoft SQL Server data source Forwarding DAOs Configuring the CSV data source 1. Navigate to the[tomcat]/webapps/bzisadmin/web-inf folder. 2. Open the applicationcontext.xml file in a text editor. 3. Locate the bzw2hcsvparser bean: <bean id="bzw2hcsvparser" name="bzw2hcsvparser" class="com.bluezone.w2h.data.bzw2hcsvparser"> <!--path to the CSV file that contains BzW2h formatted data --> <property name="csvpath" value="c:/path/to/bzis/web-inf/data/bzw2h.csv" /> <property name="emptycolumnplaceholder" value="" /> </bean> 4. Modify the csvpath property to the fully qualified path to the.csv file. 5. Locate the bzw2huserdao bean: <bean id="bzw2huserdao" class="com.bluezone.w2h.data.bzw2hcsvuserdao"> <property name="csvparser" ref="bzw2hcsvparser" /> </bean> 6. Ensure that the bzw2huserdao is configured to use the BzW2hCsvUserDao class and with a reference to the parser: <bean id="bzw2huserdao" class="com.bluezone.w2h.data.bzw2hcsvuserdao"> <property name="csvparser" ref="bzw2hcsvparser" /> </bean> 7. Save and close the file. 8. Restart the application or the entire server. 9. LogintoBzIsAdminagainusingtheOwneraccount. Configuring the Microsoft SQL Server data source IfyoucreatedthedatabaseforBzIs,youdonotneedtore-createit. Youmustonlyconnect to the database. 21

Chapter 2: Installing and configuring BlueZone Integration Server Prerequisite InstalltheMicrosoftSQLServerJDBCDriver2.0ontheserverthatishostingBzIsAdmin. Microsoft does not allow the redistribution of its SQL Server drivers. You must download the driver from the Microsoft website and install it to use this data provider. Procedure 1. Create a database table with the following format: Column Contents 1 User ID(string) 2 Password(string) 3 Email address(string) 4 Site name(string) 5 Page name(string) 6-16 Arbitrary data(string) 2. Name the table BzUsers. 3. Navigate to the[tomcat]/webapps/bzisadmin/web-inf folder. 4. Open the applicationcontext.xml file in a text editor. 5. Locate the mssqldatasource bean: <bean id="mssqldatasource" class="org.springframework.jdbc.datasource.drivermanagerdatasource" p:driverclassname="com.microsoft.sqlserver.jdbc.sqlserverdriver" p:url="jdbc:sqlserver://yourserver.com;integratedsecurity=false;databasename=bluezone" p:username="admin" p:password="secret" /> 6. Modify the following properties: Property url username password Value PathtotheSQLServerandthedatabasename Refer to http://msdn.microsoft.com/en-us/library/ ms378428%28v=sql.90%29.aspx for more information on setting this parameter. SQL Server user name SQL Server password 7. Locate the bzw2huserdao bean: <bean id="bzw2huserdao" class="com.bluezone.w2h.data.mssqluserdao"> <property name="datasource" ref="mssqldatasource" /> <property name="userstablename" value="dbo.bzisusers" /> </bean> 8. Modify the following parameters: Parameter datasource userstablename Description Define the SQL data source that was configured in the mssqldatasource bean. Define the table to direct the application to use. 22

Configuring forwarding DAOs 9. Save and close the file. 10. Restart the application or the server. Configuring forwarding DAOs You can make changes to multiple objects that implement the BzW2hUserDao interface. This works as a simple synchronization of database tables. It is recommended that if you have the technical resources within your organization that you use standard database synchronization techniques instead of this forwarding DAO strategy. 1. Create multiple BzW2hUserDao objects as directed in the previous topics. 2. Add the objects to the BzW2hForwardingUserDao bean. There is one sink bean already definedandcommentedoutthatcanbeusedasaguide. Thatbeanisdefinedbydefaultas: <bean id="bzw2hforwardinguserdao" class="com.bluezone.w2h.data.bzw2hforwardinguserdao"> <property name="masterdao" ref="bzw2huserdao" /> <!-- No sinks by default <property name="daolist"> <list> <ref bean="bzw2huserdaosink1" /> </list> </property> --> </bean> 3. Uncomment the daolist property and add additional sink beans. The BzW2hForwardingUserDao will read from the masterdao and will perform writes in a loop against the daolist DAOs. 4. Go to[tomcat]/webapps/bzisadmin/web-inf and open the dispatcher-servlet.xml fileinatexteditor. 5. In each of the controller beans, replace all references to the bzw2huserdao bean with bzw2hforwardinguserdao. For example: Change the default property node from: <property name="bzw2huserdao" ref="bzw2huserdao" /> To this: <property name="bzw2huserdao" ref=" bzw2hforwardinguserdao " /> 6. Save and close the file. Changing the default passwords The BlueZone Integration Server Administrator has three levels of administrator roles. 23

Chapter 2: Installing and configuring BlueZone Integration Server Table 5: BzIs Admin administrator roles Role Owner Admin Viewer Permissions Create, read, update, and delete Owners, Admins, and Viewers accounts. TheOwnercannotreadormodifytheuserdata. The default Owner account credentials are: User ID: owner Password: owner Create, read, update, and delete the user data. The default Admin account credentials are: User ID: BzIsAdmin Password: apass Read the user data. The default Viewer account credentials are: User ID: BzIsViewer Password: vpass Change the Owner, Admin, and Viewer account passwords before you modify the user data. 1. Log in to the BzIs Admin interface at http://[tomcat-url]/bzisadmin/ using the preconfigured owner account. The default Owner account credentials are: User ID: owner Password: owner 2. Click Edit next for the Owner account, and change the default password. 3. Repeat step 2 for the Admin and Viewer accounts. 4. Create additional administrator accounts as needed. 5. Log out of the Owner account. 24

Chapter 3: Using BlueZone Integration Server Logging in to BzIs 1. Open Internet Explorer and go to http://[tomcat-url]/bluezone/. 2. TypeyouruserIDandpasswordandclickSignOn. After authenticated, the page is redirected to http://[tomcat-url]/bluezone/sites/ Demo/Page/launch_x.htm and the BlueZone session starts. Modifying user data TheBzIsuserdataisdefinedinthedefault.csvfileordatabasetable. To modify the default data source: 1. Navigate to the[tomcat]/webapps/bluezone/web-inf/data folder. 2. Open the bzw2h.csv file in Microsoft Excel, or a text editor. 3. You can make the following modifications: Modification Addanewuser Delete a user Modify existing user data Action Createanewrowthatcontainstheuser sdata Delete the user s row Edit the necessary cells as needed 4. Save and close the file. 25

Chapter 4: Using BlueZone Integration Server Administrator Logging in to BzIs 1. Open Internet Explorer and go to http://[tomcat-url]/bzisadmin/. 2. TypeyouruserIDandpasswordandclickSignOn. Adding user data 1. LogintoBzIsAdminusinganAdminaccount. 2. In the Actions menu, select New User. 3. Enter the user s data in the fields. 4. Click Save. 26

Chapter 5: Log files There are two logs in BlueZone Integration Server: the application log and the logins log. BlueZone Integration Server logs The application log stores the inner workings of BlueZone Integration Server. The logins log stores user login information. The paths of these logs are defined in the bzw2hlogfilehandler and bzw2hlogincontrollerlogfilehandler beans by the constructor-arg in the applicationcontext.xml file: <bean id="bzw2hlogfilehandler" class="com.bluezone.w2h.helpers.bzlogfilehandler"> <constructor-arg value="./logs/bzw2h.log" /> <constructor-arg value="50000" /> <constructor-arg value="1" /> <constructor-arg value="true" /> <property name="formatter" ref="simpleformatter" /> </bean> Where: Constructor-arg1isthepathtothelog Constructor-arg 2 is the maximum file size in KB before rollover Constructor-arg 3 is the number of log files allowed Constructor-arg4istheappendtolog. Thedefaultistrue. The logging levels are set within the bzw2hloginslevelchanger and bzw2hloglevelchanger beans: <bean id="bzw2hlogincontrollerlogfilehandler" class="com.bluezone.w2h.helpers.bzlogfilehandler"> <constructor-arg value="./logs/bzw2hlogins.log" /> <constructor-arg value="50000" /> <constructor-arg value="1" /> <constructor-arg value="true" /> <property name="formatter" ref="simpleformatter" /> </bean> Where: Constructor-arg1isthepathtothelog Constructor-arg 2 is the maximum file size in KB before rollover Constructor-arg 3 is the number of log files allowed Constructor-arg4istheappendtolog. Thedefaultistrue. Bydefault,thelogginglevelsaresettoINFO.Theothervalidloglevelsare: SEVERE(highest value) WARNING INFO CONFIG FINE FINER FINEST(lowest value) 27

Chapter 5: Log files BlueZone Integration Server Administrator log TheBzIsAdminlogfilerecordseveryactionperformedinBzIsAdmin. Forexample,thislog containsthedateandtimewhenuserslogintotheapplication,andcreate,update,anddelete accounts. The log file is saved in the [tomcat]/webapps/bzisadmin/web-inf/log folder as BzIsAdminLog.txt. The path of this log is defined in the bzw2hadminlogger bean in the applicationcontext.xml file: <bean id="bzw2hadminlogger" class="com.bluezone.w2h.helpers.fileadminlogger"> <property name="logfolder" value="web-inf/log/" /> <property name="logfilename" value="bzisadminlog.txt" /> <property name="maxfilesizeinmbs" value="1" /> <property name="maxlogfiles" value="3" /> <!-- Set to 0 to keep all files --> <property name="queuemessagesdelay" value="1" /> </bean> Where: logfolder is the folder where log is written. logfilename is the name of file. maxfilesizeinmbs is the maximum size of the file in megabytes before rolling over into a new file. maxlogfilesisthemaximumnumberoflogfilestokeep. Settozerotokeepallfiles. queuemessagesdelay is the number of seconds that the message queue is held before being writtentofile. ThisreducesfileIO. 28

Chapter 6: Message pages Message pages take the form msg-*.html. The web application maps calls for files of this type into physical pages within [tomcat]/bluezone/web-inf/jsp/. For example, a call to [tomcat-url]/bluezone/msg-loginfailed.html maps to [tomcat]/webapps/bluezone/web-inf/jsp/loginfailed.jsp. You can create custom message pages. 29

Related information You might need to refer to other sources of information when you are using BlueZone products. This section lists the documentation that supports BlueZone. Version 6 Release 2 product information: BlueZone Advanced Automation Developer's Guide, BZAA-0602-DG-01 BlueZone Desktop Administrator's Guide, BZD-0602-AG-01 BlueZone Display and Printer User s Guide, BZDP-0602-UG-01 BlueZone Integration Server Administrator s Guide, BZIS-0602-AG-01 BlueZone License Manager Administrator's Guide, BZLM-0602-AG-01 BlueZone PasswordVault User s Guide, BZPV-0602-UG-01 BlueZone Secure FTP User s Guide, BZSF-0602-UG-01 BlueZone Security Sever Administrator's Guide, BZSS-0602-AG-01 BlueZone Session Manager User s Guide, BZSM-0602-UG-01 BlueZone Web-to-Host Administrator's Guide, BZWH-0602-AG-01 30

Index A administratorrole...24 application architecture...6 overview...5 applicationcontext.xml...11 B BzLdapLoginDataProvider...15 bzw2h.csv...10,11 bzw2h.log...27 BzW2hCsvLoginDataProvider...11 bzw2hlogins.log...27 C configuring automaticwindowssignon...20 LDAPservers...15 customer support contacting...3 D default data source modifying...10 device name overridevalue...10 directorystructure...6 dispatcher-servlet.xml...18 F files applicationcontext.xml...11 bzw2h.csv...10,11 bzw2h.log...27 bzw2hlogins.log...27 dispatcher-servlet.xml...18 launch_x.htm...10 ldap.jsp...15 redirect.jsp...20 signon.jsp...18 signon-windows.bz...20 splitter.jsp...20 I installation dependencies...8 requirements...8 installing BlueZoneIntegrationServer...9 L launch folders creating...9 launch_x.htm...10 LDAP servers configuring...15 ldap.jsp...15 legalnotices...2 logging in BlueZoneIntegrationServer...25 BzIsAdmin...26 login page customizing...18 LoginController customizing...18 logs applicationlog...27 loginslog...27 LU name overridevalue...10 M messagepages...29 modifying defaultdatasource...10 O overrides setting...10 ownerrole...24 P pages messages...29 passwords modifying...24 privileges configuring...24 R redirect.jsp...20 requirements installation...8 Rocket Customer Portal accessing...3 S securityrequirements...8 servers 31

BlueZone Integration Server LDAP...15 sessions creating...9 signon.jsp...18 signon-windows.bz...20 sites creating...9 software support contacting...3 splitter.jsp...20 support contacting...3 T technical support contacting...3 trademarks...2 troubleshooting contactingtechnicalsupport...3 U user data configuring...24 user data providers BzLdapLoginDataProvider...15 BzW2hCsvLoginDataProvider...11 users creating...25 V viewerrole...24 W Web-to-Host Wizard launchfolders...9 overrides...10 sessions...9 sites...9 Windows sign on configuring...20 32