Copyright © Cloud Software Group, Inc. All Rights Reserved

Using Web Services Security Policies

TIBCO ActiveMatrix BusinessWorks allows you to specify security policies for inbound and outbound SOAP messages. The security policies follow Web Services Security: SOAP Message Security 1.0 (WS-Security 2004) OASIS Standard 200401. You can find out more about this standard at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.

You define security policies in the Security Policy shared configuration resource. You can define one policy to share among all of your web services, or you can define multiple policies to use on a per-resource basis. You can include the following attributes within a policy:

•	Authentication — whether messages must be authenticated. Authentication can be performed either with usernames and passwords or with X.509 compliant certificates.

•	Integrity — whether messages must be validated with a signature to ensure the message has not been altered since its creation.

•	Confidentiality — whether messages are encrypted or unencrypted.

•	Timeout — whether messages should expire after a certain time.

See TIBCO ActiveMatrix BusinessWorks Palette Reference for more information about the Security Policy Resource.

Errors encountered when using Web Service Security policies are generally not published. This is because malicious users could attempt to gain information about your security policy by attempting to replicate known errors. To prevent the general public from obtaining the Web Service Security error codes, only licensed customers can request a list of error messages and code by contacting TIBCO Support.

 

Associating Security Policies With Web Services

The Security Policy Association shared configuration resource allows you to associate a security policy with a web service. A security policy can either be associated with individual SOAP resources (SOAP Event Source, SOAP Request Reply, and so on), or it can be associated with each operation in a Service resource. You must create a Security Policy Association resource for each SOAP resource or Service operation to which you wish to apply a security policy.

Security Policy Association shared configuration resources are not referenced by resources in process definitions. Therefore, they are not automatically included in Enterprise Archive files. You must manually add WS Policy Association resources to the Shared Archive within an Enterprise Archive for the associations to work properly in a deployed project. See TIBCO Administrator User’s Guide for more information about adding resources to the Shared Archive.

When you associate a policy with a Service operation, the policy applies to all regular or fault inbound and outbound messages for the operation. When you associate a policy with a specific SOAP Resource, the appropriate security policies are applied to the messages sent or received by the resource. For example, a SOAP Event Source can only receive messages, therefore a security policy can only be applied to incoming messages. A SOAP Request Reply activity can send and receive messages, and it may also receive a fault message. Therefore, you can associate a security policy for the inbound, outbound, and inbound fault messages.

You can create more than one Security Policy Association resource for the same SOAP or Service resource in your project. This is not recommended because only the first policy assocation for the resource is used. All other policy associations are ignored.

To run a project with security policy associations successfully, ensure that all the policy associations in the project are valid. Any invalid associations must be removed from the project before running the project.

Custom Password Lookup

By default authentication is checked against the usernames and passwords stored in TIBCO Administrator. TIBCO Administrator can also point to an LDAP registry for username/password lookup. If you store usernames and passwords in your own database or LDAP system, you can write your own password callback class that implements the javax.security.auth.callback.CallbackHandler interface.

The CallbackHandler implementation must iterate over each Callback object and look for the WSPasswordCallback type. You can use the WSPasswordCallback.getIdentifyer() method to obtain the username. Then you can write code to lookup the password for that username in your system. Once obtained, you must set the password in the Callback object using the setPassword() method.

Here is a simple example of a CallbackHandler implementation:

 

public class MyPasswordCallback implements CallbackHandler {

      private HashMap passwords = new HashMap();

      public MyPasswordCallback() {

      }

      public void handle(Callback[] callbacks) throws IOException,

