HTTP Transport Policy

Overview

Policy is not specifically required to enable HTTP transport module instances. They are enabled by default when an endpoint employs the HTTP transport (assuming the feature has been enabled). Policy is, however, required to constrain HTTP transport module instances, i.e. to perform transport level authentication. For more information regarding how policy is used, e.g. how and where it may be attached and the difference between public and private policy, please see the user guide.

Vocabulary 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0" xmlns:tns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0" elementFormDefault="qualified">
  <xs:element name="authInfo">
    <xs:annotation>
      <xs:documentation>Assertion with policy subject ENDPOINT, i.e. PRIVATE policy attached to an EndpointReference component. TODO: describe how whttp attribs on referenced endpoint are converted to/from an instance of this policy assertion and how assertion MAY be optionally attached to endpoint in lieu of whttp attribs to configure scheme/realm.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:choice>
        <xs:sequence>
          <xs:element name="scheme" type="tns:tScheme" minOccurs="0">
            <xs:annotation>
              <xs:documentation>Authentication scheme for indicated host[:port]</xs:documentation>
            </xs:annotation>
          </xs:element>
          <xs:element name="realm" type="xs:NCName" minOccurs="0">
            <xs:annotation>
              <xs:documentation>Authentication realm for indicated host[:port]</xs:documentation>
            </xs:annotation>
          </xs:element>
          <xs:element name="user" type="xs:NCName" minOccurs="0">
            <xs:annotation>
              <xs:documentation>User name for indicated host[:port]</xs:documentation>
            </xs:annotation>
          </xs:element>
        </xs:sequence>
        <xs:sequence>
          <xs:element name="none" minOccurs="0">
            <xs:annotation>
              <xs:documentation>Enables a non-authenticating transport.</xs:documentation>
            </xs:annotation>
          </xs:element>
        </xs:sequence>
      </xs:choice>
      <xs:attribute name="host" type="xs:NCName" use="required">
        <xs:annotation>
          <xs:documentation>Name of host. To configure servlet for inbound transport(s) use the placeholder 'myhost'. To configure client for async responses use actual host name. To configure client for outbound requests use the placeholder 'partnerhost' or actual host name.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="port" type="tns:tPort" use="optional" default="-1">
        <xs:annotation>
          <xs:documentation>Defines port on indicated host. The value '-1' implies all ports.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:anyAttribute namespace="http://www.w3.org/ns/ws-policy" />
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="tScheme">
    <xs:restriction base="xs:token">
      <xs:enumeration value="basic" />
      <xs:enumeration value="digest" />
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="tPort">
    <xs:restriction base="xs:int">
    <xs:minExclusive value="-2"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Examples

Note that the type of policy used to constrain this feature module is an extension to the core EOA specification. The examples below use policy which complies with version 1.5 of the ws-policy specification.

Public Policy

While public policy is not explicitly defined for the http transport, it may, however, be implied, i.e. via the use of the whttp extension attributes 'authenticationScheme' and 'authenticationRealm' which are defined on 'myEndpoint2' and 'partnerEndpoint2' below (you may have to scroll over to see it).

WSDL Descriptions 
<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://com.mycompany/eoa/1.0" xmlns:tns="http://com.mycompany/eoa/1.0">
      <wsdl:binding name="SOAP11Binding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.1" wsoap:protocol="http://www.w3.org/2006/01/soap11/bindings/HTTP" />
      <wsdl:binding name="SOAP12Binding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.2" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/" />
      <wsdl:service name="myService" interface="tns:myInterface">
        <wsdl:endpoint name="myEndpoint1" binding="tns:SOAP11Binding" address="http://myserver:8080/eoa/ws/myEngine/myService/myEndpoint1/">
          <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
              <wsp:Policy>
                <wsam:NonAnonymousResponses />
              </wsp:Policy>
            </wsam:Addressing>
          </wsp:Policy>
        </wsdl:endpoint>
        <wsdl:endpoint name="myEndpoint2" binding="tns:SOAP12Binding" address="http://myserver:8080/eoa/ws/myEngine/myService/myEndpoint2/" xmlns:whttp="http://www.w3.org/ns/wsdl/http" whttp:authenticationScheme="digest" whttp:authenticationRealm="foo">
          <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
              <wsp:Policy>
                <wsam:NonAnonymousResponses />
              </wsp:Policy>
            </wsam:Addressing>
          </wsp:Policy>
        </wsdl:endpoint>
      </wsdl:service>
      <!-- note that for this example, this engine is assumed to execute on local server -->
      <ext:engine xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="myEngine" application="tns:myApplication">
        <ext:actor role="http://some/role" service="tns:myService" />
      </ext:engine>
    </wsdl:description>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://com.partnercompany/eoa/1.0" xmlns:tns="http://com.partnercompany/eoa/1.0">
      <wsdl:binding name="SOAP11Binding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.1" wsoap:protocol="http://www.w3.org/2006/01/soap11/bindings/HTTP" />
      <wsdl:binding name="SOAP12Binding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.2" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/" />
      <wsdl:service name="partnerService" interface="tns:partnerInterface">
        <wsdl:endpoint name="partnerEndpoint1" binding="tns:SOAP11Binding" address="http://partnerserver:8080/eoa/ws/partnerEngine/partnerService/partnerEndpoint1/">
          <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
              <wsp:Policy>
                <wsam:NonAnonymousResponses />
              </wsp:Policy>
            </wsam:Addressing>
          </wsp:Policy>
        </wsdl:endpoint>
        <wsdl:endpoint name="partnerEndpoint2" binding="tns:SOAP12Binding" address="http://partnerserver:8080/eoa/ws/partnerEngine/partnerService/partnerEndpoint2/" xmlns:whttp="http://www.w3.org/ns/wsdl/http" whttp:authenticationScheme="basic" whttp:authenticationRealm="bar">
          <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
            <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
              <wsp:Policy>
                <wsam:NonAnonymousResponses />
              </wsp:Policy>
            </wsam:Addressing>
          </wsp:Policy>
        </wsdl:endpoint>
      </wsdl:service>
      <!-- note that for this example, this engine is assumed to execute on a remote server -->
      <ext:engine xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="partnerEngine" application="tns:partnerApplication">
        <ext:actor role="http://some/role" service="tns:partnerService" />
      </ext:engine>
    </wsdl:description>
  </components>
