Administration Guide

Procedure 3.1. Start the JBoss Enterprise SOA Platform

• Start the SOA server in a server window

  • Red Hat Enterprise Linux

    1. Open a terminal and navigate to the bin directory by entering the command cd SOA_ROOT/jboss-as/bin.
    2. Enter ./run.sh to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)

  • Microsoft Windows

    1. Open a terminal and navigate to the bin directory by entering the command chdir SOA_ROOT\jboss-as\bin.
    2. Enter run.bat to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)

Procedure 3.2. Deploy the "Hello World" Quickstart

1. Check that the server has fully launched.
2. Open a second terminal window and navigate to the directory containing the quick start: cd SOA_ROOT/jboss-as/samples/quickstarts/helloworld (or chdir SOA_ROOT\jboss-as\samples\quickstarts\helloworld in Microsoft Windows).
3. Run ant deploy to deploy the quickstart. Look for messages such as this to confirm if the deployment was successful:

   deploy-esb:
        [copy] Copying 1 file to
   /jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy
   
   deploy-exploded-esb:
   
   quickstart-specific-deploys:
        [echo] No Quickstart specific deployments being made.
   
   display-instructions:
        [echo] 
        [echo] ******************
        [echo] Quickstart deployed to target JBoss ESB/App Server at
   '/jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy'.
        [echo] 1.  Check your ESB Server console to make sure the deployment was
   executed without errors.
        [echo] 2.  Run 'ant runtest' to run the Quickstart.
        [echo] 3.  Check your ESB Server console again.  The Quickstart should
   have produced some output.
        [echo] ******************
   
   deploy:
   
   BUILD SUCCESSFUL
   

   Copy to Clipboard Toggle word wrap
   Also, check for this in the SOA_ROOT/jboss-as/server/default/log/server.log:

   10:58:52,998 INFO  [NamingHelper] JNDI InitialContext properties:{}
   11:00:58,154 INFO  [QueueService]
   Queue[/queue/quickstart_helloworld_Request_esb] started, fullSize=200000,
   pageSize=2000, downCacheSize=2000
   11:00:58,186 INFO  [QueueService]
   Queue[/queue/quickstart_helloworld_Request_gw] started, fullSize=200000,
   pageSize=2000, downCacheSize=2000
   11:00:58,427 INFO  [EsbDeployment] Starting ESB Deployment
   'Quickstart_helloworld.esb'
   

   Copy to Clipboard Toggle word wrap
