BlueZone Integration Server

(1)

BlueZone Integration Server

Administrator’s Guide

Version 6.2

January 2013 BZIS-0602-AG-01

(2)

Notices

Edition

Publication date:January 2013

Book number:BZIS-0602-AG-01

Product version:BlueZone Integration Server Version 6.2

Copyright

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. or its affiliates, are furnished under license, and may be used and copied only in 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 77 4th_{Avenue, Suite 100}

Waltham, MA 02451–1468 USA

Tel: +1 781 577 4321 Fax: +1 617 630 7100

(3)

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.

To log in to the Rocket Customer Portal, go to:

www.rocketsoftware.com/support

If you do not already have a Rocket Customer Portal account, you can request one by clicking

Need an account? on the Rocket Customer Portal login page.

Alternatively, you can contact Global Technical Support by email at

(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 interface to edit the user data. It can be installed on the same server as BzIs or on a different server that points to the same database as BzIs.

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:

standby="Initializing BlueZone Web-to-Host …" height="250"

width="575" …>

The LU name (or Device name in an iSeries Display) is specified as “OU812” and the port is “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

[email protected]

(6)

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%%s6%" /> <param name="MD_S1_Port" value="%s7%%s7%" />%s7%

The placeholder %s6% specifies column 6 and %s7% specifies column 7. InTable 1:Example CSV file contentsnotice that column 6 contains the LU name and column 7 contains the port.

3. The user JSmith logs in to BzIs. If the authentication passes, the data is pulled from the 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%%s6%" /> <param name="MD_S1_Port" value="%s7%%s7%" />%s7%

is converted to:

<param name="MD_S1_Lu" value="MyLuMyLuMyLu" /> <param name="MD_S1_Port" value="2323" />23

4. After this conversion happens, the BlueZone emulator starts and assigns the LU of MyLu into the session that connects to the host on port 23.

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.

(7)

Architecture

Table 2: BlueZone Integration Server and BlueZone Integration Server Administrator directory structure

Subdirectory or file Description

/logs Contains the BzIs log files. These log files are created on the first run.

/META-INF Created by the JAR process. Contains metadata about the BzIs WAR. Can be deleted.

/Sites Contains sites created by the BlueZone Web-to-Host Wizard. Create all sites in this folder.

/WEB-INF Contains metadata about the BzIs web application, including java class files, configuration files, data files,.jspfiles, and binary libraries.

/static Contains any files that need to be referenced from within BzIs that are not dynamic, such as PNGs, GIFs, JPGs, and so on.

login.html 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 indispatcher-servlet.xml.

logout.html Virtual File. All calls to this file are handled by

com.bluezone.w2h.controllers.LogoutController, which is configured indispatcher-servlet.xml.

signon.bz 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.bzwill post the login/password tologin.html. This login information is passed intosplitter.jspby default. You can host your sign on screen anywhere and direct it into Integration Server.

/signon-windows.bz Virtual file. Uses an Applet to determine windows user name and computer name and redirects to the login process.

/redirect.jsp The default welcome page. By default it redirects tosignon.bz.

/splitter.bz Virtual file. This page directs the log in to the correct location. Modify the code in this page to change handling of log ins. This virtual file maps to the physical file at/WEB-INF/jsp/splitter.jsp.

(8)

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 be installed on the same server or on different servers. If you install the BzIs Admin component 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 Server JDBC Driver 2.0, a Type 4 JDBC driver. The driver is not redistributable and cannot be included in the BzIs or BzIs Admin package.

If you want to connect to a Microsoft SQL Server, you must download the driver from the Microsoft website, and install it on the same server as BzIs or BzIs Admin before using the data providers.

The following table lists the data provider classes that are supplied with each component. Refer toConfiguring the Microsoft SQL Server data provider, on page 12andConfiguring the Microsoft SQL Server data source, on page 21for more information on these provider classes.

(9)

Installing BlueZone Integration Server

Table 3: Data provider classes Component Data provider

class type

Data provider class name

BzIs Login data provider class

com.bluezone.w2h.data.BzW2hSqlLoginDataProvider

BzIs Admin User data provider class

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. In the File Name field, type a name for the site, for example type Demo, and click Open. d. In the Confirm Installation window, click OK.

3. Create a launch folder:

a. In the Sites window, click Next. b. Click Create.

c. In the Folder Name field, type a name for the launch folder, for example type Page, and select a distribution type.

d. Click OK. 4. Create a session:

(10)

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. Type a name for the session, for example type MFD, and click OK.

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. In the field(s), type %sn%, where n is the corresponding column number in the data source.

For example, in the LU Name field, type %s6% to map to column 6 in the data source .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 the value was modified in the launch page.

1. Navigate to the [tomcat]/webapps/BlueZone/Sites/Demo/Page/ folder. 2. Open the launch_x.htm file in a text editor.

3. Ensure that the override values are in the launch page file. For example, if you set the LU

Name override value to %s6%, the following line would be in the file:

If the launch_x.htm file does not contain this line, ensure that you set the LU name override value when you configured Web-to-Host. Refer toInstalling and configuring BlueZone Web-to-Host, on page 9for 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. If you plan to use a Microsoft SQL Server, you do not need to modify the default data source.

1. Navigate to [tomcat]/webapps/BlueZone/WEB-INF/data. 2. Open the bzw2h.csv file in Microsoft Excel, or a text editor. 3. Add a new user. For example, the user test was added:

(11)

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 [email protected] w2h demo g7 test test [email protected] 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. Ensure that the values in columns 4 and 5 match a valid site and launch folder. These values were created when Web-to-Host was configured. Refer toInstalling and configuring BlueZone Web-to-Host, on page 9for 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 Value

bzW2hCsvParser Reference to the parser bean.

matchIgnoresCase Determines if the login is case-sensitive. Set tofalsefor case-sensitive login.

(12)

<bean id="bzW2hCsvParser" name="bzW2hCsvParser"

class="com.bluezone.w2h.data.BzW2hCsvParser">

<property name="csvResource" value="/WEB-INF/data/bzw2h.csv" /> <property name="emptyColumnPlaceholder" value="" />

</bean>

6. Modify the following properties as needed:

csvResource Location of the.csvfile.

emptyColumnPlaceholder Contains the string that will replace any columns that are empty. The value is empty by default.

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:

(13)

Configuring the Microsoft SQL Server data provider

url Path to the SQL Server and the database name

username _{SQL Server user name} password 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" />

8. Uncomment the BzW2hSqlLoginDataProvider bean and modify the following properties:

dataSource Name of the data source

passwordEncrypted The available values are:

§

true: The data provider uses the provided

passwordHasherproperty to encrypt or hash the password.

§

false: The password is sent in the clear.

passwordHasher Implements the

com.bluezone.w2h.crypto.PasswordEncryptor

interface.

There are two implementations provided:

§

BzW2hBlowfishPasswordHasherclass

§

BzW2hShaPasswordHasherclass Both of these classes are defined by default in theapplicationContext.xmlfile.

userTableName Name of the database table created in step1.

userIdFieldName The name of the column in the BzUsers table that contains User ID.

userPasswordFieldName The name of the column in the BzUsers table that contains Password.

10. In the [tomcat]/webapps/BlueZone/WEB-INF folder, open the dispatcher-servlet.xml file in a text editor.

11. Locate the loginController bean:

<bean id="login"

name="loginController"

class="com.bluezone.w2h.controllers.LoginController">

12. Change ref="bzW2hCsvLoginDataProvider" to ref="bzW2hSqlLoginDataProvider". 13. Save and close the file.

(14)

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 [email protected].

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:

delegate TheBzLoginDataProviderthat the updated user ID and password combination are forwarded to.

append The text to append to the user ID.

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 or Active Directory server) and the custom data to be stored in a second database.

