Web service clients and policy configuration to use the service provider policy

Web service clients and policy configuration to use the service provider policy

If a service provider publishes its policy in its WSDL, the policy configuration of a WAS service client can be configured dynamically, based on the policies supported by its service provider.
The service provider must publish its policy in WS-PolicyAttachment format in its WSDL and the client must be able to support those provider policies. The client can base its policy configuration entirely on the policy of the provider, or partly on the policy of the provider with restrictions defined by the policy set configuration of the client.
A client acquires the provider policy by using either an HTTP GET request or the Web Services Metadata Exchange (WS-MetadataExchange) protocol to obtain the WSDL of the provider. We can configure how the client obtains the provider policy, and the endpoint at which the policy is acquired, using the console or wsadmin commands. If we use the WS-MetadataExchange protocol to obtain the policy of the provider, this has the advantage that we can secure WS-MetadataExchange GetMetadata requests by using a suitable system policy set.
If the provider policy uses multipart WSDL, we can use an HTTP GET request to obtain the policy of the provider, but we cannot use the WS-MetadataExchange protocol. For more information about multipart WSDL, see the topic about WSDL.
The web application client-side policy is calculated and cached as a runtime configuration. This calculated policy is known as the effective policy and is used for subsequent outbound web service requests to the endpoint or operation for which the calculation was performed. The original policy set configuration of the client does not change.
For a specific service, dynamic policy configuration occurs once by default, and it is assumed that this configuration is the same for all endpoints that implement a service, because they have the same WSDL. The policy calculations based on this WSDL are cached in the client runtime (they are not persisted) and shared with each target service.
In a cluster environment, this means that the client does not obtain the provider policy again for each endpoint instance of a web service.
In WebSphere Application Server Version 8.0 and later, a service reference can be configured to use a different WSDL document to the WSDL configured for the client service. By default, service references inherit their policy set and WS-Policy configuration from their parent service, however, if desired, the policy set and WS-Policy configuration can be overwritten. See Use WS-Policy to exchange policies in a standard format for further details.
If we require a different policy configuration for each endpoint implementation, create a new port for each endpoint. Then we can specify a different policy configuration for each endpoint.
Transport policies such as HTTP, SSL, and JMS, cannot be expressed in WS-PolicyAttachment format, so the client cannot acquire the transport policies of the service provider. If the client requires transport policies, configure these policies as part of the policy set configuration of the client.
For an HTTP GET request, when the request is targeted at the same location as the endpoint, the request uses the same HTTP and SSL transport policies as the application. When the HTTP GET request is targeted at a different endpoint, we can also attach a system policy set to specify different HTTP and SSL transport policies.
For a WS-MetadataExchange GetMetadata request, the WS-Security configuration in the specified system policy set is used. The HTTP transport properties are inherited from the application.
A client configured to use Security Assertion Markup Language (SAML) can use dynamic policy configuration. However, the client must be configured to use general bindings.

Policy in a registry

A client can obtain the policy configuration of a web service provider from a registry, such as WebSphere Service Registry and Repository (WSRR), by using an HTTP GET request.
The WSDL for the policy of the service provider, and its corresponding policies and policy attachments, are stored in a registry such as WSRR. That policy must contain its policy configuration in WS-PolicyAttachments format. The client must be able to support those provider policies.
The registry must support the use of HTTP GET requests to publish WSDL containing WS-Policy attachments, for example WSRR Version 6.2 or later.
We can apply the provider policy that the client obtains from a registry at the service or service reference level, but not at the application level.
If there is a secure connection between the client and the registry, you must ensure that trust is established between the application server and the registry server.
If the registry requires authentication, we also have to configure a policy to authenticate outbound service requests to the registry. By default, the HTTP and HTTPS credentials are used for both the web service endpoint and the registry. Therefore, it is advisable to secure any authorization credentials and ensure that these credentials are not sent to an unauthorized endpoint. We can also attach a system policy set to specify different HTTP and SSL transport policies.

Policy inheritance

The provider policy can be attached at the application or service level. Endpoints and operations inherit their policy configuration from the relevant service.

Calculating policy

Policy intersection is the comparison of a client policy and a provider policy to determine whether they are compatible, and the calculation of a new policy that complies with both their requirements and capabilities. When you obtain the policy of a service provider, we can choose to use the provider policy only, or to use the client and the provider policy. The outcome of policy intersection is as follows:

When specified provider policy only, the calculated policy is based on all the policies that the WAS client supports intersected by the provider policy. Effectively, the provider determines the policy, as long as the client can support that policy. This policy configuration is available if the scope point (endpoint operation) where the provider policy is attached is not attached to a client policy set and does not inherit a policy set attachment from parent scope points.

When specified client and provider policy, the calculated policy is based on the policy that is acceptable to the client intersected by the provider policy. Effectively, the policy conforms to the client policy set, but might be restricted further by the policies dictated by the provider. The policy that is acceptable to the client is defined by the policy set that is either attached to the client scope point, or that the client scope point inherits from a parent scope point. This policy configuration is available if the scope point (endpoint operation) where the provider policy is attached is attached to a client policy set or inherits a policy set attachment from parent scope points.

The WS-Policy language provides a way to express multiple policy choices, so the policy calculation might produce more than one result. For example, the service provider might support both WS-ReliableMessaging 1.0 and WS-ReliableMessaging 1.1. If the client also supports both versions, the client can use either version in its web service requests to the provider. In this situation, where more than one specification version is acceptable to both the client and the provider, the effective policy is calculated using the most recent version.

Policy intersection in the JAX-WS dispatch client

Invocations that use the JAX-WS dispatch client (javax.xml.ws.Dispatch) use provider policy in their configuration if this is the administered behavior for the service. If the operation for the invocation is unknown, the client behaves as follows:

The client complies with the provider policy scoped to the operation only if the provider policy is identical for all the operations provided by the service (both semantically and syntactically).

If the provider policy is not identical for all the operations provided by the service, the client returns a JAX-WS WebserviceException with the cause WSPolicyException (CWPOL0106E), and an appropriate error message.

If there is no policy on any of the operations, the client uses the effective provider policy for the service endpoint.

For JAX-WS dispatch client using dynamic port (created by javax.xml.ws.Service.addPort instead of ports that are pre-defined in WSDL or by annotation), the operation of invocation is always unknown.
Setting an "operation-level" policy for each such dynamic port in the JAX-WS dispatch client is not supported.

Refreshing the provider policy held by the client

The provider policy that the client holds for a service is refreshed the first time that the web service is invoked after the application is started. After that, the provider policy is refreshed when the application restarts, or when you explicitly invoke an update of the provider policy. When the provider policy is refreshed, the effective policy is recalculated.
We can invoke an update of the provider policy in the application code. This might be useful if a JAX-WS invocation fails; in the exception handling, we can force a retry with refreshed policy. We can set the following property (available in the WSPConstants class of the API) on the JAX-WS client proxy, then reissue the JAX-WS request: com.ibm.websphere.wspolicy.refreshProviderPolicy.
When the com.ibm.websphere.wspolicy.refreshProviderPolicy property is set, the provider policy that the client holds for a service is refreshed, and the effective policy is recalculated at the next request. After the refresh and recalculation have occurred, the com.ibm.websphere.wspolicy.refreshProviderPolicy property is unset.
The following example of code for a dispatch client shows the identification of an exception that might be resolved by refreshing the provider policy, followed by the invocation of the refresh.
try 
{ 
dispatch.invoke(params); 
} 
catch (javax.xml.ws.WebServiceException e) 
{ 
Throwable cause = e.getCause(); 
if ((cause instanceof NullPolicyException) || (cause instanceof PolicyException) ) 
{
// The exception might be because the policy of the provider is not up to date.
//
// There is also a message on the console that starts with the characters CWPOL, // which helps to decipher and debug the cause of the error.
// This message is also available by using // String nlsedMessage = cause.getMessage(); 
Map<String, Object> requestContext = dispatch.getRequestContext(); 
requestContext.put(WSPConstants.REFRESH_PROVIDER_POLICY, Boolean.TRUE);
// The following method might cause another jax-ws invocation exception.
// The cause might still be policy, in which case, a message is written to the // console. 
dispatch.invoke(params); 
}
// For all other exceptions, use the normal exception handling for the // application. In this case, assume there are no other exceptions and rethrow the // initial exception. Remember that the WebServiceException might be caused by a // WSPolicyAdministrationException. In this situation, a message is written to the // console, but forcing a refresh in the application cannot resolve the problem.
throw e; 
} 
Related concepts

WSDL
SAML concepts

Related tasks

Configure the client policy to use a service provider policy
Configure the client policy to use a service provider policy from a registry
Configure security for a WS-MetadataExchange request
Configure the client policy to use a service provider policy by

Additional APIs
Policies applied settings
Policy set bindings settings