            UnsupportedCallbackException {

         for (int i = 0; i < callbacks.length; i++) {

            if (callbacks[i] instanceof WSPasswordCallback) {

               WSPasswordCallback pc =

                  (WSPasswordCallback) callbacks[i];

              String identifier = pc.getIdentifer();

              int usage = pc.getUsage();

              if (usage == WSPasswordCallback.USERNAME_TOKEN

           //usage ==WSPasswordCallback.USERNAME_TOKEN_UNKNOWN)

              {

               String pw = (String) passwords.get(sub);

               if(pw == null){

                  pw = lookupPassword(identifier);

                  //lookup password using any mechanism.

               }

                pc.setPassword(pw);

            }

         }

      }

   }

For more information about implementing the CallbackHandler interface, see the custom password examples in the BW_HOME/examples/activities/soap directory or see http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html.

To use custom password lookup in a security policy, perform the following procedure:

1.	Compile your Callback object into a .jar file.

2.	Open the TIBCO ActiveMatrix BusinessWorks project containing the processes for which you are creating security policies.

3.	Click the General palette and drag and drop an AliasLibrary resource into the design panel.

4.	Place your Callback object .jar file into the AliasLibrary resource, and also include any classes that your object depends on (for example, third-party classes for LDAP access). See Chapter 19, Sharing Common Resources with Other Projects for more information about using AliasLibrary resources.

5.	Click the Policy palette and drag and drop a Security Policy resource into the design panel. Alternatively, click an existing Security Policy resource to edit the resource.

6.	On the Configuration tab, click the checkbox in the Custom Password Lookup field.

7.	In the Custom Password Callback Java Class field, use the Browse button to locate and select the AliasLibrary resource you created in step 4.

8.	In the Class field, use the Show Class Browser button to locate and select your Callback object.

9.	Click Apply, then associate your security policy with the desired web services, if you have not already done so.

10.	Save the project.

 

Security Context Propagation from TIBCO ActiveMatrix Policy Manager

TIBCO ActiveMatrix BusinessWorks allows you to define security policies and associate them with web services such that these policies are applied to the inbound or\and outbound messages by associating security policies with web services. You can now choose not to apply inbound policies in ActiveMatrix BusinessWorks because ActiveMatrix BusinessWorks allows the propagation of security context from TIBCO ActiveMatrix Policy Manager.

TIBCO ActiveMatrix BusinessWorks can now propagate the security context information sent by TIBCO ActiveMatrix Policy Manager and map it to appropriate fields of the security context in ActiveMatrix BusinessWorks. The security context information is available only when a policy is applied and the information is sent by TIBCO ActiveMatrix Policy Manager.

ActiveMatrix Policy Manager sends security information as an XML document, either as part of the header when HTTP transport is used, or as a message property when JMS transport is used. The security information is available under the header com.tibco.security.userinformation.

When ActiveMatrix BusinessWorks Service resource or SOAP Event Source activity receives such a message, it processes the XML document from the header and propagates it in its output tab.

ActiveMatrix BusinessWorks propagates the incoming security context to all outbound invokes by adding the security information as a HTTP header in case of HTTP, or as a JMS message property in case of JMS transport. Figure 66 shows the Authentication Certificate Information and Signature Certificate Information as seen in the Output tab of a SOAP Event Source activity. In this case, the ActiveMatrix Policy Manager had applied the Authentication Signature inbound policy.

Figure 66 Security Context in SOAP Event Source activity Output tab

Enabling security context propagation from TIBCO Policy Manager

You can enable security context propagation from TIBCO Policy Manager by selecting the Expose Security Context checkbox available on the Configuration tab of the Service resource or the SOAP Event Source activity using either HTTP or JMS transport.

TIBCO ActiveMatrix BusinessWorks can propagate two types of security context information from ActiveMatrix Policy Manager -

•

Authentication Username Token - For this policy, TIBCO ActiveMatrix BusinessWorks propagates only the Username value. This is because TIBCO ActiveMatrix Policy Manager does not give out the complete Username Token. Instead, it provides only the Username. The password and the Password type values in the security context will be empty.

•	Authentication Certificate Information and Signature Certificate Information - For this policy, TIBCO ActiveMatrix BusinessWorks propagates the certificate information, consisting of Subject_DN, Issuer_DN, Serial No and the encoded certificate.

Available Security Contexts in ActiveMatrix BusinessWorks

Table 22 lists the inbound policies available in Policy Manager and the corresponding policies in ActiveMatrix BusinessWorks.

Table 22 Security Contexts Available in ActiveMatrix BusinessWorks

Inbound Policy in ActiveMatrix Policy Manager	Available Security Context in ActiveMatrix BusinessWorks
Authentication - IMS	Authentication Username Token
Crypto - Check Signature	Signature Certificate Information
Authentication Signature and Crypto - Check Signature	Authentication Certificate Information and Signature Certificate Information
Authentication Signature	Authentication Certificate Information and Signature Certificate Information
Authentication - IMS and Crypto - Check Signature	Authentication Username Token and Signature Certificate Information
Authentication - IMS and Crypto - Encrypt and Decrypt	Authentication Username Token and Signature Certificate Information

Limitations to Security Context Propagation from TIBCO ActiveMatrix Policy Manager

The number of security context types that TIBCO ActiveMatrix BusinessWorks propagates is restricted due to certain limitations.

•	For Authentication Username Token policy, only the Username value will be available. The password and Password Type values will be empty. This is because ActiveMatrix Policy Manager gives out only the Username in the security context.

•	ActiveMatrix BusinessWorks will not propagate any extra information given out by ActiveMatrix Policy Manager. For example, information such as User Role and User Attributes, given by ActiveMatrix Policy Manager will not be propagated.

•

ActiveMatrix Policy Manager does not propagate the Transport Security Context received from the client. Hence, the Transport Security Context node in ActiveMatrix BusinessWorks will never be populated with the clients transport security context, when the security context is propagated from ActiveMatrix Policy Manager.

•	Signature using Username Token is not available in ActiveMatrix Policy Manager. As a result, it cannot be supported by ActiveMatrix BusinessWorks when using ActiveMatrix Policy Manager.

Using JAAS Login for Authentication

TIBCO ActiveMatrix BusinessWorks uses persistent object framework (POF) API to authenticate with TIBCO Administrator in the standalone mode. Alternatively, you can authenticate TIBCO ActiveMatrix BusinessWorks using JAAS login using the following procedure.

To Authenticate With JAAS Login

1.	Run the TIBCO Domain Utility to create an administration domain and enable HTTPS.

2.	Create a text file named jaas.config and copy the following contents in it.

AuthenticationService {

com.tibco.atlas.auth.jaas.AuthenticationServiceLoginModule required

soap_username="a"

soap_password="#!1Go16wN7zB+OWxx+eTlB/w=="

authority="localhost:5443"

scheme="https";

};

Where soap_username is the super username of the admin server and soap_ password is the obfuscated password of the above user.

You can obtain the username and password information from the AdministrationDomain.properties file located in $TIBCO_Home\tra\domain\<domainName>. The username and password information is provided as a name-value pair with names ’UserID’ and ’Credential’ respectively. If you find any \ in the password, you need to remove them as they are escape characters.

authority="localhost:5443" specifies admin servers host and https port.

You can create the jaas.config file in any folder. However, you need to specify the path of the jaas.config file while setting the Java property com.tibco.bw.security.login.jaas in bwengine.xml.

3.	Edit the bwengine.xml file and recreate the EAR file before deploying the project.

4.	Add the following Java property in bwengine.xml:

java.property.java.security.auth.login.config=<path>\jaas.conf

where <path> specifies the path for the jaas.config file.

•	To use non-default location for keystores (that is, the location other than what JRE uses by default, jsr\1.5.0\lib\security\cacerts), add the following properties and set them with appropriate values.

For example, you can use the keystore from admin as follows:

java.property.javax.net.ssl.keyStore=C:\Tibco\administrator\domain\<domainName>\SSL\keystore

java.property.javax.net.ssl.keyStorePassword=password

java.property.javax.net.ssl.trustStore=C:\Tibco\administrator\domain\<domainName>\SSL\keystore

java.property.javax.net.ssl.trustStorePassword=password

where ’password’ specifies the default admin keystore password.

•	To use the default keystore, you need to export the certificates from Admin Server's keystore using keytool and import them in to jre's keystore.

5.	Enable the JAAS authentication by adding the following property in the bwengine.xml file:

java.property.com.tibco.bw.security.login.jaas=true

Following are the JAAS login properties that can be set in bwengine.xml. You can refer to these properties while configuring JAAS login:

<property>

<name>JAAS config</name>

<option>java.property.java.security.auth.login.config</option>

<default>C:\tibco\jaas\jaas.config</default>

<description>Used for setting the jaas configuration file</description>

</property>

<property>

<name>Admin Keystore</name>

<option>java.property.javax.net.ssl.keyStore</option>

<default></default>

<description>Sets the Admin Keystore</description>

</property>

<property>

<name>Keystore Password</name>

<option>java.property.javax.net.ssl.keyStorePassword</option>

<default>none</default>

<description>Sets the keystore password</description>

</property>

<property>

<name>admin truststore</name>

<option>java.property.javax.net.ssl.trustStore</option>

<default>none</default>

<description>Sets the admin truststore</description>

</property>

<property>

<name>truststore password</name>

<option>java.property.javax.net.ssl.trustStorePassword</option>

<default>none</default>

<description>sets the truststore password</description>

</property>

<property>

<name>JAAS Login</name> <option>java.property.com.tibco.bw.security.login.jaas</option>

<default>true</default>

<description>sets the JAAS to true or false</description>

</property>

Copyright © Cloud Software Group, Inc. All Rights Reserved