SOAP Web services

 

 

 

Session monitoring

Session monitoring can - subject to specific implementation - be initiated between a client (clients) and a Web service. This session monitoring is directly connected to the notion of scope, which is one of the characteristics of Web service deployment.

Generally, a Web service has a 'request' type scope, where a new instance of the service is created for each client request. By definition, the Request scope does not allow session monitoring.

Other scopes, such as the 'transportsession' scope, or the 'application' scope give the instance of an existing service a lifetime allowing the initiation of dialog between the service consumer and the service itself.

The lifetime of an instance of a service with a 'transportsession' scope is identical to that of the transport layer session (HTTP session for a SOAP implementation via HTTP). Throughout the HTTP session, the service context is maintained and the connection between the client and the service is, by default, established via the conventional session cookie "JSESSIONID". The service instance is destroyed on HTTP session timeout.

To activate client-side session monitoring, you must declare the following item in the configuration file:

<Session><Management>true</Management></Session>

 

Note: Axis2 offers an additional 'transport' level session monitoring implementation (scope named 'soapsession') that is not based directly on the HTTP session (and its session cookie), but on WS-ADDRESSING via the serviceGroupId element in a SOAP message header. In this case, 'addressing' module commitment must be forced by adding the following item to the configuration file:

<module><name>addressing</name></module>

 

Warning: with Adelia Studio, the consumption of a Web service having the 'transportsession' scope is not supported in an automated way for the C/Windows generation platform. To ensure an automated management of session monitoring you must declare a service with 'soapsession" scope.

 

The lifetime of a service instance with an 'application' scope is that of the host Web application. There is only one instance of a given Web service in this application. All clients communicate with the same service instance and share the same context. The service instance is destroyed when the host Web application is unloaded. Session monitoring is not necessary as, by definition, only one session exists. Insofar as the service needs to precisely know the client with which it is communicating, rules may be defined between the client and the server concerning data exchange in the header of SOAP messages. The use of WS_ADDRESSING or WS-SECURITY may provide solutions to this problem.

 

Note: The initiation of session monitoring is not the consumer's responsibility, it is governed by Web service design/implementation. Providing a service to consumers must always be accompanied by an information specifying whether or not session monitoring should be managed.

↑ Top of page

 

 

 

Asynchronous calls

Conventionally an IN-OUT MEP [Message Exchange Pattern] Web service (also called 'request-response') is called in a synchronous manner. The client invokes Web service operation and locks while awaiting a response. As service processing can be a relatively long operation, it may be advantageous to be able to call this service asynchronously - on condition that the service engine hosting the Web service is capable of this -.

The Adelia instruction WS_CALL, with its *ASYN directive, generates an asynchronous call. The status of the request sent to the service should be regularly queried to determine whether the service has responded and whether the result can be processed: the WS_GET_STATE instruction fulfills this task. If the value returned by the instruction is not 0, then a response is available. More specifically, a negative value indicates a communication error between the client and the server, whereas a positive value indicates normal completion.

An asynchronous call can function with a single or dual communication channel. A single channel indicates that the same HTTP connection is used for both the request and the response. This mode can be used if the transport layer timeout is sufficiently long, or if request processing is relatively rapid: if necessary, the transport layer timeout can be adjusted in the configuration file by adding the following item:

<Transport><Timeout>value in ms</Timeout></Transport>

The default timeout value is of 60000 ms, i.e. 60 seconds.

 

To avoid the transport layer timeout constraint, a dual communication channel is necessary: one for the request and one for the response.

For this, the following items should be added to the configuration file:

 

a. Dual communication channel declaration:
<Transport><UseAsyncDualChannel>true</UseAsyncDualChannel></Transport>

 

b. force addressing module commitment (WS-Addressing):
<Module><Name>addressing</Name></Module>

 

↑ Top of page

 

 

 

Optimized binary element management (MTOM: Message Transmission Optimization Mechanism)

Binary elements (image files, audio files, etc.) can transit in a SOAP message, in the form of a base64-encoded string. This practice is acceptable for small items, but should be avoided for larger items as, on the one hand, base64 encoding increases by approximately 1/3 the amount of data transiting over the line and, on the other hand, decoding this same base64 is CPU-intensive.

