Securing Caché Web Services
Using WS-ReliableMessaging
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Caché supports parts of the WS-ReliableMessaging specifications, as described in the first chapter. This specification provides a mechanism to reliably deliver a sequence of messages, in order. The easiest way to use this support is to create a security policy and use the Reliable Message Delivery option in the Web Service/Client Configuration Wizard. Another option is to manually use reliable messaging, as described in this chapter, which discusses the following topics:

Sending a Sequence of Messages from the Web Client
To send a sequence of messages reliably from a Caché web client to a web service that supports WS-ReliableMessaging, do the following:
  1. Specify the security header elements of the web client as needed. See previous chapters of this book.
    If you are using WS-SecureConversation, as described in the previous chapter, start the secure conversation.
  2. Call the Create() class method of %SOAP.RM.CreateSequence. This returns an instance of that class.
    This method has the following signature:
    classmethod Create(addressingNamespace As %String, 
                       oneWay As %Boolean = 0, 
                       retryInterval As %Float = 1.0, 
                       maxRetryCount As %Integer = 8, 
                       expires As %xsd.duration, 
                       SSLSecurity As %Boolean = 0) as %SOAP.RM.CreateSequence
    Where:
  3. Call the %StartRMSession() method of the web client and pass the instance of %SOAP.RM.CreateSequence as the argument.
    Note that you can use the instance of %SOAP.RM.CreateSequence only one time. That is, you cannot use it to create another session later.
  4. Invoke web methods as needed.
    Use the same web client instance each time.
  5. Call the %CloseRMSession() method of the web client when you are done sending messages.
Important:
Also make sure to sign the WS-ReliableMessaging headers as described in the next section.
Signing the WS-ReliableMessaging Headers
You can sign the WS-ReliableMessaging headers in either of the following ways.
Signing the Headers with the SecurityContextToken
If you are also using WS-SecureConversation, as described in the previous chapter, the SecurityContextToken property of web client contains a symmetric key that you can use to sign the WS-ReliableMessaging header elements. To do so, call the AddSTR() method of the instance of %SOAP.RM.CreateSequence, passing the SecurityContextToken property as the argument:
 do createsequence.AddSTR(client.SecurityContextToken)
Do this before calling %StartRMSession().
Signing the Headers When Signing the Message
You can also sign the WS-ReliableMessaging headers in the same way that you sign the rest of the message. To do so, add the value $$$SOAPWSIncludeRMHeaders to the signatureOptions argument when you call the Create() or CreateX509() method of %XML.Signature. The $$$SOAPWSIncludeRMHeaders macro is included in the %soap.inc file.
Modifying a Web Service to Support WS-ReliableMessaging
To modify a Caché web service to support WS-ReliableMessaging, modify the web methods so that they do the following:
It is easier, however, to create a security policy and use the Reliable Message Delivery option in the Web Service/Client Configuration Wizard.
Controlling How the Web Service Handles Reliable Messaging
You can specify the following parameters of the web service class to fine-tune the behavior of the web service:
RMINORDER
Corresponds to the InOrder policy assertion of WS-ReliableMessaging. Specify this as either 0 (false) or 1 (true). See the Web Services Reliable Messaging Policy 1.1 specification for details.
By default, when this parameter is not specified, a Caché the web service does not issue SOAP faults about the order of messages.
RMDELIVERYASSURANCE
Corresponds to the DeliveryAssurance policy assertion of WS-ReliableMessaging. Specify this as "ExactlyOnce", "AtLeastOnce", or "AtMostOnce". See the Web Services Reliable Messaging Policy 1.1 specification for details.
By default, when this parameter is not specified, a Caché the web service does not issue SOAP faults about any failures to deliver according to this policy assertion.
RMINACTIVITYTIMEOUT
Specifies the inactivity timeout, in seconds, for the sequence received by the web service. The default is 10 minutes.
You can specify the same parameters in a web service class that uses a security policy that uses the Reliable Message Delivery option.
Also, you can implement the %OnCreateRMSession() callback method of the web service. This method is invoked at the start of WS-ReliableMessaging session before the %SOAP.RM.CreateSequenceResponse is returned. The response argument has been completely created and not yet returned at this point. This callback gives you an opportunity to add any required Security header elements to the SecurityOut property of the web service. If WS-Policy is used, then WS-Policy support does this automatically. For the method signature, see the class reference for %SOAP.WebService.