Procedure 16.1. 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>
   

   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
   

   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>
   

   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 16.2. 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>
   

   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 16.3. 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>
   

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 16.4. 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 16.5. 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):
   

   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
    

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 16.6. 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>
  

  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>
  

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

Procedure 16.7. 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>
   

3. Save the file and exit.

Procedure 16.8. 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:
   

   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>
   

5. Set the drools.serialization.sign property to "true":

   drools.serialization.sign=true
   

   • 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
   

Procedure 16.9. 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
   

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

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
   

   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
   

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
   

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" );
   ...
   

   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"
   

   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"
   

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

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>
   

4. Save the file and exit.

Procedure 16.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. 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>
   

3. Save the file and exit.

Procedure 16.11. Task

• Execute this code:

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

Procedure 16.12. 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 16.13. 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.