Note

TheauthenticationProvidercan be anyBzLoginDataProvider, including a

BzAppendingLoginDataProviderwhich front ends anotherauthenticationProvider.

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

(15)

Authenticating Windows domains

authenticationProvider A reference to a configuredBzLoginDataProviderbean to handle authentication.

userDataProvider A reference to a configuredBzLoginDataProviderbean to handle data retrieval.

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="filterArgs"> <list> <value>BzUserId</value> <value>BzUserPassword</value> </list> </property>

(16)

anonymousBind False by default.

The switch to determine ifgetData(userId)or

getData(userId,Password)is used is set in

LoginController.setPasswordRequired(boolean). Modify the setting indispatcher-servlet.xml. To look up all users with no authentication:

IfgetData(userId)is called andAnonymousBind

istrue, then no security credentials are used when initializing the LDAP context, this is known as anonymous bind.

To look up all users with a single admin login: IfgetData(userId)is called andAnonmymousBind

isfalse, then the values ofgetSecurityPrincipal

andgetSecurityCredentialare used to initialize the LDAP context.

To authenticate with values passed into

getData(userId, Password):

IfgetData(userId,Password)is called, then the value ofAnonymousBindis ignored and the passed values are always used to authenticate.

connectionTimeoutInMillisecondsThe number of milliseconds until the connection attempt times out.