Optimization based on the MTOM protocol is possible. The transport layer then generates a MIME/multipart message. The body of the SOAP message, contained in the 1st part, references the binary that is offset/attached, in raw format, in a second part.

To enable MTOM optimization, the following item should be added to the configuration file:

<ForceMtom>true</ForceMtom>

 

Note: MTOM is compatible with SwA (SOAP with Attachments).

 

Declaration of binaries to optimize: attributes aws_mtom_src_mem and aws_mtom_src_file

In the context of a service call in "message" mode, an XML file must first be created. The binary items in the document to undergo MTOM optimization must be declared using the aws_mtom_src_mem and aws_mtom_src_file attributes.

 

- The aws_mtom_src_mem references a binary stored in memory in the base64-encoded string format.

 

The Adelia instruction XML_SET_VAL serves to automatically serialize an IMAGE variable in the required format.

 

Example of creation - using Adelia XML instructions - of a <pmPICT> item with an aws_mtom_src_mem attribute referencing a binary stored in memory:

 

XML_CREATE_NODE idx *SIBLING 'ns0:pmPICT'

XML_SET_VAL idx aws_mtom_src_mem varImage

 

- The aws_mtom_src_file attribute references a binary stored in a file.

 

Example of creation - using Adelia XML instructions - of a <pmPICT> item with an aws_mtom_src_file attribute referencing a binary file to attach:

 

XML_CREATE_NODE idx *FRERE 'ns0:pmPICT'

XML_SET_VAL idx aws_mtom_src_file 'c:\pics\MyImage.jpg'

 

Using a proxy

Connection via a proxy is configured - in the configuration file - using the following items:

 

Additional information must be added for a proxy requiring authentication:

↑ Top of page

 

 

Secure connection: HTTPS /SSL

• Encryption of exchanged data

• Server authentication

• Server and client authentication

 

C/Windows client platform

1. Server authentication (SSL 1-way): the client ensures that the server is what it claims to be.

 

By default, the client refers to the %adeliws%/certifs/cacert.pem file containing all the CA certificates to ensure server authentication and establish the SSL connection automatically.

In case if this connection fails, you can specify the <Transport><SSLCertificate><ServerCertAuto>true</ServerCertAuto></SSLCertificate></Transport> element to force the retrieval from the target server of a certificate which allows to establish the desired SSL connection (to be used in particular in case of a self-signed certificate).

Finally, if necessary, it is also possible to set up a specific PEM file for server authentication. This file must be filled in using the <Transport><SSLCertificate><ServerCertFile> element.

 

Examples :

- Automatic retrieval of a certificate from the target server in case of the SSL automatic connection failure:

 

- Use of a specific certificate:

 

2. Server authentication and client authentication (SSL 2-way): the client ensures that the server is what it claims to be and the server ensures that the client is what it claims to be.

 

To ensure client authentication, the client must possess a certificate and private key, both within a single .PEM file.

Creation of a (self-signed) certificate and private key with openssl:

openssl req -x509 -days 365 -newkey rsa:1024 -keyout hostkey.pem -nodes -out hostcert.pem

 

The above command creates a self-signed certificate in the hostcert.pem file, along with a private key in the hostkey.pem file. Both files must be concatenated into a single file (clientauth.pem for example), that must be referenced in the Web services configuration file:

 

Note: If a Passphrase is required to access the private key, the following items should be added:

As for all passwords in the configuration file, the Passphrase can be passed unencrypted (Encrypted=false), or encrypted (Encrypted=true). To encrypt the Passphrase, use the VaToolBxEncryptAdeliaPassword function from the VaToolBox, using the value of the <KeyFile> item as an encryption key.

 

3. Server side (e.g.: tomcat):

The server must be configured:

- to enable client authentication (server.xml; HTTPS connector):

<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="20" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" />

 

- designating the Java truststore containing the certificate used to authenticate the client:

