This document covers the following topics:
EntireX, in conjunction with the Software AG Web Services Stack (WSS), provides development and runtime functionality to support EntireX RPC clients consuming (or calling) Web services. The relevant products parts are:
IDL Extractor for WSDL to generate an XML/SOAP mapping from the service's WSDL.
XML Mapping Editor to adapt the mapping file if necessary. See XML Mapping Editor.
EntireX RPC Server for XML/SOAP, acting as the EntireX Web service runtime, to deploy the XML mapping file into and perform the Web service call. See RPC Server for XML/SOAP.
Web Services Stack client runtime, which handles the underlying SOAP, WS-Policy and message transport. See the separate Software AG Web Services Stack documentation.
For each Web service client that is deployed in RPC Server for XML/SOAP, a special configuration is required. The default name of the configuration file is entirex.xmlrpcserver.configuration.xml. Example configuration:
... <TargetServer name="http://localhost:10010/wsstack/services/example"> <xmms> <exx-xmm name="C:\MyWorkspace\Example\example.xmm" wsdl="http://localhost:10010/wsstack/services/example?wsdl" service="example" port="EXAMPLESOAP11Port" soapVersion="1.1" repository="C:\SoftwareAG\WS-Stack\repository" /> </xmms> </TargetServer> ...
where | code |
is the XMM mapping file for the service |
wsdl |
is the reachable URL for the WSDL file of the service. This WSDL file can contain additional WS-Policy information for the service that is supported by the Web Services Stack | |
service |
is the service name inside the WSDL file of the service | |
port |
is the port inside the WSDL file. This information is needed when the WSDL file can contain more than one port. The value in this example is the default number; this number can be changed during installation | |
soapVersion |
can be "1.1" or "1.2" | |
repository |
is the client "repository" of the Web Services Stack (containing the conf and modules subfolders) |
A Web Services Stack client using advanced Web services functionality (WS-Security, WS-ReliableMessaging, etc.) requires the following configuration data:
A "repository" containing configuration files and extension modules (.mar files). The "repository" is a folder containing subfolders conf and modules.
The conf folder contains the client's global configuration file axis2.xml for the Web Services Stack engine.
The modules folder contains modules for WS-* extensions, for example
addressing-1.4.mar if WS-Addressing is used
rampart-1.4.mar if WS-Security is used
rahas-1.4.mar if WS-Trust is used
If WS-Security is used, an additional security configuration file
wsclientsec.properties is required. The name and location of this file can be
configured in the client's global configuration file axis2.xml, using the
securityConfigFile
property.
Here is an example of a client security configuration file wsclientsec.properties:
USERNAME=client ENCRYPTION_USER=service PASSWORD_CALLBACK_HANDLER_CLASS=com.softwareag.wsstack.test.PasswordCallbackHandler KEYSTORE_FILE_ENCRYPT=client.jks KEYSTORE_TYPE_ENCRYPT=jks KEYSTORE_PASSWORD_ENCRYPT=apache KEYSTORE_FILE_SIGN=client.jks KEYSTORE_TYPE_SIGN=jks KEYSTORE_PASSWORD_SIGN=apache KEYSTORE_SSL_LOCATION=clientKS.jks SSL_KEYSTORE_TYPE=jks SSL_KEYSTORE_PASSWORD=apache TRUSTSTORE_SSL_LOCATION=clientKS.jks TRUSTSTORE_SSL_TYPE=jks TRUSTSTORE_SSL_PASSWORD=apache
The USERNAME
specifies the user name that the Web service client uses to authenticate itself with the
Web service. It corresponds to Alias
as described for the service
configuration. ENCRYPTION_USER
and PASSWORD_CALLBACK_HANDLER
correspond accordingly.
The example Java password callback handler from above can also be used for
the client. The Web Services Stack provides some default password callback handlers that can be instantly used without needing
to write a custom one.
For example com.softwareag.wsstack.pwcb.ConfigFilePasswordCallbackHandler
, which uses
a simple user configuration file users.xml
. See the separate WS-stack documentation for more details.
A Web Services Stack client that connects to a Web Service that requires advanced Web Services policies (which are attached to the service's WSDL as policy attachment) automatically sets up and processes the necessary SOAP headers in the SOAP message exchange with the service and fills the required parameters according to the configuration information described above.
This section describes how to set up EntireX RPC clients calling a remote Web service that has a WS-Security UsernameToken
policy in effect. Two scenarios are described: one where the security policy is defined in the WSDL, and one where the policy
is not defined.
Scenario 1: Service requires UsernameToken and has a Security Policy in the WSDL
Scenario 2: Service requires UsernameToken but does not declare this in the WSDL
To set up a dedicated RPC Server for XML/SOAP instance to connect EntireX RPC clients to a secured Web service, the following prerequisites apply, for example in a folder of their own in the file system:
A startup script, jxmlserver.bat
. You can copy this from <Install-Dir>\EntireX\bin and adapt it.
Property file and config file, entirex.xmlrpcserver.properties
and entirex.xmlrpcserver.configuration.xml
. You can copy these from <Install-Dir>\EntireX\conf and adapt them.
A WSS client repository containing the subfolders conf
, modules
and services
. You can copy this from <Install-Dir>\WS-Stack\repository and adapt it
Note:
For this example only the addressing
and rampart
modules are required; delete the others.
A WSS client security configuration properties file, wsclientsec.properties
,
containing at least values for USERNAME
and PASSWORD_CALLBACK_HANDLER_CLASS
.
You can copy this from <Install-Dir>\EntireX\bin and adapt it.
In this scenario, the Web Services Stack runtime can use the WS-Security policy from the WSDL to determine which security headers need to be attached to the SOAP message. Follow the steps below:
To set up an RPC Server for XML/SOAP with defined security policy
Store a copy of the service's WSDL (which also includes the policy attachment) in the test folder.
Generate an XML/SOAP mapping file (.xmm) with the IDL Extractor for WSDL. Enter the name of the RPC Server for XML/SOAP ("XMLSERVER" in this example) under Broker Settings on the wizard page.
Start the RPC Server for XML/SOAP in a command window, using the start
script.
Deploy the mapping file to the RPC Server for XML/SOAP. Provide the location of the WSDL and specify the desired service endpoint, name and port.
Configure the Web Services Stack repository for the service, using the following steps:
Stop the RPC Server for XML/SOAP.
Edit the file entirex.xmlrpcserver.configuration.xml
and add the repository definition to the TargetServer
section.
For example:
<TargetServer name="http://localhost:10010/wsstack/services/example.EXAMPLESOAP11Port/"> <xmms> <exx-xmm name="D:\TestWS\example.xmm" port="EXAMPLESOAP11Port" wsdl="D:\TestWS1\example.wsdl" service="example" soapVersion="1.1" repository="repository"/> </xmms> </TargetServer>
Restart the RPC Server for XML/SOAP.
Configure security for the WSS client runtime
by modifying files wsclientsec.properties
and users.xml
:
File wsclientsec.properties
, containing the lines
USERNAME=user PASSWORD_CALLBACK_HANDLER_CLASS= com.softwareag.wsstack.pwcb.ConfigFilePasswordCallbackHandler
Specify the desired username
, which should go into the UsernameToken
.
The password callback handler class is used by the WSS client runtime to inquire a password for this user.
The ConfigFilePasswordCallbackHandler
is a simple default handler delivered with Web Services Stack
that reads the password of a given user from a flat file users.xml
.
You can write a custom password callback handler for other methods to acquire passwords.
File users.xml
. Example:
<?xml version="1.0" encoding="UTF-8"?> <users> <user username="user" password="pass" /> <user username="client" password="apache" /> <user username="service" password="apache" /> <user username="bob" password="bobPW" /> </users>
To test access to the remote Web service, use the EntireX XML Tester on the IDL file.
For this scenario, perform the steps as described above. Because the WSDL does not contain a security policy
stating that UsernameToken
is required, perform this additional step:
Explicitly tell the Web Services Stack client runtime about the
UsernameToken
required by the service. Edit <SuiteInstallDir>/profiles/CTP/workspace/wsstack/repository/conf/axis2.xml,
uncomment the rampart
module and add the OutFlowSecurity
parameters:
<module ref="rampart"/> <parameter name="OutflowSecurity"> <action> <items>UsernameToken</items> <user>user</user> <passwordType>PasswordText</passwordType> <passwordCallbackClass> com.softwareag.wsstack.pwcb.ConfigFilePasswordCallbackHandler </passwordCallbackClass> </action> </parameter>
where | user |
is a valid user name for authentication. |