Creating and Using Policies
This topic describes how to use WS-Policy support in InterSystems IRIS. WS-Policy enables you to specify the WS-Security headers to use or to expect. It also enables you to specify use of WS-Addressing headers and MTOM (which are described in Creating Web Services and Web Clients). You create policies in separate classes rather than editing the web service or web client directly. In most cases, no low-level programming is required.
Overview
In InterSystems IRIS, the policy (or collection of policies) for a web service or client is contained in a separate configuration class, a subclass of %SOAP.ConfigurationOpens in a new tab. The policies are in effect when the class is compiled.
If the WSDL for the web service has already been defined, you can generate the configuration class. If you are creating the web service first, you can use the Web Service/Client Configuration Wizard to choose and configure a predefined policy to apply to the web service. You can also create the class manually.
No coding is generally required. However, in some cases, you can specify a detail programmatically, rather than having that element hardcoded into the policy.
Effect of the Configuration Class
When you compile a configuration class, the future operation of the web service or client is affected as follows:
-
The web service or client includes additional header elements in outbound messages, according to the details of the policy.
-
The web service or client validates inbound SOAP messages based on the policy. This includes decrypting inbound messages if appropriate.
-
The web service or client optionally encrypts outbound messages, if appropriate.
-
For a web service, the WSDL is automatically affected. Specifically, <wsp:Policy> elements are added, and the namespace declarations include the following:
xmlns:wsp="http://www.w3.org/ns/ws-policy"
If the configuration class is mapped to multiple namespaces, you must compile it in each of those namespaces.
Relationship to WS-Security, WS-Addressing, and MTOM Support
InterSystems IRIS support for WS-Policy is built on InterSystems IRIS support for WS-Security, WS-Addressing, and MTOM. Note the following points:
-
If a policy does not include a security policy, InterSystems IRIS uses the SecurityOut property of the web service or web client. (To add security header elements manually to a web service or client, you add them to SecurityOut property, as described elsewhere.)
-
If a policy does include a security policy, InterSystems IRIS ignores the SecurityOut property of the web service or web client except for any elements that relate to that policy.
For example, when you use the Mutual X.509 Certificates Security policy, you can specify an InterSystems IRIS credential set to use directly within the policy, or you can create an instance of %SYS.X509CredentialsOpens in a new tab and add that, contained in a binary security token, to the SecurityOut property. If you do not specify the credential set directly in the policy, InterSystems IRIS retrieves the binary security token from the SecurityOut property and uses it. InterSystems IRIS ignores other elements in SecurityOut property, however, because they do not apply to this scenario.
-
If a policy requires WS-Addressing, InterSystems IRIS ignores the WSADDRESSING class parameter.
If the AddressingOut property is set, however, InterSystems IRIS uses the WS-Addressing headers that it specifies. Otherwise, it uses the default set of WS-Addressing headers.
-
If a policy requires MTOM, InterSystems IRIS ignores the MTOMREQUIRED class parameter and the MTOMRequired property.
Relationship of Web Service and Web Client
When you attach a policy to a web service, all clients must be able to obey that policy. If the web service policy does not include any policy alternatives, then the clients must have the same policy as the web service, substituting a client-side certificate for the server-side certificate, if needed.
Similarly, if you attach a policy to a web client, the service must be able to obey that policy.
In practice, if both the service and the client are created in InterSystems IRIS, the following procedure is the simplest:
-
Create the web service class.
-
Create the web service configuration class, with the service policy.
-
Use the SOAP Wizard to generate the client classes, including the client configuration class.
After you do so, examine the generated client classes and make changes if needed.
You usually also create a wrapper class for it.
For information on these tasks, see Creating Web Services and Web Clients.
-
Examine the generated configuration classes and make changes if needed. See Editing the Generated Policy.
For details on the configuration class, see WS-Policy Configuration Class Details.
Creating and Attaching Policies
To create a policy and attach it to a web service or client, you create and compile a configuration class. There are several ways to create this class:
-
Use the Web Service/Client Configuration Wizard. This option applies if the web service or client class already exists.
-
Use the SOAP Wizard. This option applies if you are starting with the WSDL.
The wizard generates the configuration class only if the WSDL includes WS-Policy elements.
For information, see Creating Web Services and Web Clients.
-
Use the GeneratePolicyFromWSDL() method to generate just the configuration class from the WSDL. This option applies if the web service or client class already exists, and you do not want to regenerate that.
-
Create a configuration class manually for an existing web service or client. For information, see the next topic.
If you generate the policy class from a WSDL, you may need to edit it as described in the next section.
Using the Web Service/Client Configuration Wizard
You can create and attach policies by using the Web Service/Client Configuration Wizard in Studio. To use this wizard:
-
Click File > New....
-
On the General tab, click Web Service/Client Configuration.
-
Click OK.
Studio then displays a dialog box.
-
Select the web service or a web client to which the policies will apply. The wizard lists only the services and clients that are compiled.
To do so, click either the Service or the Client drop-down menu as appropriate and then click the web service class or web client class.
-
Click Next.
Studio then displays another dialog box.
-
Optionally edit the configuration class name, which is shown in the second field on this dialog box.
Note:If this class already exists, this wizard ignores its existing contents and overwrites it. The new class is not created until you reach the end of the wizard.
The default configuration class name is the web service or client class name, with Config appended to it.
-
For details on the rest of this page, see Security Policy Descriptions and Policy Option Reference.
-
Click Finish.
The wizard creates and saves the class.
-
Review the generated configuration class, which also includes a policy expression that adds timestamps to outbound messages:
<sp:IncludeTimestamp/>
-
Optionally edit the configuration class and re-save it.
You would do this, for example, to add policy alternatives or to fine-tune the policy created by the wizard.
The class is not automatically compiled and the policy is not in effect until the class is compiled.
If you compile the configuration class and then want to disable it, comment out the XData block and recompile it.
Generating the Policy from the WSDL
In some cases, you might already have client classes, but not the corresponding configuration classes. This could occur, for example, if you generate the client classes from the WSDL and later the WSDL is modified to include WS-Policy information. In such cases, you can generate the configuration class alone by using a utility method in %SOAP.WSDL.ReaderOpens in a new tab, as follows:
-
Create an instance of %SOAP.WSDL.ReaderOpens in a new tab.
-
Set properties of that instance as applicable. See the class documentation for %SOAP.WSDL.ReaderOpens in a new tab.
Do not use the Process() method.
-
Invoke the GeneratePolicyFromWSDL() method of your instance.
This method has the following signature:
method GeneratePolicyFromWSDL(wsdlURL As %String, clientWebServiceClass As %String, policyConfigClass As %String) as %Status
Where:
-
wsdlURL is URL of the WSDL which contains the policy. It is assumed that the WSDL specifies only one port.
-
clientWebServiceClass is the name of the web client class. It is your responsibility to ensure that this web client matches the given WSDL.
-
policyConfigClass is the name of the configuration class to be created.
-
This creates (or overwrites) a configuration class for a web service client which contains the policy specified by the WSDL of the web service. If there is no policy in the WSDL, an empty configuration class is created. The configuration class will be compiled if the CompileClasses property of the instance equals 1.
Editing the Generated Policy
If you generate a configuration class from a WSDL and if the WSDL is external to this instance of InterSystems IRIS, you must edit the configuration class to include information about the certificates and SSL/TLS configurations to use. Or you could specify this information at runtime.
Also, if you select Establish Secure Session (Secure Conversation), you can edit the policy to specify an optional lifetime for the secure conversation.
The following table gives the details:
If the Generated Policy Includes ... | Do the following ... |
---|---|
<sp:HttpsToken> | For a policy attached to client, do one of the following:
|
<sp:InitiatorToken> | For a policy attached to client, do one of the following:
For a policy attached to a service, no change is needed. |
<sp:RecipientToken> | Do one of the following:
|
<sp:SecureConversationToken> | Optionally add the cfg:Lifetime attribute as described in Adding InterSystems Extension Attributes. The default lifetime is 5 minutes. |
Security Policy Descriptions
The primary purpose of the wizard is to provide configurable security policies. The choices for Security Policy are as follows:
-
No Security Policy
The following section lists all the policy options.
SSL/TLS Connection Security
This policy requires use of HTTP over SSL/TLS (HTTPS) between the web client and the web service. It provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Username Authentication over SSL/TLS
This policy requires the client to send a <UsernameToken> (with username and password). This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
At runtime, the web client must create and add the username token with the default password type. See Adding a Username Token.
X.509 Certificate Authentication over SSL/TLS
This policy requires the client to send messages with signed body and timestamp and the X.509 certificate that can verify the signature. WS-Addressing headers, if included, are also signed. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Authentication with Symmetric Keys
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
Symmetric Keys with Endorsing Certificate
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
This mechanism uses an endorsing client certificate to augment the token associated with the message signature.
Mutual X.509 Certificates Security
This policy requires all peers to sign the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
SAML Authorization over SSL/TLS
This policy requires the client to send a SAML token that contains an X.509 certificate or a public key. The corresponding private key signs the message body and timestamp, as well as WS-Addressing headers, if included. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
SAML with X.509 Certificates
This policy requires the client to send a SAML token. This policy also signs the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
Policy Option Reference
The predefined policies have many of the same options. The following list provides details on all the options, following the order they are shown in the wizard.
Where applicable: All security policies.
If you select this option, the web service and web client establish and use a shared, secret security context. Then both parties can generate the same symmetric key and use it for signing, encryption, signature validation, and decryption.
Where applicable: All security policies.
This option is applicable only if the previous option is also selected. If you select Require Derived Keys, then a derived key is used in the messages, rather than the original session key.
Where applicable: All security policies.
This option specifies that the WS-ReliableMessaging protocol must be used when sending messages. This protocol allows SOAP messages to be reliably delivered even in the presence of software component, system, or network failures.
You can specify parameters in an InterSystems IRIS web service to fine-tune its behavior with WS-ReliableMessaging. See Controlling How the Web Service Handles Reliable Messaging.
Where applicable: All policies that use SSL/TLS. Applies only to the client.
SSL/TLS configuration for the client to use.
In all applicable policies, you can either choose an SSL/TLS configuration within the wizard (hardcoding that selection), or you can programmatically select and add one in the web service or client; see Specifying the SSL/TLS Configuration to Use.
Where applicable: All policies that use SSL/TLS.
Optionally select this option if the SSL/TLS connection requires the client to authenticate itself. See the comments for SSL Configuration.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to encrypt the SOAP body with the public key of the peer’s certificate.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the messages are encrypted before being signed. If this option is not selected, the messages are signed and then encrypted.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the message signature is applied to the binary security token that carries the certificate whose associated private key signs the message.
Where applicable: X.509 Certificate Authentication over SSL/TLS. Applies only to the client.
InterSystems IRIS credential set for the client to use when signing messages. The signature uses the private key in the associated certificate. See the subsection Credential Sets.
Where applicable: Several policies.
Optionally select this to require the client to send an encrypted element that contains a <UsernameToken>.
If you choose this option, you must add the <UsernameToken> at runtime as described in Adding a Username Token. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
Where applicable: Policies that use symmetric keys. Applies only to the client.
InterSystems IRIS credential set for the client to use to generate the symmetric key; this should be the certificate of the service. The symmetric key is generated with the public key of the certificate. See Credential Sets.
Where applicable: Symmetric Keys with Endorsing Certificate. Applies only to the client.
InterSystems IRIS credential set for the client to use to endorse the protection token. This should be the certificate of the client. See the subsection Credential Sets.
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates. Applies only to the client.
InterSystems IRIS credential set for the web client to use. The client uses the associated private key for message signing and sends the initiator token to the service to enable the service to verify signatures and encrypt the response. See the subsection Credential Sets.
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates.
InterSystems IRIS credential set for the web service to use. The client uses the public key in the certificate in the recipient token to encrypt the outbound message body. The service uses the associated private key for message signing. See the subsection Credential Sets.
Where applicable: All security policies.
Algorithm suite for the web server and client to use. For details, see section 6.1 in the WS-SecurityPolicy specificationOpens in a new tab.
Where applicable: All security policies.
Optionally select this option to enforce a strict layout of security header elements.
Where applicable: All policies.
If you select this option, the web service or web client includes WS-Addressing header elements in outbound messages and expects them in inbound messages.
If you use Enable WS-Addressing, InterSystems IRIS uses a default set of WS-Addressing header elements; for details on the included elements, see Adding WS-Addressing Header Elements.
Even when you select Enable WS-Addressing, you can manually create WS-Addressing header elements and attach them as described in Adding WS-Addressing Header Elements; if you do so, the web service or client uses those header elements instead of the default ones.
Where applicable: All policies.
If you select this option, the web service or web client uses MTOM packaging in outbound messages and expects MTOM packaging in inbound messages.
Credential Sets
In many of the policies, you can select an InterSystems IRIS credential set as follows:
-
Select a credential set from the X.509 Credentials drop-down list.
-
Select a credential set by specifying the value of a field in the certificate. To do so, select a field from the Field drop-down list and then enter a value in the type-in box.
The available fields are as follows:
-
Alias
-
SubjectKeyIdentifier
-
Thumbprint
-
SerialNumber
-
IssuerDN
-
IssuerName — Acts as search string for the IssuerDN field. The system selects the first credential set whose IssuerDN field contains the given string. (In contrast, if you use IssuerDN, the match must be exact.)
-
SubjectDN
-
SubjectName — Acts as search string for the SubjectDN field. The system selects the first credential set whose SubjectDN field contains the given string. (In contrast, if you use SubjectDN, the match must be exact.)
-
Or you can programmatically select a credential set; see Retrieving Credential Sets Programmatically. In this case, you also need to package the certificate in a binary security token and add it to the outbound messages, as described in Adding a Certificate at Runtime.
Adding a Certificate at Runtime
If your web service or client must select and include a certificate programmatically, use the following procedure:
-
Retrieve an instance of %SYS.X509CredentialsOpens in a new tab, as described in Retrieving Credential Sets Programmatically.
For example:
set credset=##class(%SYS.X509Credentials).GetByAlias(alias,password)
Or:
set credset=..SecurityIn.Signature.X509Credentials
-
Create an instance of %SOAP.Security.BinarySecurityTokenOpens in a new tab that contains the certificate from that credential set. For example:
set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
Where credentials is the credential set you retrieved in the previous step.
This returns an object that represents the <BinarySecurityToken> element, which carries the certificate in serialized, base-64–encoded form.
-
Call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the binary security token you created previously. For example:
do ..SecurityOut.AddSecurityElement(bst)
In some cases, two binary security tokens are needed: one for encryption and one for signing. Be sure to add these in the appropriate order, depending on whether you selected the Encrypt Before Signing option. If the policy encrypts the message and then signs it, be sure to add the binary security token used for encryption before you add the one used for signing. Conversely, if the policy signs and then encrypts, the first binary security token must be the one used for signing.
The following shows an example within a web method in a web service:
//get credentials
set x509alias = "something"
set pwd = "password"
set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
//get certificate and add it as binary security token
set cert = ##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
do ..SecurityOut.AddSecurityElement(cert)
The code would be slightly different for a web client, because you do not typically edit the proxy client:
set client=##class(proxyclient.classname).%New()
//get credentials
set x509alias = "something"
set pwd = "password"
set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
//get certificate and add it as binary security token
set cert = ##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
do client.SecurityOut.AddSecurityElement(cert)
//invoke web method of client
Specifying a Policy at Runtime
For an InterSystems IRIS web client, you can specify the policy to use at runtime; this overrides any policy configuration class. To specify the policy at runtime, set the PolicyConfiguration property of the web client instance. The value must have the following form:
Configuration class name:Configuration name
Where Configuration class name is the full package and class name of a policy configuration class, as described earlier in this topic, and Configuration name is the value of the name attribute of the <configuration> element for the policy in that class
Suppressing Compilation Errors for Unsupported Policies
By default, when you compile a configuration class, InterSystems IRIS issues an error if the configuration includes any policy expressions that are not supported in InterSystems IRIS. To suppress such errors, include the following in the configuration class:
Parameter REPORTANYERROR=0;
When you use the SOAP Wizard to generate a web client or web service from a WSDL, if InterSystems IRIS also generates a configuration class, it includes this parameter setting in that class.
Unsupported alternatives can be ignored as long as there is one supported policy alternative.