<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="20" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" truststoreFile="c:\keystore\.keystore" truststorePass="changeit"/>

 

Note: The certificate can be added to the Java truststore using the keytool command:

keytool -import -v -trustcacerts -alias <your alias> -file <your file>.pem -keystore <your key store>.jks -storepass <your storepass>

↑ Top of page

 

 

Java client platform

1. Server authentication (SSL 1-way): the client ensures that the server is what it claims to be.

 

By default, the client refers to the %java_home%/lib/jre/security/cacerts file containing all the CA certificates to ensure server authentication and establish the SSL connection automatically.

In case if this connection fails, you can specify the <Transport><SSLCertificate><ServerCertAuto>true</ServerCertAuto></SSLCertificate></Transport> element to force the retrieval from the target server of a certificate which allows to establish the desired SSL connection (to be used in particular in case of a self-signed certificate).

Finally, if necessary, it is also possible to set up a specific PEM file or refer to a specific JKS truststore for server authentication. This file or truststore name must be filled in using the <Transport><SSLCertificate><TruststoreName> element.

 

Examples :

- Automatic retrieval of a certificate from the target server in case of the SSL automatic connection failure:

 

- Use of a specific .PEM certificate:

 

- Use of a JKS truststore:

 

Note: To encrypt the password such that the does not appear unencrypted in the configuration file, use the VaToolBxEncryptAdeliaPassword function from the VaToolBox, with the <TruststoreName> item value as the encryption key.

 

2. Server authentication and client authentication (SSL 2-way): the client ensures that the server is what it claims to be and the server ensures that the client is what it claims to be.

 

To ensure client authentication, the client must possess a certificate and private key, both within a keystore. The keystore and corresponding password must be entered into the Web services configuration file:

 

Note: As standard, a truststore and Java keystore use the same format (JKS). Consequently, a single store can be used both as a truststore and as a keystore.

 

Example creation of a keystore containing a private key and certificate using the keytool command:

keytool -genkey -alias key1 -keyalg RSA -keystore keystore.jks

 

The certificate can be exported to a .cer file to be imported into the server's truststore:

keytool -export -alias key1 -keystore keystore.jks -file clicert.cer

 

Notes:

- In the context of client authentication, the use of self-signed certificates requires the addition of a certificate to the server's truststore for each client. The solution consists in having the client certificates signed by a single certification authority [CA] and adding the root certificate to the authority in question. A number of free certification authorities are available, such as http://cert.startcom.org/.

- For certificate, private key and certification authority management, see the Java JDK keytool utility, or the openssl.exe tool.

↑ Top of page

 

 

WS-Addressing, WS-Security, WS-Policy, WS-SecurityPolicy

These denominations define specifications exclusive to Web services.

 

WS-Addressing is a specification used to address/route messages independently of the transport layer.

 

WS-Security is a specification used to secure SOAP message exchanges. These mechanisms are time-stamping, authentication, encryption and digital signature. All of these mechanisms serve, on the one hand, to ensure that a message cannot be read or altered during transit and, on the other hand, to precisely identify a message's sender.

 

WS-Policy and WS-SecurityPolicy define flexible grammars used to express entity possibilities, requirements and general characteristics within a Web service-based system.

 

Adelia Studio is based on the Axis2 layer and consequently offers de facto support for these specifications.

 

WS-Addressing is enabled by committing the "addressing" module from the configuration file. The configuration elements specific to WS-Addressing (To, Action, From, ReplyTo, FaultTo, RelatesTo) are defined via module properties.

 

 

WS-Security is enabled by committing the rampart module from the configuration file. The configuration items are passed via a policy file that conforms to the grammars defined by WS-Policy and WS-SecurityPolicy. The policy file is referenced using the rampart module's PolicyFile item. This file should meet service expectations and, most of the time, can be retrieved from this latter's description file (WSDL). Some aspect of policy file configuration are declared either using Rampart-specific tags, or Adelia Web services consumption configuration file elements.

 

 

No further details of the possibilities offered by these specifications are provided in this documentation. Please see the specific documents available on the Internet for more information.

 

↑ Top of page