Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Validating and Decrypting Inbound Messages

This chapter describes how to validate security elements in messages received by a Caché web service or web client (and automatically decrypt any encrypted content). It discusses the following topics:


Caché web services and web clients can validate the WS-Security header element for inbound SOAP messages, as well as automatically decrypt the inbound messages.

Caché web services and web clients can also process a signed SAML assertion token and validate its signature. However, it is the responsibility of your application to validate the details of the SAML assertion.

All the preceding activities are automatic if you use a security policy.

In all scenarios, Caché uses its collection of root authority certificates; see the chapter “Setup and Other Common Activities.”

Validating WS-Security Headers

To validate the WS-Security header elements contained in any inbound SOAP messages, do the following:

  1. In the web service or the web client, set the SECURITYIN parameter. Use one of the following values:

    • REQUIRE — The web service or the web client verifies the WS-Security header element and issues an error if there is a mismatch or if this element is missing.

    • ALLOW — The web service or the web client verifies the WS-Security header element.

    In both cases, the web service or the web client validates the <Timestamp>, <UsernameToken>, <BinarySecurityToken>, <Signature>, and <EncryptedKey> header elements. It also validates the WS-Security signature in the SAML assertion in the header, if any. The message is also decrypted, if appropriate.

    If validation fails, an error is returned.

    There are two additional possible values for SECURITYIN parameter, for use in testing and troubleshooting:

    • IGNORE — The web service or client ignores the WS-Security header elements except for <UsernameToken>, as described in “CSP Authentication and WS-Security.”

      For backward compatibility, this value is the default.

    • IGNOREALL — The web service or client ignores all WS-Security header elements.

For an example, see “Message Encryption Example,” earlier in this book.


The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class.

Accessing a SAML Assertion in the WS-Security Header

If the WS-Security header element includes an <Assertion> element, a Caché web service or web client automatically validates the signature of that SAML assertion, if it is signed.

Caché does not, however, automatically validate the assertion. Your code should retrieve the assertion and validate it.


Validation requires a trusted certificate. Caché can validate a signature if it can verify the signer’s certificate chain from the signer’s own certificate to a self-signed certificate from a certificate authority (CA) that is trusted by Caché, including intermediate certificates (if any).

To access the SAML assertion, find the <Assertion> element of the security header element. To do so, use the FindElement() method of the SecurityIn property of the service or client, as follows:

 Set assertion=..SecurityIn.FindElement("Assertion") 

This returns an instance of %SAML.Assertion. Examine properties of this object as needed.

CSP Authentication and WS-Security

It is useful to understand that with a Caché web service, two separate mechanisms are in effect: the CSP engine and the web service.

  • In the Management Portal, you specify allowed authentication modes for a web application. (For details, see “Timestamp and Username Token Example,” earlier in this book.) If you select the Password option, the web application can accept a Caché username/password pair.

  • Independently of this, the web service can require a Caché username/password pair.

These mechanisms work together as follows:

  1. Upon receiving a message, a Caché web service checks for the presence of a header element called <Security>, without examining the contents of that element.

  2. If no <Security> header element is present and if the SECURITYIN parameter equals REQUIRE, the web service issues a fault and quits.

  3. If the <Security> header element contains a <UsernameToken> element:

    • If you selected the Password option for the web application, the web service instructs the CSP engine to log in to Cache. The login is done in the same way as for any CSP page; Caché uses the username and password given by the <UsernameToken> element.

      The web service does this for any value of the SECURITYIN parameter, except for IGNOREALL.

      The username is available in the $USERNAME special variable and in the Username property of the web service. The password is not available.

    • If you did not select the Password option, no login occurs.


The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class.

Retrieving a Security Header Element

In some cases, you might want to add custom processing for WS-Security header elements. To do this, use the SecurityIn property of the web service or client. If a service or client receives WS-Security header elements, this property is an instance of %SOAP.Security.Header that contains the header elements. For example:

 Set secheader=myservice.SecurityIn

Then use one of the following methods of that instance to retrieve a header element:

method FindByEncryptedKeySHA1(encryptedKeySHA1 As %Binary) as %SOAP.Security.Element

Returns the key from an <EncryptedKey> element that corresponds to the given EncryptedKeySHA1 argument. Or returns the empty string if there is no match.

method FindElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element

Returns the first security element of the specified type after position pos. If there is no match, the method returns the empty string (and returns pos as 0).

For type, specify "Timestamp", "BinarySecurityToken", "UsernameToken", "Signature", or "EncryptedKey".

method FindLastElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element

Returns the last security element of the specified type. If there is no match, the method returns the empty string (and returns pos as 0).

For information on type, see the entry for FindElement().

All these methods return either an instance of %SOAP.Security.Element or an instance of one the following subclasses, depending upon the element type:

Element Type Subclass Used
"Timestamp" %SOAP.Security.Timestamp
"BinarySecurityToken" %SOAP.Security.BinarySecurityToken
"UsernameToken" %SOAP.Security.UsernameToken
"Signature" %XML.Security.Signature

For details, see the class reference.

Checking the Signature Confirmation

The WS-Security 1.1 <SignatureConfirmation> feature enables a web client to ensure that a received SOAP message was generated in response to the original request sent by the web client. The client request is typically signed but does not have to be. In this mechanism, the web service adds a <SignatureConfirmation>element to the security header element, and the web client can check that <SignatureConfirmation> element.

For a web client, to validate the <SignatureConfirmation> elements in a response received from a web service, call the WSCheckSignatureConfirmation() method of the web client. This method returns true if the <SignatureConfirmation> elements are valid, or false otherwise.

For information on adding signature confirmation to messages sent by a web service, see “Adding Signature Confirmation,” earlier in this book.