1 Introduction

JBoss Enterprise Application Platform 5 is a widely used Application Server from the JBoss division at Redhat.

In this document we describe how to install and run the LegStar JCA Socket connector on JBoss EAP 5.

Although the use cases described here are built on the Enterprise version of JBoss Application Server, they would run on the corresponding community edition as well.

Beware, that the instructions are specifically for version 5 of JBoss EAP.

2 Installation

If you havent't done so, install LegStar Socket Transport in CICS.

On the JEE side, we will refer to the location where you have JBoss EAP5 installed as <JBOSS_HOME>. We assume it is running using the default server.

Download and unzip the LegStar JCA Connector distribution, to a location of your choice, this should create a folder called legstar.connector.distrib-x.y where x.y is the latest version number available. We will refer to this folder as <LEGSTAR_JCA_HOME>.

2.1 Deploy the Resource Adapter

Copy <LEGSTAR_JCA_HOME>/legstar.socket.connector-x.y.rar to <JBOSS_HOME>/server/default/deploy.

Edit the <LEGSTAR_JCA_HOME>/samples/jee5/legstar.socket.connector-ds.xml deployment descriptor. Change the ServerName and PortNumber parameters to point to the CICS Socket listener.

Copy <LEGSTAR_JCA_HOME>/samples/jee5/legstar.socket.connector-ds.xml to <JBOSS_HOME>/server/default/deploy.

Check the JBoss log for a message similar to:

