Validating and Decrypting Inbound Messages
This topic describes how to validate security elements in messages received by an InterSystems IRIS web service or web client (and automatically decrypt any encrypted content).
Overview
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 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:
-
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.
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.AssertionOpens in a new tab. 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.
-
In the Management Portal, you specify allowed authentication modes for a web application, thus controlling access to the %Service_WebGateway service. (For details, see Timestamp and Username Token Example. For additional background, see Web Applications.) If you select the Password option, the web application can accept an InterSystems IRIS username/password pair; this is called instance authentication.
-
Independently of this, the web service can require an InterSystems IRIS username/password pair.
These mechanisms work together as follows:
-
Upon receiving a message, the web service checks for the presence of a header element called <Security>, without examining the contents of that element.
-
If no <Security> header element is present and if the SECURITYIN parameter equals REQUIRE, the web service issues a fault and quits.
-
If the <Security> header element contains a <UsernameToken> element:
-
If you selected the Password option for the web application, the web service reads the <UsernameToken> element, obtains the username and password from that, and logs in to the web application.
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.HeaderOpens in a new tab 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.ElementOpens in a new tab or an instance of one the following subclasses, depending upon the element type:
Element Type | Subclass Used |
---|---|
"Timestamp" | %SOAP.Security.TimestampOpens in a new tab |
"BinarySecurityToken" | %SOAP.Security.BinarySecurityTokenOpens in a new tab |
"UsernameToken" | %SOAP.Security.UsernameTokenOpens in a new tab |
"Signature" | %XML.Security.SignatureOpens in a new tab |
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.