InterSystems IRIS Data Platform 2019.2  /  Securing Web Services

Securing Web Services
Validating and Decrypting Inbound Messages
Previous section           Next section
InterSystems: The power behind what matters   

This chapter describes how to validate security elements in messages received by an InterSystems IRIS web service or web client (and automatically decrypt any encrypted content). It discusses the following topics:
InterSystems IRIS web services and web clients can validate the WS-Security header element for inbound SOAP messages, as well as automatically decrypt the inbound messages.
InterSystems IRIS 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, InterSystems IRIS 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:
    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:
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, an InterSystems IRIS web service or web client automatically validates the signature of that SAML assertion, if it is signed.
Validation requires a trusted certificate. InterSystems IRIS 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 InterSystems IRIS, including intermediate certificates (if any).
InterSystems IRIS does not, however, automatically validate the assertion. Your code should retrieve the assertion and validate it.
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.
Instance Authentication and WS-Security
It is useful to understand that with an InterSystems IRIS web service, two separate mechanisms are in effect: the IRIS server and the web service code.
These mechanisms work together as follows:
  1. Upon receiving a message, the 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:
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.

Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-20 05:45:45