INFO  [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=ConnectionFactoryBinding,name=legstar.socket.connector' to JNDI name 'java:legstar.socket.connector'

3 Running the samples

You will find several samples ready for JBoss EAP5 in <LEGSTAR_JCA_HOME>/samples/jee5.

3.1 samples/jee5/web

This is a simple servlet using the connector directly:

It executes a CICS program called T1CONTXT whose COBOL source is in <LEGSTAR_JCA_HOME>/samples/cobol. The program just queries a few environment parameters from the CICS system. It is recommended to use it as an Installation Validation Program.

You deploy the web application by copying <LEGSTAR_JCA_HOME>/samples/jee5/web/legstar.connector.it.jee5.web.war to <JBOSS_HOME>/server/default/deploy.

You can then point a browser to http://localhost:8080/legstar.connector.it.jee5.web. The web page displays a single link which, if clicked, runs the T1CONTXT CICS program and displays the parameters returned.

The JBoss log is a good source of information regarding any failure you might get. You can turn LegStar debug level on, by adding:

   <category name="com.legsem">
      <priority value="DEBUG"/>
   </category>

to <JBOSS_HOME>/server/default/conf/jboss-log4j.xml.

3.2 samples/jee5/ear

This sample provides an EJB which performs simple create, read and update operations. These operations happen within a container-managed transaction.

The 3 operations correspond to 3 CICS programs: LSFILEAW for create, LSFILEAE for read and LSFILEAD for delete. Sources for these programs are in <LEGSTAR_JCA_HOME>/samples/cobol.

The EJB is called from a web application and both the web application and the EJB are bundled in an EAR archive.

You deploy the EAR by copying <LEGSTAR_JCA_HOME>/samples/jee5/ear/legstar.connector.it.jee5.ear-x.y.ear to <JBOSS_HOME>/server/default/deploy.

Once deployed, you access the web application by pointing a browser to http://localhost:8080/legstar.connector.it.jee5.ejb.web.

The UI displayed allows you to pick up an operation, a client ID, and then, by clicking on the submit button, run the corresponding CICS program.

First try to read with client ID 100 (a standard entry in IBM's FILEA), you should get a read OK reply.

Now try to read with client ID 99999. You should get a "Remote execution failed" error message. This is because client ID 99999 does not exist.

Now create client 99999 (by entering client ID 99999 and selecting create then submit). You should get an OK reply.

Try reading 99999, you should now also get an OK reply.

Now try deleting client ID 99999, you should get an OK reply.

Finally, try the fail option for client ID 99999. This option first creates the client ID 99999 which succeeds, but within the same transaction, it attempts at creating the same client ID again which fails. Because the failure occur within the same transaction, all updates are rolled back, including the first creation.

You can test that the container-managed transactions actually work by verifying that client ID 99999 is not if the database following the failure.

3.3 samples/jee5/web.tran

This is a servlet that performs the same functions as the previous sample but rather than using container-managed transaction, it uses component-managed transactions.

This servlet also requires a security context.

The idea is that web users are required to authenticate in a secure way in order to run the servlet and then access to the mainframe uses a different set of credentials, unknown to the web user.

This is one way you can setup security for this sample:

3.3.1 Unabling SSL

First generate an SSL key. For this, within the <JBOSS_HOME>/server/defaul/conf directory run:

     keytool -genkey -keystore chap8.keystore -storepass rmi+ssl -keypass rmi+ssl -keyalg RSA -alias chapter8 -validity 3650 -dname "cn=chapter8 example,ou=admin book,dc=jboss,dc=org"

Second unable SSL port 8443. Edit file <LEGSTAR_JCA_HOME>/server/defaul/deploy/jbossweb.sar/server.xml and uncomment:

            <!-- SSL/TLS Connector configuration using the admin devl guide keystore -->
            <Connector protocol="HTTP/1.1" SSLEnabled="true"
                 port="8443" address="${jboss.bind.address}"
                 scheme="https" secure="true" clientAuth="false"
                 keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"
                 keystorePass="rmi+ssl" sslProtocol = "TLS" />

3.3.2 Securing the mainframe access

The LegStar Socket Transport can be setup to accept incoming connections only if they are authenticated. In this case, the client side of the Transport needs to collect a valid mainframe(RACF) user/password that it presents to the mainframe security system.

You can enter the user/password in the Connection Resource parameters (legstar.socket.connector-ds.xml) but the password would appear in clear text in this configuration file. Here is a better way offered by JBoss:

First encrypt the mainframe password by running the following command from the <JBOSS_HOME> folder (change ; to : on unix):

        java -cp "lib/jboss-logging-spi.jar;lib/jbosssx.jar" org.jboss.resource.security.SecureIdentityLoginModule <required_mainframe_password>

This will produce a required_mainframe_password_encrypted.

Then under <JBOSS_HOME>/server/defaul/conf, add this to login-config.xml (replacing all <required ...> fields with actual values):

        <!-- Access to secured mainframe for legstar integration tests -->
        <application-policy name="CicsRealm">
          <authentication>
            <login-module code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">
              <module-option name="principal"><required_mainframe_user></module-option>
              <module-option name="userName"><required_mainframe_user></module-option>
              <module-option name="password"><required_mainframe_password_encrypted></module-option>
              <module-option name="managedConnectionFactoryName">jboss.jca:service=TxCM,name=legstar.socket.connector</module-option>
            </login-module>
          </authentication>
        </application-policy>

Edit the <LEGSTAR_JCA_HOME>/samples/jee5/legstar.socket.connector-ds.xml file and uncomment:

        <security-domain>CicsRealm</security-domain>

Redeploy that file to <JBOSS_HOME>/server/default/deploy.

3.3.3 Securing the web application

Here we restrict access to the web application to authenticated users belonging to the LegstarTesterRole role.

This is already defined in the security-related content in web.xml for the web application:

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>Secure Content</web-resource-name>
                <url-pattern>/*</url-pattern>
            </web-resource-collection>
            <auth-constraint>
                <role-name>LegstarTesterRole</role-name>
            </auth-constraint>
            <user-data-constraint>
                <transport-guarantee>CONFIDENTIAL</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

        <login-config>
            <auth-method>BASIC</auth-method>
            <realm-name>legstarRealm</realm-name>
        </login-config>

        <security-role>
            <description>The role required to access restricted content </description>
            <role-name>LegstarTesterRole</role-name>
        </security-role>

In addition to the standard web.xml, the delivery also contains a jboss-web.xml file with the following security-related content:

       <security-domain>legstarRealm</security-domain>

What we need to do now is to create a web user who is authorized to run this web application.

Under <JBOSS_HOME>/server/defaul/conf/props, create 2 files:

      legstar-users.properties with content:
          alice=wonderland
      legstar-roles.properties with content:
          alice=LegstarTesterRole

Under <JBOSS_HOME>/server/defaul/conf, add this to login-config.xml:

        <!-- Web users security policy for legstar testing -->
        <application-policy name="legstarRealm">
            <authentication>
                <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
                    <module-option name="usersProperties">props/legstar-users.properties</module-option>
                    <module-option name="rolesProperties">props/legstar-roles.properties</module-option>
                </login-module>
            </authentication>
        </application-policy>

3.3.4 Running the sample

At this stage you might want to restart JBoss so that it picks up all these changes.

Drop the legstar.connector.it.jee5.web.tran.war into <LEGSTAR_JCA_HOME>/server/default/deploy.

Point a browser to http://localhost:8080/legstar.connector.it.jee5.web.tran.

You can perform exactly the same functions as samples/jee5/ear.

If you click the submit button though, you should be redirected to the HTTPS URL (your browser will likely display a warning since the SSL certificate we created is self-signed. You can safely bypass the warning).

You are then prompted for a User/password. Enter alice and wonderland (anything else should fail). Once you are logged in you can operate the servlet.