</deployment>
Implied Public Policy

The WSDL description above implies the following public policy with policy subject ENDPOINT attached to endpoint 'myEndpoint2'. Note the value 'myhost' is a constant which is a proxy for the local host's name, ip address and the values 127.0.0.1 and 'localhost'. The implied policy enables/configures an http transport module which handles requests addressed to http://myserver:8080/eoa/ws/myEngine/myService/myEndpoint2/ and which requires digest authentication and credentials defined within the authentication realm "foo".

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <dns:authInfo host="myhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
    <dns:scheme>digest</dns:scheme>
    <dns:realm>foo</dns:realm>
  </dns:authInfo>
</wsp:Policy>

The WSDL description above also implies the following public policy with policy subject ENDPOINT attached to endpoint 'partnerEndpoint2'. The implied policy configures an http transport module which uses basic authentication and the realm "bar" to send messages to the partner endpoint http://partnerserver:8080/eoa/ws/partnerEngine/partnerService/partnerEndpoint2/ . Note that valid users of this endpoint must be defined via private policy (see example below).

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <dns:authInfo host="partnerserver" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
    <dns:scheme>basic</dns:scheme>
    <dns:realm>bar</dns:realm>
  </dns:authInfo>
</wsp:Policy>

Private Policy

Note that the following examples use the "default engine" provider to demonstrate private policy attachements. The structure employed by other providers should be similar.

Authenticating 'myhost' Requests

If no whttp attributes are defined on a local endpoint's WSDL description and no private policy is attached to the referenced endpoint, a non-authenticating http transport module is enabled by default, i.e. the following private policy with policy subject ENDPOINT is implied. Note that the constant "myhost" serves as a proxy for local host name, ip address and the values 127.0.0.1 and 'localhost'.

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <dns:authInfo host="myhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
    <dns:none />
  </dns:authInfo>
</wsp:Policy>

If no whttp attributes are defined on a local endpoint's WSDL description and you want the requests to be authenticated, you must explicitly define and attach private policy with policy subject ENDPOINT to the referenced endpoint. Using the example WSDL description listed above, to enable basic authentication on realm "foo" for "myEndpoint1" requires the following attachment. Note that users for myhost and realm "foo" must be defined within the credential store used by this feature (see the credential store feature reference for additional information).

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:myEngine">
      <partners>
        <engineReference engineName="tns:myEngine">
          <serviceReference serviceName="tns:myService">
            <endpointReference endpointName="myEndpoint1">
              <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                <dns:authInfo host="myhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
                  <dns:scheme>basic</dns:scheme>
                  <dns:realm>foo</dns:realm>
                </dns:authInfo>
              </wsp:Policy>
            </endpointReference>
          </serviceReference>
        </engineReference> 
      </partners>
    </engine>         
  </providers>  
</deployment>
Authenticating 'partnerhost' Requests

If no whttp attributes are defined on a partner endpoint's WSDL description and no private policy is attached to the referenced endpoint, a non-authenticating http transport module is enabled by default, i.e. the following private policy with policy subject ENDPOINT is implied. Note that the constant 'partnerhost' may be used as a proxy for the actual host name defined on referenced endpoint.

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <dns:authInfo host="partnerhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
    <dns:none />
  </dns:authInfo>
</wsp:Policy>