4. Run the quickstart by issuing this command: ant runtest. When the quickstart is run, messages such as this are written to the SOA_ROOT/jboss-as/server/default/log/server.log:

   11:03:02,190 INFO  [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
   11:03:02,191 INFO  [STDOUT] Body: Hello World
   11:03:02,191 INFO  [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
   11:03:02,192 INFO  [STDOUT] Message structure: 
   11:03:02,192 INFO  [STDOUT] [Hello World].
   

   Copy to Clipboard Toggle word wrap

Procedure 3.3. Task

1. Navigate to the quickstart's directory: cd SOA_ROOT/jboss-as/samples/quickstarts/helloworld (or chdir SOA_ROOT\jboss-as\samples\quickstarts\helloworld if you are running Microsoft Windows).
2. Run the ant undeploy command. You should see messages such as this displayed:

   undeploy:
   [delete] Deleting:
   /jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy/Quickstart_helloworld.esb
   
   BUILD SUCCESSFUL
   

   Copy to Clipboard Toggle word wrap
   And messages such as this written to the server.log:

   11:10:08,205 INFO  [EsbDeployment] Stopping 'Quickstart_helloworld.esb'
   11:10:08,577 INFO  [EsbDeployment] Destroying 'Quickstart_helloworld.esb'
   

   Copy to Clipboard Toggle word wrap

Procedure 3.4. Stop the JBoss Enterprise SOA Platform Server

• Stop the SOA server

  Press ctrl-c in the server window (the terminal window where the SOA server was started).

Procedure 4.1. Task

1. Study the quickstart's readme.txt file.
2. Run the ant help command in the quickstart's directory.

Procedure 5.1. Start the JBoss Enterprise SOA Platform in a Production Environment

1. Navigate to the bin Directory

   Open a terminal and input this command: cd SOA_ROOT/jboss-as/bin (or chdir SOA_Root\jboss-as\bin in Microsoft Windows).

   Note

   It is required that you have set up an administration username and password before proceeding.

2. Launch the JBoss Enterprise SOA Server on Red Hat Enterprise Linux

   To start the product, run this command: ./run.sh -c production

3. Launch the JBoss Enterprise SOA Server on Microsoft Windows

   To start the product, run this command: run.bat -c production

Procedure 5.2. Task

• To make the JBoss Enterprise SOA Platform run as a background daemon (service), you will have to create your own shell script. Red Hat does not supply any scripts to do this.

Procedure 5.3. Task

• To start the JBoss Enterprise SOA Platform as a service, issue this command: service jboss_soa start

  Note

  If the JBoss user was created as a system account (using the -R switch) then a warning message is displayed. You can safely ignore this.

Procedure 5.4. Task

• To stop the JBoss Enterprise SOA Platform when it is running as a service, issue this command: service jboss_soa stop

Procedure 6.1. Add a New User

1. Open the soa-users.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-users.properties. Add the user's name and password on a new line, using this syntax: username=password.
   Here is an example for a user with the login name "Harold":

   harold=@dm1nU53r
   

   Copy to Clipboard Toggle word wrap

   Note

   Any line in this file that begins with a hash (#) is ignored. (You can use this convention to temporarily disable a user account.)
2. Save the changes to the file and exit the text editor.
3. Open the soa-roles.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-roles.properties. Add the user and the roles you wish to assign to them on a new line, using this syntax: username=role1,role2,role3.

   harold=JBossAdmin,HttpInvoker,user,admin
   

   Copy to Clipboard Toggle word wrap

   Note

   You can assign any number of roles. Note that a user must be assigned the JBossAdmin, HttpInvoker, user and admin roles in order to be able to log into the server consoles.

   Any line in this file that begins with a hash (#) is ignored. You can use this convention to temporarily disable user roles.
4. Save the changes to the file and exit the text editor.

Procedure 6.2. Disable a User's Account

1. Open the soa-users.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-users.properties. Either delete the entire line containing the user's name and password or simply put a hash (#) in front of it to "comment it out."
   Here is an example for a user with the login name "Harold":

   #harold=@dm1nU53r
   

   Copy to Clipboard Toggle word wrap
2. Save the changes to the file and exit the text editor.

Procedure 6.3. Task

1. Obtain the Login Module (LM) located in org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule
2. Open the LM's configuration file.
3. Enter the following code, inserting the names of the services you wish to use:

   <application-policy name="saml-issue-token">
        <authentication>
            <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
                <module-option name="configFile">picketlink-sts-client.properties</module-option>
                <module-option name="endpointURI">http://security_saml/goodbyeworld</module-option>
            </login-module>
            <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">
                <module-option name="configFile">picketlink-sts-client.properties</module-option>
            </login-module>
        </authentication>
    </application-policy>
   

   Copy to Clipboard Toggle word wrap
   This configuration uses a stacked LM. The security token from the first LM is later used by the second LM which will validate the security token. Having two separate LMs for this can be useful as there can be situations where you only need to validate a security token.
4. Specify the picketlink-sts-client properties:

   serviceName=PicketLinkSTS
   portName=PicketLinkSTSPort
   endpointAddress=http://localhost:8080/picketlink-sts/PicketLinkSTS
   username=admin
   password=admin
   

   Copy to Clipboard Toggle word wrap

   Note

   The username and password in this file are only used by the STSValidatingLoginModule. The username and password may also be stacked or provided by a callback.
5. To use this LM in JBossESB you need to update your server's login-config.xml with the above application-policy. You must also point the ESB service to where you want this LM to be used.
   For example, this is how you could configure it in jboss-esb.xml:

   <service category="SamlSecurityQuickstart" name="issueTokenService" invmScope="GLOBAL"
       description="This service demonstrates how a service can be configured to issue and validate a security token">
   
    
   
       <security moduleName="saml-issue-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSIssueCallbackHandler">
           <!-- disable the security context timeout so that our security context is re-evaluated -->
           <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>
       </security>
       ...
   </service>
   

   Copy to Clipboard Toggle word wrap
   The callbackHandler that is is specified is specific to the ESB. This is because it requires access to the authentication request in the ESB for retreiving the username and password of the user for whom a security token should be issued.

Procedure 6.4. Task

1. Open the Login Module (LM) from org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule.
2. Configure the properties file as shown in the example below:

           <application-policy name="saml-validate-token">
       <authentication>
           <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">
               <module-option name="configFile">picketlink-sts-client.properties</module-option>
           </login-module>
       </authentication>
   </application-policy>
   
    
   
   And in jboss-esb.xml:
   <service category="SamlSecurityQuickstart" name="securedSamlService" invmScope="GLOBAL"
       description="This service demonstrates that an ESB service can be configured to only validate a security token.">
   
       <security moduleName="saml-validate-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSTokenCallbackHandler">
           <!-- disable the security context timeout so that our security context is re-evaluated -->
           <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>
       </security>
       ...
   </service>
   

   Copy to Clipboard Toggle word wrap

   Note

   The callbackHandler that is specified is specific to the ESB. This is because it requires access to the authentication request in the ESB for retreiving the SAML Token which is to be validated.

   Note

   An example of SAML support in JBossESB can be found in the security_saml quickstart. More information about the Login Modules provied by PicketLink can be found at http://www.jboss.org/community/wiki/STSLoginModules

Procedure 7.1. Task

1. Scroll down to the section that contains properties name="security" and edit the settings to suit your system:

   <properties name="security"> 
   <property name="org.jboss.soa.esb.services.security.implementationClass"
   value="org.jboss.internal.soa.esb.services.security.JaasSecurityService"/>
   
   <property name="org.jboss.soa.esb.services.security.callbackHandler" 
   value= 
   "org.jboss.internal.soa.esb.services.security.UserPassCallbackHandler"/>
           
   <property name="org.jboss.soa.esb.services.security.sealAlgorithm" 
   value="TripleDES"/> 
   
   <property name="org.jboss.soa.esb.services.security.sealKeySize" 
   value="168"/>
   
   <property name="org.jboss.soa.esb.services.security.contextTimeout" 
   value="30000"/>
   
   <property name= 
   "org.jboss.soa.esb.services.security.contextPropagatorImplemtationClass" 
   value= 
   "org.jboss.internal.soa.esb.services.security.JBossASContextPropagator"/>
           
   <property name="org.jboss.soa.esb.services.security.publicKeystore" 
   value="/publicKeyStore"/> 
   
   
   <property name="org.jboss.soa.esb.services.security.publicKeystorePassword" 
   value="testKeystorePassword"/> 
   
   <property name="org.jboss.soa.esb.services.security.publicKeyAlias" 
   value="testAlias"/> 
   
   <property name="org.jboss.soa.esb.services.security.publicKeyPassword" 
   value="testPassword"/> 
   
   <property name="org.jboss.soa.esb.services.security.publicKeyTransformation" 
   value="RSA/ECB/PKCS1Padding"/> 
   
   </properties>
   

   Copy to Clipboard Toggle word wrap
2. Save the file and exit.
3. Open the log-in configuration file in your text editor: vi SOA_ROOT/server/PROFILE/conf/login-config.xml
4. Configure the JAAS log-in modules by editing the settings in this file. (You can use either a pre-configured option or create your own custom solution.)
5. Save the file and exit.

Procedure 7.2. Task

1. Go to the conf directory: cd SOA_ROOT/jboss-as/server/PROFILE/conf
2. Execute this command: java -cp ../../../lib/jbosssx.jar org.jboss.security.plugins.FilePassword welcometojboss 13 testpass esb.password

Procedure 7.3. Task

1. Generate a key pair using this command: keytool -genkey -alias jboss -keyalg RSA -keysize 1024 -keystore password.keystore and follow the prompts:

           keytool -genkey -alias jboss -keyalg RSA -keysize 1024 -keystore password.keystore
   Enter keystore password:  
   Re-enter new password: 
   What is your first and last name?
     [Unknown]:  Bob Bobson
   What is the name of your organizational unit?
     [Unknown]:  Corporate_IT
   What is the name of your organization?
     [Unknown]:  XYZ
   What is the name of your City or Locality?
     [Unknown]:  BRISBANE
   What is the name of your State or Province?
     [Unknown]:  QLD
   What is the two-letter country code for this unit?
     [Unknown]:  AU
   Is CN=Bob Bobson, OU=Corporate_IT, O=XYZ, L=BRISBANE, ST=QLD, C=AU correct?
     [no]:  yes
   
   Enter key password for jboss
   	(RETURN if same as keystore password):
   

   Copy to Clipboard Toggle word wrap

   Note

   You must specify the same password for the key store and key pair.
2. Run chown to change ownership to the JBoss Application Server process owner, and chmod 600 password.keystore to make sure only the file's owner can read it.

   Note

   The process owner should not have console log-in access. In that case you will be performing these operations as another user. Creating masked passwords requires read access to the key store, so you may wish to complete configuration of masked passwords before restricting the key store file permissions.
3. Navigate to the jboss-as/bin directory: cd SOA_ROOT/jboss-as/bin
4. Run the password tool, using the command ./password_tool.sh on Red Hat Enterprise Linux systems, (or password_tool.bat on Microsoft Windows-based systems.)
5. Select 0: Encrypt Keystore Password by pressing 0, then Enter.
6. Enter the key store password you specified above.
7. Enter a random string of characters to aid with encryption strength. This is the salt.
8. Enter a whole number for the iterator count to aid with encryption strength.
9. Select 5: Exit to exit.

   Note

   The password tool will exit with the message: Keystore is null. Cannot store. This is normal.
10. Use the chown command to change ownership of the password/jboss_keystore_pass.dat file to the process owner, and chmod 600 jboss-keystore_pass.dat to ensure that only that owner can read the file.
11. Navigate to the jboss-as/bin directory: cd SOA_ROOT/jboss-as/bin
12. Run the password tool, using the command ./password_tool.sh on Red Hat Enterprise Linux systems (or password_tool.bat on Microsoft Windows systems).
13. Select 1: Specify KeyStore by pressing 1 then Enter.
14. Enter the path to the key store you created above. (You can specify an absolute path, or the path relative to SOA_ROOT/jboss-as/bin. This should be SOA_ROOT/jboss-as/bin/password.keystore, unless you have changed the defaults.)
15. Enter the key alias. This should be "jboss" (unless you have performed an advanced installation and changed the defaults).
16. Select 2: Create Password by pressing 2, then Enter. You will be prompted for the security domain. Follow the prompts on screen.

            /password_tool.sh 
    **********************************
    ****  JBoss Password Tool********
    **********************************
    Error while trying to load data:Encrypted password file not located
    Maybe it does not exist and need to be created.
    0: Encrypt Keystore Password 1:Specify KeyStore 2:Create Password  3: Remove a domain 4:Enquire Domain 5:Exit
    1
    Enter Keystore location including the file name
    password.keystore
    Enter Keystore alias
    jboss
    0: Encrypt Keystore Password 1:Specify KeyStore 2:Create Password  3: Remove a domain 4:Enquire Domain 5:Exit
    2
    Enter security domain:
    
    default
    Enter passwd:
    passwordmask
    Password created for domain:default
    0: Encrypt Keystore Password 1:Specify KeyStore 2:Create Password  3: Remove a domain 4:Enquire Domain 5:Exit
    

    Copy to Clipboard Toggle word wrap
17. Enter a name for the password mask. This is an arbitrary unique name that you will use to identify the password mask in configuration files.
18. Enter the password that you wish to mask.
19. Repeat the password mask creation process to create masks for all passwords you wish to mask.
20. Exit the program by choosing 5: Exit
21. Navigate to the password directory: cd SOA_ROOT/jboss-as/bin/password

Procedure 7.4. Task

• Launch a text editor and replace each occurrence of a clear text password in the configuration files with an annotation referencing its mask.
  This is the general form of the annotation:

  <annotation>
  @org.jboss.security.integration.password.Password(securityDomain=MASK_NAME, methodName=setPROPERTY_NAME)
  </annotation>
  

  Copy to Clipboard Toggle word wrap
  As a concrete example, the JBoss Messaging password is stored in the server profile's deploy/messaging/messaging-jboss-beans.xml file. If you create a password mask named "messaging", then the before and after snippet of the configuration file will looks like this:

  <property name="suckerPassword">
  CHANGE ME!!
  </property>
  

  Copy to Clipboard Toggle word wrap

  <annotation>
  @org.jboss.security.integration.password.Password(securityDomain=messaging,
  methodName=setSuckerPassword)
  </annotation>
  

  Copy to Clipboard Toggle word wrap

Procedure 7.5. Task

1. Open the security configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/security/security-jboss-beans.xml.
2. Edit the key store location and key alias. Here are some example settings:

   <!-- Password Mask Management Bean-->
      <bean name="JBossSecurityPasswordMaskManagement"
            class="org.jboss.security.integration.password.PasswordMaskManagement" >
            <property name="keyStoreLocation">password/password.keystore</property>
            <property name="keyStoreAlias">jboss</property>
            <property name="passwordEncryptedFileName">password/jboss_password_enc.dat</property>
            <property name="keyStorePasswordEncryptedFileName">password/jboss_keystore_pass.dat</property>
      </bean>
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.

Procedure 7.6. Task

1. Navigate to the SOA_ROOT directory: cd SOA_ROOT.
2. Run the keytool command and follow the prompts on screen:

   keytool -genkey -alias droolsKey -keyalg RSA -keystore MyDroolsPrivateKeyStore.keystore
   Enter keystore password:  
   Re-enter new password: 
   What is your first and last name?
     [Unknown]:  Test User
   What is the name of your organizational unit?
     [Unknown]:  HR
   What is the name of your organization?
     [Unknown]:  Test Org
   What is the name of your City or Locality?
     [Unknown]:  Brisbane
   What is the name of your State or Province?
     [Unknown]:  QLD
   What is the two-letter country code for this unit?
     [Unknown]:  AU
   Is CN=Test User, OU=HR, O=Test Org, L=Brisbane, ST=QLD, C=AU correct?
     [no]:  yes
   Enter key password for droolsKey
        (RETURN if same as keystore password):  
   Re-enter new password:
   

   Copy to Clipboard Toggle word wrap
   After answering all of the questions, a password-protected file named MyDroolsPrivateKeyStore.keystore is created. This keystore file has a private key called droolsKey with the password "drools". Store this file in a safe location in your environment, which will hereafter be referred to as the keystoredir.

   Important

   The passwords above are examples only and should not be used in production.
3. Open the configuration file: vi jboss-as/server/default/deploy/properties-service.xml
4. Configure the JBoss Enterprise SOA Platform to use the JBoss Rules serialization feature by adding this snippet to properties-service.xml:

   <mbean code="org.jboss.varia.property.SystemPropertiesService"  name="jboss:type=Service,name=SystemProperties">
       <attribute name="Properties">
         # Drools Security Serialization specific properties
         drools.serialization.sign=true
         drools.serialization.private.keyStoreURL=file://$keystoredir/MyDroolsPrivateKeyStore.keystore
         drools.serialization.private.keyStorePwd=drools
         drools.serialization.private.keyAlias=droolsKey
         drools.serialization.private.keyPwd=drools
       </attribute>
   </mbean>
   

   Copy to Clipboard Toggle word wrap
5. Set the drools.serialization.sign property to "true":

   drools.serialization.sign=true
   

   Copy to Clipboard Toggle word wrap
   • drools.serialization.private.keyStoreURL=<RL> is the URL of the private keystore location.
   • In the example above, replace keystoredir and MyDroolsKeyStore.keystore with your keystore directory and the name of the keystore you created with the keytool
   • drools.serialization.private.keyStorePwd=<password> is the password to access the private keystore.
   • drools.serialization.private.keyAlias=<key> is the key alias (identifier) of the private key.
   • drools.serialization.private.keyPwd=<password> is the private key password.
6. Save the file and exit.
7. Restart the server instance.

   Warning

   If the system properties were not configured properly, you will see this error when you try to build a rules package:

   An error occurred building the package.
   
   Error
   signing object store: Key store with private key not configured. Please
   configure it properly before using signed serialization
   

   Copy to Clipboard Toggle word wrap

Procedure 7.7. Task

1. Create a public key certificate from the private keystore. (You can access the keytool by running keytool -genkey -alias droolsKey -keyalg RSA -keystore.):

   keytool -export -alias droolsKey -file droolsKey.crt -keystore
   

   Copy to Clipboard Toggle word wrap

       
   MyDroolsPrivateKeyStore.keystore 
   Enter keystore password:  
   Certificate stored in file <droolsKey.crtU>
   

   Copy to Clipboard Toggle word wrap
2. Import the public key certificate into a public keystore. (This is where it will be used by your client applications):

   keytool -import -alias droolsKey -file droolsKey.crt -keystore
   

   Copy to Clipboard Toggle word wrap

   MyPublicDroolsKeyStore.keystore
   Enter keystore password:  
   Re-enter new password: 
   Owner: CN=Test User, OU=Dev, O=XYZ Corporation, L=Brisbane, ST=QLD, C=AU
   Issuer: CN=Test User, OU=Dev, O=XYZ Corporation, L=Brisbane, ST=QLD, C=AU
   Serial number: 4ca0021b
   Valid from: Sun Sep 26 22:31:55 EDT 2010 until: Sat Dec 25 21:31:55 EST 2010
   Certificate fingerprints:
        MD5:  31:1D:1B:98:59:CC:0E:3C:3F:57:01:C2:FE:F2:6D:C9
        SHA1: 4C:26:52:CA:0A:92:CC:7A:86:04:50:53:80:94:2A:4F:82:6F:53:AD
        Signature algorithm name: SHA1withRSA
        Version: 3
   Trust this certificate? [no]:  yes
   Certificate was added to keystore
   

   Copy to Clipboard Toggle word wrap
3. Open the server configuration file: vi grep drools jboss-as/server/default/deploy/properties-service.xml
4. Replace keystoredir and MyPublicDroolsKeyStore.keystore with your keystore directory, and the name of the public keystore you created previously:

   # Drools Client Properties for Security Serialization
   drools.serialization.public.keyStoreURL=file://$keystoredir/MyPublicDroolsKeyStore.keystore
   drools.serialization.public.keyStorePwd=drools
   

   Copy to Clipboard Toggle word wrap
5. Save the file and exit.
6. Restart the JBoss Enterprise SOA Platform server.
7. For Java client applications, set the system properties in your code like this:

   // Set the client properties to deserialize the signed packages
   URL clientKeyStoreURL = getClass().getResource( "MyPublicDroolsKeyStore.keystore" );
   System.setProperty( KeyStoreHelper.PROP_SIGN,
                               "true" );
   System.setProperty( KeyStoreHelper.PROP_PUB_KS_URL,
                               clientKeyStoreURL.toExternalForm() );
   System.setProperty( KeyStoreHelper.PROP_PUB_KS_PWD,
                               "drools" );
   ...
   

   Copy to Clipboard Toggle word wrap
   Alternatively, open the run.sh shell script (vi SOA_ROOT/jboss-as/bin/run.sh) script and edit the JAVA_OPTS section:

   # Serialization Security Settings
   JAVA_OPTS="-Ddrools.serialization.sign=true $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.private.keyStoreURL=file://$keystoredir/MyDroolsKeyStore.keystore $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.private.keyStorePwd=drools $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.private.keyAlias=droolsKey $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.private.keyPwd=drools $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.public.keyStoreURL=file://$keystoredir/MyPublicDroolsKeyStore.keystore $JAVA_OPTS"
   JAVA_OPTS="-Ddrools.serialization.public.keyStorePwd=drools $JAVA_OPTS"
   

   Copy to Clipboard Toggle word wrap
   Replace the values shown above with ones specific to your environment, and then restart the server instance.

1. Open the configuration file: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/properties-service.xml.
2. Remove the drools.serialization.sign property's value.
3. Save the file and exit.
   An alternative way to do this task is to open the run.sh shell script (vi SOA_ROOT/jboss-as/bin/run.sh) and edit it as follows:

   JAVA_OPTS="-Ddrools.serialization.sign=false $JAVA_OPTS"
   

   Copy to Clipboard Toggle word wrap
4. Restart the server instance.
5. To turn signing off for Java client applications, remove the drools.serialization.sign property or add the following snippet to each application's code:

   System.setProperty( KeyStoreHelper.PROP_SIGN, "false" );
   

   Copy to Clipboard Toggle word wrap

1. Open the global configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployer/jboss-esb.xml.
2. Scroll down to the service you want to configure.
3. Add a security element. This setting shows you how to do so:

   <service category="Security" name="SimpleListenerSecured"> 
      <security moduleName="messaging" runAs="adminRole"
       rolesAllowed="adminRole, normalUsers"
       callbackHandler="org.jboss.internal.soa.esb.services.security.UserPassCallbackHandler"> 
   	    <property name="property1" value="value1"/> 
   	    <property name="property2" value="value2"/> 
      </security>
      ...
   </service>
   

   Copy to Clipboard Toggle word wrap
4. Save the file and exit.

Procedure 7.8. Task

1. Open the global configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployer/jbossesb-properties.xml.
2. Configure the setting in question. Here is an example:

   <security moduleName="messaging" 
     runAs="adminRole" rolesAllowed="adminRole">
   
   <property 
       name="org.jboss.soa.esb.services.security.contextTimeout" 
       value="50000"/> 
     
   <property name=
   "org.jboss.soa.esb.services.security.contextPropagatorImplementationClass"
       value="org.xyz.CustomSecurityContextPropagator" /> 
   
   </security>
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.

Procedure 7.9. Task

• Execute this code:

  byte[] encrypted = PublicCryptoUtil.INSTANCE.encrypt((Serializable)
   authRequest);
  message.getContext.setContext(SecurityService.AUTH_REQUEST, encrypted);
  

  Copy to Clipboard Toggle word wrap

Procedure 7.10. Task

1. Open the global configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployer/jbossesb-properties.xml.
2. Scroll down to the section that contains security.contextTimeout. Set the time-out value (in milliseconds).
3. Save the file and exit.

Procedure 7.11. Task

1. Open the service's configuration file in a text editor: vi jboss-esb.xml.
2. Scroll down to the section that contains Security Context. Set the time-out value (in milliseconds).
3. Save the file and exit.

Procedure 8.1. Task

1. Open the log-in configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/login-config.xml
2. Add the details of your custom log-in module.
3. Save the file and exit.
4. Since different log-in modules require different information, you must specify the CallbackHandler attribute to be used. Open the specific security configuration for that service.
5. Make sure that the CallbackHandler specifies a fully-qualified classname for the class which implements the EsbCallbackHandler interface. This code shows you how to do so:

   public interface EsbCallbackHandler extends CallbackHandler
   {
     void setAuthenticationRequest(final AuthenticationRequest authRequest);
     void setSecurityConfig(final SecurityConfig config);
   }
   

   Copy to Clipboard Toggle word wrap
6. Add both the "principle" and the credentials needed to authenticate a caller to the AuthenticationRequest class.

Procedure 8.2. Task

1. Open the log-in configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/login-config.xml
2. Set the rolesPropertiesFile property. (This property can point to a file located on either the local file system or the class-path).
3. Map users to roles. This example code shows how to do so:

   # user=role1,role2,...
   guest=guest
   esbuser=esbrole
   # The current implementation will use the Common Name(CN) specified
   # for the certificate as the user name.
   # The unicode escape is needed only if your CN contains a space
   Andy\u0020Anderson=esbrole,worker
   

   Copy to Clipboard Toggle word wrap
4. Save the file and exit.

Procedure 8.3. Task

1. Implement the SecurityService interface:

   public interface SecurityService
   {
       void configure() throws ConfigurationException;
   
       void authenticate(
           final SecurityConfig securityConfig, 
           final SecurityContext securityContext, 
           final AuthenticationRequest authRequest) 
           throws SecurityServiceException;
   
       boolean checkRolesAllowed(
           final List<String> rolesAllowed, 
           final SecurityContext securityContext);
   
       boolean isCallerInRole(
           final Subject subject, 
           final Principle role);
   
       void logout(final SecurityConfig securityConfig);
   
       void refreshSecurityConfig();
   }
   

   Copy to Clipboard Toggle word wrap
2. Open the global configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployer/jbossesb-properties.xml.
3. Configure the file to use the customized SecurityService
4. Save the file and exit.

Procedure 8.4. Task

1. Edit the Settings in the jboss-service.xml File

   Open the file in a text editor: vi SOA_ROOT/server/PROFILE/conf/jboss-service.xml

2. Configure the Settings in the File

   Here is an example:

   <attribute name="DownloadServerClasses">false</attribute>
   

   Copy to Clipboard Toggle word wrap
   Set this value to false to ensure that client applications can only download Enterprise Java Bean classes.

   Important

   By default, this value is set to false in the SOA Platform's 'production' profile. The value is set to true in all other cases, including the SOA Standalone version's default profile. Note that this is not a secure configuration and should only be used in development environments.

Procedure 9.1. Task

1. Make a GetAuthToken() request.
2. A GetAuthToken object is returned. Set a userid and credential (password) on this object:

   org.uddi.api_v3.GetAuthToken ga = new org.uddi.api_v3.GetAuthToken();
   ga.setUserID(pubId);
   ga.setCred("");
   
   org.uddi.api_v3.AuthToken token = securityService.getAuthToken(ga);
   

   Copy to Clipboard Toggle word wrap
3. Locate the juddi.properties configuration file in SOA_ROOT/jboss-as/server/PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF. Open it in a text editor.
4. Configure the juddi.authenticator property to how the Service Registry will check the credentials passed to it by the GetAuthToken request. (By default it uses the jUDDIAuthenticator implementation.)
5. Save the file and exit.

Procedure 9.2. Task

1. Create a text file called juddi-users.xml and save it in jbossesb-registry.sar.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <juddi-users>
       <user userid="sscholl" password="password" />
       <user userid="dsheppard" password="password" />
       <user userid="vbrittain" password="password" />
   </juddi-users>
   

   Copy to Clipboard Toggle word wrap
2. Save the file and exit.
3. Add the file to the class-path.
4. Open the juddi.properties file in your text editor (located in SOA_ROOT/jboss-as/server/PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF).
5. Modify the file so that it looks like this:

   juddi.authenticator = org.apache.juddi.auth.XMLDocAuthentication
   juddi.usersfile = juddi-users.xml
   

   Copy to Clipboard Toggle word wrap
6. Save the file and exit.

Procedure 9.3. Task

1. Locate the juddi.properties file in SOA_ROOT/jboss-as/server/PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF. Open it in your text editor.
2. Add the following configuration settings:

   juddi.authenticator=org.apache.juddi.auth.LdapSimpleAuthenticator
   juddi.authenticator.url=ldap://localhost:389
   

   Copy to Clipboard Toggle word wrap
   The juddi.authenticator.url property tells the LdapSimpleAuthenticator class where the LDAP server resides.
3. Save the file and exit.

Procedure 9.4. Task

1. Locate the juddi.properties file in SOA_ROOT/jboss-as/server/PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF. Open it in your text editor.
2. Add the following lines to the file:

   uddi.auth=org.apache.juddi.auth.JBossAuthenticator
   juddi.securityDomain=java:/jaas/other
   

   Copy to Clipboard Toggle word wrap
   The juddi.authenticator property connects the JbossAuthenticator class to the jUDDI Registry's Authenticator framework. The juddi.security.domain tells JBossAuthenticator where it can find the Application Server's security domain. It uses this domain to perform the authentications.
   Note that JBoss creates one security domain for each application policy element in the SOA_ROOT/jboss-as/server/PROFILE/conf/login-config.xml file. These domains are bound to the server JNDI tree with this name: java:/jaas/<application-policy-name>. (If a look-up refers to a non-existent application policy, a policy named other will be used by default.)
3. Save the file and exit.

Procedure 10.1. Running the Admin Console

1. Launch the Console in a Web Browser

   Open http://localhost:8080/admin-console in a web browser.

2. Authenticate to the Console

   Enter your Username and Password as set in SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-users.properties.

Procedure 10.2. Task

1. Launch a web browser and go to localhost:8080/admin-console.
2. Input admin as the username and password.
3. To view the queue, click on Resources, JBoss Messaging and then Queues.

Procedure 13.1. Task

1. Click on JBoss ESB Statistics (above the Resources menu) to "drill down" through various levels of statistics.
   On the first level, the figures displayed are a summary for the overall ESB instance.
2. Click on the JBoss ESB Deployment item to view a list of all of the Enterprise Service Bus packages deployed on the server. One will not see any statistics at this level but, from here, one can select a deployment and drill down into it to view them.
3. Drill down further still to view details for that deployment's constituent services and actions.

Procedure 13.2. Task

1. Open a web browser and log into the JON for SOA Console.
2. Go to the JBoss ESB Statistics screen.
3. Click on the INVENTORY tab
4. Go to Child Resources.

   Note

   You can view historical deploy requests here as well.
5. Go to the Create New menu and select JBoss ESB Deployment.
6. On the Create New Resource page, choose the archive to deploy and select where it should be sent (which, under normal circumstance, will be your deploy directory).

   Note

   Remember that only compressed files can be uploaded: use the Deploy Zipped option to determine whether it should be deployed as a compressed or an exploded archive.

Procedure 13.3. Task

1. Open a web browser and log into the JON for SOA Console.
2. Go to the JBoss ESB Statistics screen.
3. Click on the INVENTORY tab
4. Go to Child Resources list.
5. Tick the entry to be deleted.
6. Click DELETE

   Note

   You can view historical delete requests here as well.

Procedure 13.4. Task

1. Open the configuration file installed with the JON Agent in a text editor: vi rhq-agent/conf/agent-configuration.xml
   Edit the file as per this example code:

   <entry key="rhq.agent.plugins.service-discovery.period-secs" value="86400"/>
   

   Copy to Clipboard Toggle word wrap
2. Save the file and exit.
3. Restart the JBoss Enterprise SOA Platform.
   In contrast to the JBoss Enterprise SOA Platform consoles, there is no way to force the JON web console to collect new data on demand. Clicking on buttons such as Get Current Values (found under the Metric Data tab) only updates the display to reflect the most recently collected data. If you want an an update immediately, reset the collection period to a very low value, such as thirty seconds. (Remember to set the interval back to the previous figure afterwards.)

   Important

   If you set the value to too low a figure, performance will suffer.

Procedure 13.5. Task

1. Open a web browser and log into the JON for SOA console.
2. Add a JON agent to the server's inventory of resources.
3. Click on CONFIGURE.
4. Change the value for Service Discovery Period.

   Note

   You do not need to restart the agent for the change to take effect.

Procedure 14.1. Task

1. Open a web browser session and go to the jUDDI Console at http://localhost:8080/uddi-console/. Log in as root.
2. Click "Publisher".
3. From the Publisher ID list, click on the username.
4. Select the "Is Admin" checkbox.

Procedure 16.1. Task

1. Launch a web browser and go to http://localhost:8080/bpel-console.
2. Input your user name and password.
3. Click on the Manage Instances tab to see which BPEL processes are currently deployed. You will also see version information for each of these processes.
4. Select a process definition to open it. In the bottom panel you will see a list of process instances that are active for that particular definition.

   Note

   Only one version of a process can be active at a time. When you open a process definition, the active version is automatically selected.
5. Sometimes you will find that you need to manage a "retired" version (for example, in order to terminate running instances). In these cases, click More - Change Version and then select the version you want.

   Note

   If there is no version for a particular process archive, (such as Quickstart_bpel_simple_invoke.jar), it is treated as version zero. (In this case, Quickstart_bpel_simple_invoke-1.jar, will be the next version deployed.)

Procedure 16.2. Task

1. Launch a web browser and go to http://localhost:8080/bpel-console.
2. Input your user name and password.
3. Click on the Manage Instances tab to see which BPEL processes are currently deployed. You will also see version information for each of these processes.
4. Select a process definition to open it. In the bottom panel you will see a list of process instances that are active for that particular definition.
5. Use the Execution History to produce a chart. Here you can specify a particular period of time to review and choose whether or not to include failed and terminated instances in the chart.

Procedure 16.3. Task

1. Open the deploy.xml file in a text editor (for the bpel_helloworld quick start, this would be vi SOA_ROOT/jboss-as/samples/quickstarts/bpel_hello_world/bpelContent/deploy.xml
2. Edit the file as follows:

   <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
    xmlns:bpl="http://www.jboss.org/bpel/examples" 
    xmlns:intf="http://www.jboss.org/bpel/examples/wsdl">
   
    <process name="bpl:HelloGoodbye">
     <active>true</active>
           <process-events generate="all"/>
     <provide partnerLink="helloGoodbyePartnerLink">
      <service name="intf:HelloGoodbyeService" port="HelloGoodbyePort"/>
     </provide>
    </process>
   </deploy>
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.
4. Open the bpel.properties file in the text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/riftsaw.sar/bpel.properties
5. Switch on the process-events option for the particular process you want to log and make sure that org.jboss.soa.bpel.console.bpaf.BPAFLogAdapter is enabled.
6. Save the file and exit.

Procedure 16.4. Task

1. Launch a web browser and go to http://localhost:8080/bpel-console.
2. Input your user name and password.
3. Click on the Manage Instances tab to see which BPEL processes are currently deployed. You will also see version information for each of these processes.
4. Select a process definition to open it. In the bottom panel you will see a list of process instances that are active for that particular definition.

   Note

   Only one version of a process can be active at a time. When you open a process definition, the active version is automatically selected.
5. Click the Instance Data button.
6. The View tab shows the instance execution graph, while the Source tab below it shows all of the "activity" events.

Procedure 16.5. Task

1. Launch a web browser and go to http://localhost:8080/bpel-console.
2. Input your user name and password.
3. Click on the Manage Instances tab to see which BPEL processes are currently deployed. You will also see version information for each of these processes.
4. Select a process definition to open it. In the bottom panel you will see a list of process instances that are active for that particular definition.

   Note

   Only one version of a process can be active at a time. When you open a process definition, the active version is automatically selected.
5. Click on the Execution Path button to see an instance execution graph for the process.

Procedure 16.6. Task

1. Log into the BPEL Web Console.
2. Choose a process definition and a process status from the list box.
   You can also optionally choose to input the correlation key, the start time and the end time as search criteria.
3. Go to the History Instances List and double-click on a row. A window will pop up showing you all of the execution events that happened when that process ran.

Procedure 16.7. Task

1. Launch a web browser and go to http://localhost:8080/bpel-console.
2. Input your user name and password.
3. Click on the Runtime tab.
4. Select the Deployments option.
   You will now be able to see the version information and current status (active or retired) of each process definition.
5. Select the particular version of the process definition you want to retire and then press the Retire button.

   Note

   If you undeploy a process, its end-points will only deactivate if no previous versions of that process have ever existed.