Specifying Security Settings for SOAP RA Web Service Agent Connection Objects

Security settings for SOAP RA Web Service Agent Connection objects can be set by selecting the Security menu item.

Some .wsdl files require authentication specifications to the end URL. To enter them:

Select an option from the Authentication field.

This field allows you to select Basic, Digest, NTLM, or Kerberos, or to leave the default of None to not use an authentication mechanism.

Respond to the authentication-specific fields. Although not all of these fields are required by the RA Web Service Agent, they may need values for the authentication mechanism to work.

For	Field	Description
Basic and Digest	User	The user name.
	Password	The password.
	Host	The host to connect to.
	Port	The port to use.
	Realm	The realm.
	Preemptive	Activates preemptive authentication. Preemptive authentication sends the authentication information without waiting for the server to give an unauthorized response. This reduces some overhead, and may be required in cases where the server does not reply with an unauthorized response. You use preemptive authorization when you trust the endpoint enough to send authentication credentials somewhere without being asked for them.
NTLM	User	The user name.
NTLM	Password	The password.
Kerberos*	User	The user name.
Kerberos*	Password	The password.

* Previous releases of the RA Web Service Agent had additional Kerberos settings specified in the Connection object. Now all Kerberos settings other than User and Password are set in the krb.ini (.conf) file. If you upgraded from a previous version with other settings defined in the Connection object or you create a new Connection object with Kerberos authentication, you need to create/edit the krb.ini (.conf) file. The Agent itself does not read this file directly, it uses the Kerberos classes of the JRE.

The algorithm to locate the krb5.conf file is the following:

If the system property java.security.krb5.conf is set, its value is assumed to specify the path and file name.
If that system property value is not set, the configuration file is looked for in the directory:

<java-home>\lib\security (Windows)
<java-home>/lib/security (Solaris and Linux)

Here <java-home> refers to the directory where the JRE is installed. For example, if you have J2SE 5.0 installed on Solaris in a directory named /j2sdk1.5, the directory in which the configuration file is looked for is:

/j2sdk1.5/jre/lib/security

If the file is still not found, then an attempt is made to locate it as follows:

/etc/krb5/krb5.conf (Solaris)
c:\winnt\krb5.ini (Windows)
/etc/krb5.conf (Linux)

If the file is still not found, and the configuration information being searched for is not the default realm and KDC, then implementation-specific defaults are used. If, on the other hand, the configuration information being searched for is the default realm and KDC because they weren't specified in system properties, and the krb5.conf file is not found either, an exception is thrown.

Creating and Editing Policy Files

To create or edit web service policy file, pick WS-Security from the Authentication field and Custom from the Policy field. This will activate the Edit Policy button.

Click Edit Policy File, this button allows you to define WS-Security policy file for the Connection object. When the button is clicked the Edit WS Security File dialog pops up.

In the Edit WS Security File dialog you can edit or paste content for the policy file. It is important you know the policy requirements for the web service you wish to connect to. Most of the time, a sample policy file will be supplied by the owner of the web service.

The contents of the policy file will be saved on the Agent's file system. The name of the file will be <webservice_adapter_file_name>.policy, if the web service adapter file named was WS_1375884056297.jar then the policy file will be named WS_1375884056297.policy. Below is a sample WS-Security policy file:

<wsp:Policy wsu:Id="SigOnly"

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility- 1.0.xsd"

xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" >

<wsp:ExactlyOne>

<wsp:All>

<sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">

<wsp:Policy>

<sp:InitiatorToken>

<wsp:Policy>

<sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Once">

<wsp:Policy>

<sp:WssX509V3Token10/>

</wsp:Policy>

</sp:X509Token>

</wsp:Policy>

</sp:InitiatorToken>

<sp:RecipientToken>

<wsp:Policy>

<sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">

<wsp:Policy>

<sp:WssX509V3Token10/>

</wsp:Policy>

</sp:X509Token>

</wsp:Policy>

</sp:RecipientToken>

<sp:IncludeTimestamp />

<sp:AlgorithmSuite>

<wsp:Policy>

<sp:TripleDesRsa15/>

</wsp:Policy>

</sp:AlgorithmSuite>

<sp:Layout>

<sp:Lax/>

</sp:Layout>

</wsp:Policy>

</sp:AsymmetricBinding>

<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy" >

<sp:Body />

<sp:Header Name="wsu:Timestamp" Namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" />

</sp:SignedParts>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">

<ramp:user> client </ramp:user>

<ramp:passwordCallbackClass>PWCallBack</ramp:passwordCallbackClass>

<ramp:signatureCrypto>

<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.file">client.jks</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">client</ramp:property>

</ramp:crypto>

</ramp:signatureCrypto>

</ramp:RampartConfig>

</wsp:All>

</wsp:ExactlyOne>

</wsp:Policy>

You may specify special variables in the policy file. These variables represent values specified in the chosen Web Service Connection object. They are:

keystoreAlias
keystorePassword
keystoreFile
userid
password
keystorePropertiesFile

These variables can be used in case you do not want to save userid and password in clear text format. You use the notation ${variable_name} in order for the values to be resolved.

There is also a password callback class called com.uc4.security.PWCBHandler, the user should use this class when specifying a class name for the ramp:passwordCallbackClass tag name in their WS-Security policy file. The password is obtained from the Web Service Connection object selected for the Job definition.

The KeystorePropertiesFile is automatically created if the variable is used in the xml WS-policy or Axis2 client file.

Any Password callback classes required for either WS-Security Policy files or Axis2 client configuration files should specify com.uc4.security.PWCBHandler.