bzUserIdFilterArgKey If this key is listed infilterArgs, then it will be replaced with the user ID passed intogetData(UserId,Pass).

bzUserPasswordFilterArgKey If this key is listed infilterArgs, then it will be replaced with the password passed into

getData(UserId,Pass).

filter See LDAP filter query references for structure of this filter string. This filter can contain replaceable values, of the form {0}, {1}, and so on. The string {0} will be replaced withfilterArgs[0]and so on. See

javax.naming.directory.DirContext.search()

for the exact rules of the replacement. This allows for the passing of binary data and so on.

filterArgs The list of arguments to the filter to replace the placeholders: {0}, {1}, and so on.

providerUrl The URL of the ldap server including port.

For example,ldap://ldap.virginia.edu:389

searchBase The base DN to search.

For example,o=University of Virginia,c=US searchControls TheSearchControlsobject reference.

(17)

Customizing the login options

securityAuthentication The type/mode of authentication. See

javax.naming.Context.SECURITY_AUTHENTICATION for values, "none", "simple", "strong".

Use<null />for default behavior. Default behavior:

§

IfAnonymousBindistrue, then no authentication is passed and the

Context.SECURITY_AUTHENTICATION="none".

§

IfAnonymousBindisfalsethen either theSecurityPrincipaland

SecurityCredential, or theBzUserId

andBzUserPassword, are passed and the

Context.SECURITY_AUTHENTICATION="simple".

securityPrincipal A user ID. Used withAnonymousBind.

securityCredential A password. Used withAnonymousBind.

illegalCharsUserIdString

illegalCharsPasswordString Specifies the illegal characters for use as a userlogin ID or a user password. Disallowing these characters prevents LDAP injection attacks. The

BzLdapLoginDataProviderwill 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: space or # character at the beginning of a string space character at the end of a string

, 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

Customizing the login options

The following login options can be customized:

§

Redirect page options

(18)

§

LoginController options

§

Launch page redirect

§

Automatic Windows sign on

Customizing the redirect options

You can change the order of the welcome file list. The welcome file list determines the order that the pages are visited. Or, you can change the file that the default redirect page uses.

§

To change the contents or order of the welcome file list:

ú

Navigate to the [tomcat]/webapps/BlueZone/ folder.

ú

Open the web.xml file in a text editor.

ú

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>

ú

Modify the file list contents, order of the files, or both.

ú

Save and close the file.

§

To change the file that the default redirect page uses:

ú

Navigate to the [tomcat]/webapps/BlueZone folder.

ú

Open the redirect.jsp file in a text editor.

By default, the redirect.jsp file redirects to the signon.bz, as shown below:

<% response.sendRedirect("signon.bz"); %>

ú

Modify the redirect file.

ú

Save and close the file.

Customizing the sign on page appearance

