Securing Web Services with SOAP
InterSystems IRIS supports parts of the WS-Security, WS-Policy, WS-SecureConversation, and WS-ReliableMessaging specifications, which describe how to add security to web services and web clients. This topic summarizes the tools and lists the supported standards.
If your InterSystems IRIS web client uses a web service that requires authentication, and if you have a special reason to do so, you can use the older WS-Security login feature. See Using the WS-Security Login Feature.
Tools in InterSystems IRIS Relevant to SOAP Security
InterSystems IRIS provides the following tools that are relevant to security for web services and web clients:
-
Ability to provide trusted certificates for InterSystems IRIS to use to validate certificates and signatures received in inbound messages.
-
Ability to represent X.509 certificates. You can store, in the IRISSYS database, certificates that you own and certificates of entities you will communicate with. For certificates that you own, you can also store the corresponding private keys, if you need to sign outbound messages.
In the IRISSYS database, an X.509 certificate is contained within an InterSystems IRIS credential set, specifically within an instance of %SYS.X509CredentialsOpens in a new tab. You use the methods of this class to load a certificate (and optionally, the associated private key file, if applicable) into the database. You can execute the methods directly or you can use the Management Portal.
You can specify who owns the credential set and who can use it.
The %SYS.X509CredentialsOpens in a new tab class also provides methods to access certificates by alias, by thumbprint, by subject key identifier, and so on. For reasons of security, the %SYS.X509CredentialsOpens in a new tab class cannot be accessed using the normal object and SQL techniques.
-
Support for SSL (Secure Sockets Layer) and TLS (Transport Layer Security). You use the Management Portal to define InterSystems IRIS SSL/TLS configurations, which you can then use to secure the communications to and from an InterSystems IRIS web service or client, by means of X.509 certificates.
SSL/TLS configurations are discussed in the InterSystems TLS Guide.
-
WS-Policy support. InterSystems IRIS provides the ability to attach WS-Policy information to an InterSystems IRIS web service or web client. A policy can specify the items like the following:
-
Use of WS-SecureConversation.
-
Use of SSL/TLS.
-
WS-Security features to use or to expect.
-
WS-Addressing headers to use or expect. WS-Addressing headers are described in Creating Web Services and Web Clients, which also describes how to add these headers manually.
-
Use of MTOM (Message Transmission Optimization Mechanism) packaging. MTOM is described in Creating Web Services and Web Clients, which also describes how to manually use MTOM packaging.
The policy is created in a separate configuration class. In the class, you use an XData block to contain the policy (which is an XML document) and to specify the parts of the service or client to which it is attached. You can attach the policy to the entire service or client or to specific methods (or even to specific request or response messages).
You can make direct edits to the policy later if wanted. The policy is in effect when you compile the configuration class.
-
-
Support for creating and working with WS-Security elements directly. InterSystems IRIS provides a set of XML-enabled classes to represent WS-Security header elements such as <UsernameToken> and <Signature>. These specialized classes provide methods that you use to create and modify these elements, as well as references between them.
If you use WS-Policy support, InterSystems IRIS uses these classes automatically. If you use WS-Security support directly, you write code to create instances of these classes and insert them into the security header.
In all cases, when an InterSystems IRIS web service or client receives a SOAP message with WS-Security elements, the system creates instances of these classes to represent these elements. It also creates instances of %SYS.X509CredentialsOpens in a new tab to contain any certificates received in the inbound messages.
-
Support for creating and working with WS-SecureConversation elements directly. InterSystems IRIS provides a set of XML-enabled classes to represent these elements. You define a callback method in the web service to control how the web service responds to a request for a secure conversation.
You can either use WS-Policy or you can use WS-Security and WS-SecureConversation directly. If you use WS-Policy, the system automatically uses the WS-Security tools as needed. If you use WS-Security or WS-SecureConversation directly, more coding is necessary.
A Brief Look at the WS-Security Header
A SOAP message carries security elements within the WS-Security header element — the <Security> subelement of the SOAP <Header> element. The following example shows some of the possible components:
![A sample SOAP message header with digital signature and encrypted key elements.](images/gsoapsec_secheader.png)
These elements are as follows:
-
The timestamp token (<Timestamp>) includes the <Created> and <Expires> elements, which specify the range of time during which this message is valid. A timestamp is not, strictly speaking, a security element. If the timestamp is signed, however, you can use it to avoid replay attacks.
-
The binary security tokens (<BinarySecurityToken>) are binary-encoded tokens that include information that enable the recipient to verify a signature or decrypt an encrypted element. You can use these with the signature element, encryption element, and assertion element.
-
The username token (<UsernameToken>) enables a web client to log in to the web service. It contains the username and password required by the web service; these are included in clear text by default. There are several options for securing the password.
-
The assertion element (<Assertion>) includes the SAML assertion that you create. The assertion can be signed or unsigned.
The assertion element can include a subject confirmation element (<SubjectConfirmation>). This element can use the Holder-of-key method or the Sender-vouches method. In the former case, the assertion carries key material that can be used for other purposes.
-
The encrypted key element (<EncryptedKey>) includes the key, specifies the encryption method, and includes other such information. This element describes how the message has been encrypted. See Overview of Encryption.
-
The signature element (<Signature>) signs parts of the message. The informal phrase signs parts of the message means that the signature element applies to those parts of the message, as described in Overview of Digital Signatures.
The figure does not show this, but the signature element contains <Reference> elements that point to the signed parts of the message.
As shown here, an encrypted key element commonly includes a reference to a binary security token included earlier in the same message, and that token contains information that the recipient can use to decrypt the encrypted key. However, it is possible for <EncryptedKey> to contain the information needed for decryption, rather than having a reference to a token elsewhere in the message. InterSystems IRIS supports multiple options for this.
Similarly, a digital signature commonly consists of two parts: a binary security token that uses an X.509 certificate and a signature element that has a direct reference to that binary security token. (Rather than a binary security token, an alternative is to use a signed SAML assertion with the Holder-of-key method.) It is also possible for the signature to consist solely of the <Signature> element; in this case, the element contains information that enables the recipient to validate the signature. InterSystems IRIS supports multiple options for this as well.
SOAP Security Standards
This section lists the support details for WS-Security, WS-Policy, WS-SecureConversation, and WS-ReliableMessaging for InterSystems IRIS web services and web clients.
Also see XML Standards and SOAP Standards.
WS-Security Support in InterSystems IRIS
InterSystems IRIS supports the following parts of WS-Security 1.1 created by OASIS (http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-pr-SOAPMessageSecurity-01.pdfOpens in a new tab):
-
WS-Security headers (http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdfOpens in a new tab)
-
X.509 Token Profile 1.1 (http://www.oasis-open.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdfOpens in a new tab)
-
XML Encryption (https://www.w3.org/TR/xmlenc-core/Opens in a new tab) with the following choice of algorithms:
-
Block encryption (data encryption): AES-128 (default), AES-192, or AES-256
-
Key transport (key encryption): RSA-OAEP (default) or RSA-v1.5
-
-
XML Signature with Exclusive XML Canonicalization (https://www.w3.org/TR/xmldsig-core/Opens in a new tab) with the following choice of algorithms:
-
Digest method: SHA1 (default), SHA256, SHA384, or SHA512
-
Signature algorithm: RSA-SHA1, RSA-SHA256 (default), RSA-SHA384, RSA-SHA512, HMACSHA256, HMACSHA384, or HMACSHA512
Note that you can modify the default signature algorithm. To do so, access the Management Portal, click System Administration, then Security, then System Security, and then System-wide Security Parameters. The option to specify the default signature algorithm is labeled Default signature hash.
For encryption or signing, if the binary security token contains an X.509 certificate, InterSystems IRIS follows the X.509 Certificate Token Profile with X509v3 Token Type. If the key material uses a SAML assertion, InterSystems IRIS follows the WS-Security SAML Token Profile specification.
You can specify the message parts to which the digital signature applies.
-
-
UsernameToken Profile 1.1 (http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-pr-UsernameTokenProfile-01.pdfOpens in a new tab)
-
Most of WS-Security SAML Token Profile 1.1 (http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SAMLTokenProfile.pdfOpens in a new tab) based on SAML version 2.0. The exception is that InterSystems IRIS SOAP support does not include features that refer to SAML 1.0 or 1.1.
For outbound SOAP messages, InterSystems IRIS web services and web clients can sign the SAML assertion token. However, it is the responsibility of your application to define the actual SAML assertion.
For inbound SOAP messages, InterSystems IRIS web services and web clients can process the SAML assertion token and validate its signature. Your application must validate the details of the SAML assertion.
Full SAML support is not implemented. SAML support in InterSystems IRIS refers only to the details listed here.
WS-Policy Support in InterSystems IRIS
Both the WS-Policy 1.2 (https://www.w3.org/Submission/WS-Policy/Opens in a new tab) and the WS-Policy 1.5 (https://www.w3.org/TR/ws-policyOpens in a new tab) frameworks are supported along with the associated specific policy types:
-
WS-SecurityPolicy 1.1 (http://www.oasis-open.org/committees/download.php/16569/Opens in a new tab)
-
WS-SecurityPolicy 1.2 (http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.2/ws-securitypolicy.htmlOpens in a new tab)
-
Web Services Addressing 1.0 - Metadata (https://www.w3.org/TR/ws-addr-metadataOpens in a new tab)
-
Web Services Addressing 1.0 - WSDL Binding (https://www.w3.org/TR/ws-addr-wsdlOpens in a new tab)
-
WS-MTOMPolicy (https://www.w3.org/Submission/WS-MTOMPolicy/Opens in a new tab)
Note that <PolicyReference> is supported only in two locations: in place of a <Policy> element within a configuration element or as the only child of a <Policy> element.
WS-SecurityPolicy 1.2 is supported as follows. Equivalent parts of WS-SecurityPolicy 1.1 are also supported.
-
4.1.1 SignedParts supported with exceptions:
-
Body supported
-
Header supported
-
Attachments not supported
-
-
4.1.2 SignedElements not supported
-
4.2.1 EncryptedParts supported with exceptions:
-
Body supported
-
Header not supported
-
Attachments not supported
-
-
4.2.2 EncryptedElements not supported
-
4.3.1 RequiredElements not supported
-
4.2.1 RequiredParts supported:
-
Header supported
-
-
5.1 sp:IncludeToken supported
-
5.2 Token Issuer and Required Claims not supported
-
5.3 Derived Key properties supported only for X509Token and SamlToken
-
5.4.1 UsernameToken supported
-
5.4.2 IssuedToken not supported
-
5.4.3 X509Token supported
-
5.4.4 KerberosToken not supported
-
5.4.5 SpnegoContextToken not supported
-
5.4.6 SecurityContextToken not supported
-
5.4.7 SecureConversationToken supported
-
5.4.8 SamlToken supported
-
5.4.9 RelToken not supported
-
5.4.10 HttpsToken supported only for TransportBinding Assertion
-
5.4.11 KeyValueToken supported
-
6.1 [Algorithm Suite] partially supported:
-
Basic256, Basic192, Basic128 supported
-
Basic256Rsa15, Basic192Rsa15, Basic128Rsa15 supported
-
Basic256Sha256, Basic192Sha256, Basic128Sha256 supported
-
Basic256Sha256Rsa15, Basic192Sha256Rsa15, Basic128Sha256Rsa15 supported
-
TripleDes, TripleDesRsa15, TripleDesSha256, TripleDesSha256Rsa15 not supported
-
InclusiveC14N, SOAPNormalization10, STRTransform10 not supported
-
XPath10, XPathFilter20, AbsXPath not supported
-
-
6.2 [Timestamp] supported
-
6.3 [Protection Order] supported
-
6.4 [Signature Protection] supported
-
6.5 [Token Protection] supported
-
6.6 [Entire Header and Body Signatures] supported
-
6.7 [Security Header Layout] supported
-
7.1 AlgorithmSuite Assertion per 6.1
-
7.2 Layout Assertion per 6.7
-
7.3 TransportBinding supported only with HttpsToken
-
7.4 SymmetricBinding supported
-
7.5 AsymmetricBinding supported:
-
Only for tokens supported in section 5.4
-
Only for properties in section 6
-
-
8.1 SupportingTokens Assertion supported
-
8.2 SignedSupportingTokens Assertion supported
-
8.3 EndorsingSupportingTokens Assertion supported
-
8.4 SignedEndorsingSupportingTokens Assertion supported
-
8.5 Encrypted SupportingTokens Assertion supported
-
8.6 SignedEncrypted SupportingTokens Assertion supported
-
8.7 EndorsingEncrypted SupportingTokens Assertion supported
-
8.8 SignedEndorsingEncrypted SupportingTokens Assertion supported
-
9.1 Wss10 Assertion supported with exceptions:
-
sp:MustSupportRefKeyIdentifier supported
-
sp:MustSupportRefIssuerSerial supported
-
sp:MustSupportRefExternalURI not supported
-
sp:MustSupportRefEmbeddedToken not supported
-
-
9.2 Wss11 Assertion supported with exceptions:
-
sp:MustSupportRefKeyIdentifier supported
-
sp:MustSupportRefIssuerSerial supported
-
sp:MustSupportRefExternalURI not supported
-
sp:MustSupportRefEmbeddedToken not supported
-
sp:MustSupportRefKeyThumbprint supported
-
sp:MustSupportRefKeyEncryptedKey supported
-
sp:RequireSignatureConfirmation supported
-
-
10.1 Trust13 Assertion supported with exceptions:
-
sp:MustSupportClientChallenge not supported
-
sp:MustSupportServerChallenge not supported
-
sp:RequireClientEntropy supported
-
sp:RequireServerEntropy supported
-
sp:MustSupportIssuedTokens not supported -- ignored for now
-
sp:RequireRequestSecurityTokenCollection not supported
-
sp:RequireAppliesTo not supported
-
-
Trust10 Assertion (see http://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdfOpens in a new tab)
Note:The Trust10 Assertion is supported only in a trivial way; InterSystems IRIS converts it to a Trust13 Assertion to avoid throwing an error.
WS-SecureConversation Support in InterSystems IRIS
InterSystems IRIS supports parts of WS-SecureConversation 1.3 (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.3/ws-secureconversation.pdfOpens in a new tab), as follows:
-
It supports the SCT Binding (for issuing SecureConversationTokens based on the Issuance Binding of WS-Trust) and the WS-Trust Cancel binding (see Canceling Contexts in http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.htmlOpens in a new tab).
-
It supports the case when the service being used acts as its own Security Token Service.
-
It supports only the simple request for a token and simple response.
InterSystems IRIS also supports the necessary supporting parts of WS-Trust 1.3 (http://docs.oasis-open.org/ws-sx/ws-trust/v1.3/ws-trust.pdfOpens in a new tab). Support for WS-Trust is limited to the bindings required by WS-SecureConversation and is not a general implementation.
WS-ReliableMessaging Support in InterSystems IRIS
InterSystems IRIS supports WS-ReliableMessaging 1.1 and 1.2 for synchronous messages over HTTP. Only anonymous acknowledgments in the response message are supported. Because only synchronous messages are supported, no queueing is performed.
See http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.htmlOpens in a new tab and http://docs.oasis-open.org/ws-rx/wsrm/200702Opens in a new tab.