Securing Caché Web Services
WS-Policy Configuration Class Details
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

For reference, this chapter contains details on the configuration class that Caché uses to store WS-Policy information. It discusses the following topics:

Configuration Class Basics
To create a WS-Policy configuration class manually, create a subclass of %SOAP.Configuration. In this class, add an XData block as follows:
XData service
{
<cfg:configuration xmlns:cfg="http://www.intersystems.com/configuration" name="service">
...
The XData block has the following general structure:
XData service
{
<cfg:configuration ...>
   <service ...>
      <method ...>
         <request ...>
         <response ...>
...
The elements <service>, <method>, <request>, and <response> can each include policy information that applies at that level. The <service> element is required, but the other elements are optional.
The policy information, if included, is either a policy expression (that is, an <wsp:Policy> element) or a policy reference (that is, a <wsp:PolicyReference> element that points to a policy contained in another XData block in the same configuration class). The following sections provide more details.
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.
Adding InterSystems Extension Attributes
In addition to the cfg:wsdlElement attribute (previously discussed), you may need to add InterSystems extension attributes in the following elements within your policy elements:
For information on the prefix cfg, see the next section.
If you create a policy with the Web Service/Client Configuration Wizard, Caché sets values for these attributes automatically. If you generate a configuration class while generating a web client or service, you may need to edit these attributes.
Details for the Configuration XData Block
This section describes the contents of the XData block of a web service or client configuration class.
The <configuration>, <service>, <method>, <request>, and <response> elements must all be in the following namespace:
"http://www.intersystems.com/configuration"
In this chapter, the prefix cfg refers to that namespace.
Also see InterSystems Extension Attributes,” earlier in this chapter.
<configuration>
The <configuration> element is the root element in the XData block. This element includes the following items:
Attribute or Element Purpose
name (Optional) Name of this configuration. If specified, this must match the name of the XData block.
<service> (Optional) Associates a policy with a Caché web service or web client.
<service>
The <service> element associates a policy with a Caché web service or web client. This element includes the following items:
Attribute or Element Purpose
classname (Required) Full package and class name of a Caché web service or client.
<wsp:Policy> (Include 0 or 1) Specifies the policy to apply to this web service or client (at the binding level). Specify a WS-Policy 1.2 or WS-Policy 1.5 policy expression.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<wsp:PolicyReference> (Include 0 or 1) Specifies the policy reference to apply to this web service or client (at the binding level). If you specify this, the policyID attribute must be a reference to a local policy defined in a different XData block in the same configuration class. For an example, see Configuration with PolicyReference,” later in this chapter.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<method> (Include 0 or more) Associates a policy with a specific web method in the given web service or client (to apply at the operation level). The <service> element can include any number of <method> elements.
For example:
<cfg:configuration 
xmlns:cfg="http://www.intersystems.com/configuration" 
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702" 
xmlns:wsap="http://www.w3.org/2006/05/addressing/wsdl" 
xmlns:wsp="http://www.w3.org/ns/ws-policy" 
name="service">
  <cfg:service classname="DemoPolicies.NoSecurity">
    <wsp:Policy>
      <wsap:UsingAddressing/>
    </wsp:Policy>
  </cfg:service>
</cfg:configuration>
Within the <wsp:Policy> or <wsp:PolicyReference> child of <service>, you can specify the cfg:wsdlElement attribute, which specifies the part of the WSDL to which to attach this policy element. In this context, this attribute can have any of the following values:
<method>
The <method> element associates a policy with a specific web method within the web service or client specified by the parent <service> element. The <method> element includes the following items:
Attribute or Element Purpose
name Name of a web method.
<wsp:Policy> (Include 0 or 1) Specifies the policy to apply to this web service or client (at the operation level). Specify a WS-Policy 1.2 or WS-Policy 1.5 policy expression.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<wsp:PolicyReference> (Include 0 or 1) Specifies an optional reference WS-Policy 1.2 or WS-Policy 1.5 policy expression for this web method. The policyID attribute is a reference to a local policy defined in a different XData block in the same configuration class. For an example, see Configuration with PolicyReference,” later in this chapter.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<request> (Include 0 or 1) Associates a policy with the request message for the web method.
<response> (Include 0 or 1) Associates a policy with the response message for the web method.
Within the <wsp:Policy> or <wsp:PolicyReference> child of <method>, you can specify the cfg:wsdlElement attribute, which specifies the part of the WSDL to which to attach this policy element. In this context, this attribute can have any of the following values:
<request>
The <request> element associates a policy with the request message for the web method to which the parent <method> element refers. The <request> element includes the following items:
Attribute or Element Purpose
<wsp:Policy> (Include 0 or 1) Specifies the policy to apply to the request message. Specify a WS-Policy 1.2 or WS-Policy 1.5 policy expression.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<wsp:PolicyReference> (Include 0 or 1) Specifies an optional reference WS-Policy 1.2 or WS-Policy 1.5 policy expression for the request message. The policyID attribute is a reference to a local policy defined in a different XData block in the same configuration class. For an example, see Configuration with PolicyReference,” later in this chapter.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
Within the <wsp:Policy> or <wsp:PolicyReference> child of <request>, you can specify the cfg:wsdlElement attribute, which specifies the part of the WSDL to which to attach this policy element. In this context, this attribute can have any of the following values:
<response>
The <response> element associates a policy with the response message for the web method to which the parent <method> element refers. The <response> element includes the following items:
Attribute or Element Purpose
<wsp:Policy> (Include 0 or 1) Specifies the policy to apply to the response message. Specify a WS-Policy 1.2 or WS-Policy 1.5 policy expression.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
<wsp:PolicyReference> (Include 0 or 1) Specifies an optional reference WS-Policy 1.2 or WS-Policy 1.5 policy expression for the response message. The policyID attribute is a reference to a local policy defined in a different XData block in the same configuration class. For an example, see Configuration with PolicyReference,” later in this chapter.
Specify <wsp:Policy>, <wsp:PolicyReference>, or neither.
Within the <wsp:Policy> or <wsp:PolicyReference> child of <response>, you can specify the cfg:wsdlElement attribute, which specifies the part of the WSDL to which to attach this policy element. In this context, this attribute can have any of the following values:
Example Custom Configurations
This section provides examples of some custom configuration classes.
Configuration with Policy Alternatives
The following configuration class includes two policy alternatives: either use WS-Addressing headers or do not.
/// PolicyAlternatives.DivideWSConfig
Class PolicyAlternatives.DivideWSConfig Extends %SOAP.Configuration
{

XData service
{
<cfg:configuration xmlns:cfg="http://www.intersystems.com/configuration" 
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702" 
xmlns:wsap="http://www.w3.org/2006/05/addressing/wsdl" 
xmlns:wsp="http://www.w3.org/ns/ws-policy" 
name="service">
  <cfg:service classname="PolicyAlternatives.DivideWS">
   <wsp:Policy>
     <wsp:ExactlyOne>
       <wsp:All>
         <wsap:UsingAddressing/>
       </wsp:All>
       <wsp:All>
         <wsp:Policy/>
       </wsp:All>
     </wsp:ExactlyOne>
    </wsp:Policy>
  </cfg:service>
</cfg:configuration>
}

}
When used with a web client whose attached policy requires WS-Addressing, this web service responds with a message that has WS-Addressing headers. When used with a client whose policy does not use WS-Addressing, this web service responds with messages without WS-Addressing headers.
Another scenario would be for one policy to require SSL/TLS and an alternative policy to use message encryption (as in the Mutual X.509 Certificates Security policy).
Configuration with Policy Reference
The following configuration class contains two XData blocks. One contains a policy whose ID attribute is mypolicy. The other contains a configuration for a web service; this configuration refers to the policy contained in the other XData block:
Class DemoPolicies.WithReferenceConfig Extends %SOAP.Configuration
{

XData service
{
<cfg:configuration 
xmlns:cfg="http://www.intersystems.com/configuration"  
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702" 
xmlns:wsp="http://www.w3.org/ns/ws-policy" 
name="service">
  <cfg:service classname="DemoPolicies.WithReference">
    <wsp:PolicyReference URI="#mypolicy">
    </wsp:PolicyReference>
  </cfg:service>
</cfg:configuration>
}

XData Policy1
{
<wsp:Policy 
  xmlns:wsp="http://www.w3.org/ns/ws-policy" 
  xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility"
  xmlns:wsap="http://www.w3.org/2006/05/addressing/wsdl" 
  xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization" 
  wsu:Id="mypolicy">
 <wsap:UsingAddressing/>
 <wsoma:OptimizedMimeSerialization/>
</wsp:Policy>
}

}
In this example, the policy expression is contained in an XData block named Policy1. The name of this block has no effect on the WSDL or on any SOAP operations.