The signon.jsp file controls the appearance of the sign on page. You can modify this file to change the look and feel of the sign on page in the browser.

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.

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:

(19)

Customizing the LoginController

<bean id="login"

name="loginController"

class="com.bluezone.w2h.controllers.LoginController">

<!--PasswordRequired

If false, then BzUserDataProvider.getData(loginId) is called.

If true, then BzUserDataProvider.getData(loginId,password) is called. --> <property name="passwordRequired" value="false" />

4. Modify the properties as needed. The available properties and their use are:

Property Usage

bzUserDataProvider By default, this references theBzW2hCsvLoginDataProvider bean defined in theapplicationContext.xmlfile. This

UserDataProvidercan be changed.

There are other defaultLoginDataProvidersfor connection to LDAP/ActiveDirectory and Microsoft SQL Server. Refer to

Configuring the BzIs user data providers, on page 11for more information.

bzUserIdKey When the user ID is received it is placed into the web application’s session context under this key.

bzUserPasswordKey When the user password is received it is placed into the web application’s session context under this key.

bzUserDataKey When the user’s data is retrieved from theDataProvider, it is placed into aBzW2hUserDataRowobject and placed into the web application’s session context under this key.

loginOkRedirect If the login succeeds, then the call is redirected to this file. By default, this issplitter.bz. You can modify this to point to custom code.

loginFailedRedirect If the login fails, then the call is redirected to this file. You can modify this to point to custom code. Refer toMessage pages, on page 29for more information.

passwordRequired If false, thenBzUserDataProvider.getData(loginId)is called.

If true, then

BzUserDataProvider.getData(loginId,password)

is called.

sessionCreationDenied Advanced. If false, then theLoginControllerwill create a web application session for this call. Default isfalse. If true, then the session must be created prior to the

LoginControllerhandling the request, or an error will be returned.

(20)

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 the BlueZone launch page, and then forwards the user to that page, from which the BlueZone emulator is actually launched. You can modify the logic in this file, or perform additional data look ups to direct the calls to a launch page.

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.

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 ID and computer name. The user is then forwarded to the login process.

This is not a secure method of authentication; it is intended to be used in situations where access to the emulator is allowed and authentication is performed on the emulator screen. It saves the user from having to enter their user ID to access their sessions. If you use this method, ensure to set LoginController passwordRequired field to false. Refer toCustomizing the LoginController, on page 18for more information.

To set this as the default sign on mechanism:

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 8for more information.

2. In a web browser, go to http://[tomcat-url]/ to test the Tomcat installation.

The Tomcat default page opens. If it does not, ensure that Tomcat 6.0 or later has been 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

(21)

Configuring the BzIs Admin data sources

The BlueZone Integration Server Administrator Configure Data Source Error window opens. This window indicates that BzIs Admin is running but it is not configured yet. 6. Configure a data source.

7. Change the default passwords.

Configuring the BzIs Admin data sources

You must configure either the CSV or Microsoft SQL Server data source for the BzIs Admin 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">

</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:

class="com.bluezone.w2h.data.BzW2hCsvUserDao"> <property name="csvParser" ref="bzW2hCsvParser" /> </bean>

8. Restart the application or the entire server.

9. Log in to BzIs Admin again using the Owner account.

Configuring the Microsoft SQL Server data source

If you created the database for BzIs, you do not need to re-create it. You must only connect to the database.

(22)

Prerequisite

Install the Microsoft SQL Server JDBC Driver 2.0 on the server that is hosting BzIs Admin. 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:

6. Modify the following properties:

url Path to the SQL Server and the database name Refer tohttp://msdn.microsoft.com/en-us/library/

ms378428%28v=sql.90%29.aspxfor more information on setting this parameter.

username SQL Server user name

password SQL Server password

7. Locate the bzW2hUserDao bean:

class="com.bluezone.w2h.data.MsSqlUserDao">

8. Modify the following parameters:

Parameter Description

dataSource Define the SQL data source that was configured in the

msSqlDataSourcebean.

(23)

