Web service providers and policy configuration sharing
A WebSphere Application Server service provider can share its current policy configuration through its Web Service Description Language (WSDL). The policy configuration is in standard WSDL WS-PolicyAttachment format so that it can be shared with other clients, service registries, or services that support the Web Services Policy (WS-Policy) specification.
We can make the policy configuration of a JAX-WS service endpoint available to share in the following ways:
- Include the policy configuration of the service provider in the WSDL. The WSDL is then available to publish, or to obtain using an HTTP GET request.
- Enable the Web Services Metadata Exchange (WS-MetadataExchange) protocol so that the policy configuration of the service provider is included in the WSDL and is available to a WS-MetadataExchange GetMetadata request. An advantage of using the WS-MetadataExchange protocol is that we can apply message-level security to WS-MetadataExchange GetMetadata requests using a suitable system policy set.
System administrators can also access a WSDL document through a published compressed file with a .zip file extension, using the administrative console or administrative commands. However, a WSDL document acquired in this way might differ from a WSDL document acquired using an HTTP GET request or through the WS-MetadataExchange protocol, because the static WSDL document published in the compressed file will not have been able to take into account any web service features, annotations or deployment descriptor elements which may exist in the application code, such as WS-Addressing annotations.
By default, policy sharing is off. To include the policy configuration of the service provider in the WSDL, and specify how it is shared, we can use the administrative console or wsadmin commands.
When policy sharing is on, any WS-Policy attachments that were in the WSDL previously are removed. Note that policy configuration information becomes available in the WSDL to publish, but it is not available if you view the WSDL document directly from the administrative console or if you publish the WSDL remotely using an administrative agent.
If the service provider application uses multipart WSDL, all the WSDL must be local to the web service application. For more information about multipart WSDL, see the topic about WSDL.
A service provider configured to use Security Assertion Markup Language (SAML) can share policy for use by a WAS client or a service registry. Note that the SAML tokens are published in a proprietary format.
Application developers can specify that a service provider shares its policy configuration, and how it is shared, using Rational Application Developer tools when a web service is generated. See Rational Application Developer documentation.
Transport policy information is not included in the policy configuration because transport policies such as HTTP, SSL, and JMS cannot be expressed in WS-PolicyAttachment format.
Bootstrap policy information, for example, the policy to access a WS-Trust service, can be included in the policy configuration if the bootstrap policy is expressed in standard, publishable WS-PolicyAttachment format.
We can configure a service provider to share its policy configuration at application or service level. The policy configuration represented by the policy sets attached to any earlier levels will also be shared. Policy sets that are attached at earlier levels override the policy set configuration attached at a later level.
Policy information can be defined in several ways. The following list is in descending order of precedence. For example, the deployment descriptor method overrides the use of annotations or features in the application code, but is itself overridden by the use of policy sets.
- Policy is defined by attaching a policy set to the application.
- Policy is defined by the use of deployment descriptor elements within a port-component-ref element.
- Policy is defined using annotations or features in the application code.
- Policy is defined using WS-Policy attachments in the WSDL document packaged with the application.
When an application is deployed in a cell and you publish WSDL using the administrative console, the WSDL contains the policy set configuration of the deployment manager of the cell. If we change any policy sets, the changes do not affect the configuration of the deployment manager until that configuration is refreshed, for example when the deployment manager restarts, or when a scripting command refreshes the policy set configuration of the deployment manager.
The following information lays out the rules governing how policy configuration is published:
- When policy sharing is enabled, the WS-Policy attachments in the WSDL describe the policy configuration of the service.
- When policy sharing is not enabled:
- The WSDL that is returned by an HTTP GET request is the WSDL packaged with the application.
Such WSDL is returned unaltered and so may contain pre-existing WS-Policy attachments that do not match the configuration of the service.
- If there is no specific WSDL document associated with the service, then the server runtime generates a WSDL document automatically and associates it with the service. In this case the WSDL will contain no WS-Policy attachments unless an @Addressing annotation is present on the service implementation, in which case the @Addressing annotation configuration is expressed in WS-Policy attachments in the generated WSDL.
Troubleshoot policy configuration sharing
A service provider might not be able to share its policy configuration because the configuration cannot be expressed in the standard WS-PolicyAttachments format. One reason might be because multiple incompatible policies are defined for a particular attach point. Another reason might be because there is not enough binding information to generate the standard policy. Policy configuration might include bootstrap policy, for example, the policy to access a WS-Trust service, so the bootstrap policy must also be expressed in WS-PolicyAttachments format.
If the policy configuration cannot be shared, an error that describes the problem is written to the service provider error log, and the following policy is attached to the WSDL of the service provider:
<wsp:Policy> <wsp:ExactlyOne> </wsp:ExactlyOne> </wsp:Policy>This policy notifies the client that there is no acceptable policy configuration for the service. Other aspects of the WSDL are unaffected.
Related:
WSDL SAML concepts Configure a service provider to share its policy configuration Publishing WSDL files View WSDL documents for service providers Configure security for a WS-MetadataExchange request Refreshing policy set configurations Enable Web Services Addressing support for JAX-WS applications Policy sharing settings