Skip to main content
Previous section   Next section

WS-Policy Configuration Class Details

For reference, this topic contains details on the configuration class that InterSystems IRIS uses to store WS-Policy information.

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">
...
Copy code to clipboard

The XData block has the following general structure:

XData service
{
<cfg:configuration ...>
   <service ...>
      <method ...>
         <request ...>
         <response ...>
...
Copy code to clipboard

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:

  • <sp:X509Token> (within <sp:InitiatorToken> or <sp:RecipientToken>)

    In this element, specify a value for the cfg:FindField and cfg:FindValue attributes, which specify the InterSystems IRIS credential set to use for this token.

    • The cfg:FindField attribute specifies the name of the field by which to search. Typically this is Alias.

    • the cfg:FindValue attribute specifies the value of that field. If cfg:FindField is Alias, then this is the name of the InterSystems IRIS credential set.

    For example:

    <sp:X509Token IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never" 
                  cfg:FindField="Alias" 
                  cfg:FindValue="servercred">
      <wsp:Policy>
        <sp:WssX509V3Token11/>
      </wsp:Policy>
    </sp:X509Token>
    
    Copy code to clipboard
  • <sp:HttpsToken>

    In this element, specify a value for the cfg:SSLConfiguration attribute. This should equal the name of an InterSystems IRIS SSL/TLS configuration. For example:

    <sp:HttpsToken cfg:SSLConfiguration="mysslconfig">
        <wsp:Policy/>
    </sp:HttpsToken>
    Copy code to clipboard

    Specify this attribute only for the web client.

  • <sp:SecureConversationToken>

    In this element, you can specify the cfg:Lifetime attribute. This should equal the lifetime for the secure conversation, in hours or fractional hours. The default lifetime is 5 minutes. Suppose that we want to specify that the lifetime is 15 minutes. To do so, we edit <sp"SecureConversationToken> as follows.

    <sp:SecureConversationToken cfg:Lifetime=".25"
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
        <wsp:Policy>
          <sp:MustNotSendAmend/>
          <sp:MustNotSendRenew/>
      ...
      </wsp:Policy>
    </sp:SecureConversationToken>
    Copy code to clipboard

    Specify this attribute only for the web client.

For information on the prefix cfg, see the next section.

If you create a policy with the Web Service/Client Configuration Wizard, InterSystems IRIS 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"
Copy code to clipboard

In this topic, the prefix cfg refers to that namespace.

Also see “InterSystems Extension Attributes,” earlier in this topic.

<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 an InterSystems IRIS web service or web client.

<service>

The <service> element associates a policy with an InterSystems IRIS web service or web client. This element includes the following items:

Attribute or Element Purpose
classname (Required) Full package and class name of an InterSystems IRIS 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 topic.
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>
Copy code to clipboard

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:

  • "service" — Attach this policy element to the WSDL <service> element.

  • "port" — Attach this policy element to the WSDL <port> element.

  • "binding" (the default) — Attach this policy element to the WSDL <binding> element.

  • "portType" — Attach this policy element to the WSDL <portType> element.

<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 topic.
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:

  • "binding" (the default) — Attach this policy element to the WSDL <binding> element.

  • "portType" — Attach this policy element to the WSDL <portType> element.

<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 topic.
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:

  • "binding" (the default) — Attach this policy element to the WSDL <binding> element.

  • "portType" — Attach this policy element to the WSDL <portType> element.

  • "message" — Attach this policy element to the WSDL <message> element.

<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 topic.
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:

  • "binding" (the default) — Attach this policy element to the WSDL <binding> element.

  • "portType" — Attach this policy element to the WSDL <portType> element.

  • "message" — Attach this policy element to the WSDL <message> element.

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>
}

}
Copy code to clipboard

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>
}

}
Copy code to clipboard

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.

Previous section   Next section