Configuring forwarding DAOs

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 defined and commented out that can be used as a guide. That bean is defined by default as:

<bean id="bzW2hForwardingUserDao"

class="com.bluezone.w2h.data.BzW2hForwardingUserDao"> <property name="masterDao" ref="bzW2hUserDao" />  </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 file in a text editor.

5. In each of the controller beans, replace all references to the bzW2hUserDao bean with bzW2hForwardingUserDao. For example:

Change the default property node from:

To this:

Changing the default passwords

(24)

Table 5: BzIs Admin administrator roles

Role Permissions

Owner Create, read, update, and delete Owners, Admins, and Viewers accounts. The Owner cannot read or modify the user data.

The default Owner account credentials are: User ID: owner

Password: owner

Admin Create, read, update, and delete the user data. The default Admin account credentials are: User ID: BzIsAdmin

Password: apass Viewer 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 step2for the Admin and Viewer accounts.

4. Create additional administrator accounts as needed. 5. Log out of the Owner account.

(25)

Chapter 3: Using BlueZone Integration

Server

Logging in to BzIs

1. Open Internet Explorer and go to http://[tomcat-url]/BlueZone/. 2. Type your user ID and password and click Sign On.

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

The BzIs user data is defined in the default .csv file or database table. 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 Action

Add a new user Create a new row that contains the user’s data Delete a user Delete the user’s row

Modify existing user data Edit the necessary cells as needed

(26)

Chapter 4: Using BlueZone Integration

Server Administrator

Logging in to BzIs

1. Open Internet Explorer and go to http://[tomcat-url]/BzIsAdmin/. 2. Type your user ID and password and click Sign On.

Adding user data

1. Log in to BzIs Admin using an Admin account. 2. In the Actions menu, select New User. 3. Enter the user’s data in the fields. 4. Click Save.

(27)

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" />

Where:

Constructor-arg 1 is the path to the log

Constructor-arg 2 is the maximum file size in KB before rollover Constructor-arg 3 is the number of log files allowed

Constructor-arg 4 is the append to log. The default is true.

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" />

Where:

Constructor-arg 1 is the path to the log

Constructor-arg 2 is the maximum file size in KB before rollover Constructor-arg 3 is the number of log files allowed

Constructor-arg 4 is the append to log. The default is true.

By default, the logging levels are set to INFO. The other valid log levels are:

§

SEVERE (highest value)

§

WARNING

§

INFO

§

CONFIG

§

FINE

§

FINER

(28)

Chapter 5: Log files

BlueZone Integration Server Administrator log

The BzIs Admin log file records every action performed in BzIs Admin. For example, this log contains the date and time when users log in to the application, and create, update, and delete 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>

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.

maxLogFiles is the maximum number of log files to keep. Set to zero to keep all files. queueMessagesDelay is the number of seconds that the message queue is held before being written to file. This reduces file IO.

(29)

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.

(30)

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

(31)

Index

A

administrator role ...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 automatic Windows sign on ...20

LDAP servers ...15

customer support contacting... 3

D

default data source modifying...10 device name override value...10 directory structure... 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 BlueZone Integration Server... 9

L

launch folders creating... 9 launch_x.htm ...10 LDAP servers configuring...15 ldap.jsp ...15 legal notices... 2 logging in BlueZone Integration Server...25

BzIs Admin ...26 login page customizing...18 LoginController customizing...18 logs application log ...27

log ins log ...27

LU name override value...10

M

message pages ...29

modifying default data source...10

O

overrides setting ...10 owner role ...24

P

pages messages...29 passwords modifying...24 privileges configuring...24

R

redirect.jsp...20 requirements installation... 8

Rocket Customer Portal accessing... 3

S

security requirements ... 8 servers

(32)

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 contacting technical support ... 3

U

user data configuring...24

user data providers BzLdapLoginDataProvider...15 BzW2hCsvLoginDataProvider...11 users creating...25

V

viewer role...24

W

Web-to-Host Wizard launch folders... 9 overrides...10 sessions... 9 sites ... 9 Windows sign on configuring...20