If no whttp attributes are defined on a partner endpoint's WSDL description but the partner requires authentication, you must explicitly define and attach private policy with policy subject ENDPOINT to the referenced endpoint. Using the example WSDL description listed above, to constrain the http transport module to use basic authentication and to send credentials for user "me" and realm "bar" when sending requests to "partnerEndpoint1" requires the following attachment. Note that the user "me" for "partnerserver" and realm "bar" must be defined within the credential store used by this feature (see the credential store feature reference for additional information). Note also that the constant 'partnerhost' may be used as a proxy for the actual host name defined on referenced endpoint. 

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:myEngine">
      <partners>
        <engineReference engineName="tns:partnerEngine">
          <serviceReference serviceName="tns:partnerService">
            <endpointReference endpointName="partnerEndpoint1">
              <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                <dns:authInfo host="partnerhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
                  <dns:scheme>basic</dns:scheme>
                  <dns:realm>bar</dns:realm>
                  <dns:user>me</dns:user>
                </dns:authInfo>
              </wsp:Policy>
            </endpointReference>
          </serviceReference>
        </engineReference> 
      </partners>
    </engine>         
  </providers>  
</deployment>

If whttp attributes are defined on a partner endpoint's WSDL description you must supplement the implied policy by declaring the associated user name within private policy with policy subject ENDPOINT attached to the referenced endpoint. Using the example WSDL description listed above, to constrain the http transport module to send credentials for user "me" when sending requests to "partnerEndpoint2" requires the following policy. Note that the user "me" for "partnerserver" and realm "bar" must be defined within the credential store used by this feature (see the credential store feature reference for additional information). Note also that the constant 'partnerhost' may be used as a proxy for the actual host name defined on referenced endpoint.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:myEngine">
      <partners>
        <engineReference engineName="tns:partnerEngine">
          <serviceReference serviceName="tns:partnerService">
            <endpointReference endpointName="partnerEndpoint2">
              <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                <dns:authInfo host="partnerhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
                  <dns:user>me</dns:user>
                </dns:authInfo>
              </wsp:Policy>
            </endpointReference>
          </serviceReference>
        </engineReference> 
      </partners>
    </engine>         
  </providers>  
</deployment>
Authenticating 'myhost' Responses

If an endpoint defined on a locally hosted engine either requires or supports non-anonymous responses, as defined by ws-addressing policy, and no private policy is attached to the referenced endpoint, a non-authenticating client is used by the HTTP transport module to return the asynchronous response from 'my' endpoint.

To override this default behavior, i.e. if a partner to which asynchronous responses are sent requires authentication, private policy with subject ENDPOINT must be defined and attached to the referenced endpoint, i.e. to element which references endpoint from which the responses are returned. An unlimited number of entries can be made, i.e. one for each partner (identified by host name and port combination.)

Using the example WSDL description listed above, to configure the HTTP transport module to send credentials using the basic scheme when returning an asynchronous response in response to a request received by "myEndpoint1" and the response is sent to partner host "somehost" on port "8080", would require the following private policy. Note that the user "me" for "somehost" and realm "bar" and port "8080" must be defined within the credential store used by this feature (see the credential store feature reference for additional information). Note that if the port value were omitted, the indicated credentials would be sent for all ports on "somehost". Alterantively, multiple assertions for the same host name are allowed, as long as the port number is unique. When sending a response, using the wsa replyTo address, the HTTP transport module attempts to locate an entry matching on host and port. If not found, an entry with just the matching host name is retrieved. If that's not found, it uses the default non-authenticating client to send the response.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engineReference engineName="tns:myEngine">
      <serviceReference serviceName="tns:myService">
        <endpointReference endpointName="myEndpoint1">
          <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
            <dns:authInfo host="somehost" port="8080" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
              <dns:scheme>basic</dns:scheme>
              <dns:realm>bar</dns:realm>
              <dns:user>me</dns:user>
            </dns:authInfo>
          </wsp:Policy>
        </endpointReference>
      </serviceReference>
    </engineReference>
  </providers>  
</deployment>
Authenticating 'partnerhost' Responses

If an endpoint defined on a partner service either requires or supports non-anonymous responses, as defined by ws-addressing policy, and no private policy is attached to the referenced endpoint, a non-authenticating servlet is used by the HTTP transport module to receive the asynchronous response returned by 'partner' endpoint.

To override this default behavior and configure the HTTP transport module to require authentication of asnchronous response requires that private policy with subject ENDPOINT be defined and attached to the referenced endpoint, i.e. to element which references partner endpoint from which the responses are being returned.

Using the example WSDL description listed above, to configure the HTTP transport module to challenge responses returned from "partnerEndpoint1" using the digest scheme on realm "default" would require the following private policy. Note that the constant "myhost" serves as a proxy for local host name, ip address and the values 127.0.0.1 and 'localhost' and that the "port" attribute is not allowed in this context. Valid user credentials for "myhost" are defined within the credential store used by this feature (see the credential store feature reference for additional information). 

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:myEngine">
      <partners>
        <engineReference engineName="tns:partnerEngine">
          <serviceReference serviceName="tns:partnerService">
            <endpointReference endpointName="partnerEndpoint1">
              <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                <dns:authInfo host="myhost" xmlns:dns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/transport/http/policy/1.0">
                  <dns:scheme>digest</dns:scheme>
                  <dns:realm>default</dns:realm>
                </dns:authInfo>
              </wsp:Policy>
            </endpointReference>
          </serviceReference>
        </engineReference> 
      </partners>
    </engine>         
  </providers>  
</deployment>