Web service clients and policy configuration using 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. Configure how the client obtains the provider policy, and the endpoint at which the policy is acquired, by using the admin console or wsadmin commands. If we use the WS-MetadataExhange 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-MetadataExhange protocol.

See about multipart WSDL, see the topic about WSDL.

The Web app 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 set of WSDL, dynamic policy configuration occurs once, 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 that are based on this WSDL are cached in the client runtime (they are not persisted) and shared with each target service.

For example, in a cluster environment, this means that the client does not obtain the provider policy again for each endpoint instance of a Web service.

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.

 

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), 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 that contains WS-Policy attachments, for example WSRR V6.2 or later.

We can apply the provider policy that the client obtains from a registry at the service level, but not at the application level.

If there is a secure connection between the client and the registry, ensure that trust is established between the appserver and the registry server.

If the registry requires authentication, you also have to configure a policy to authenticate outbound service requests to the registry. 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 those credentials are not sent to an unauthorized endpoint.

 

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 you specify 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 you specify 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 could use either version in its Web service requests to the provider. In this situation, where more than one spec 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.

 

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 loaded. 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.wsspi.wspolicy.refreshProviderPolicy.

When the com.ibm.wsspi.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.wsspi.wspolicy.refreshProviderPolicy property is unset.

After an update of the policy provider is invoked, the next time that the Web service that is associated with the endpoint you selected is invoked, the policy of the service provider is obtained and the policy intersection is recalculated.

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

 

Related tasks

Set the client.policy using a service provider policy
Set the client.policy using a service provider policy from a registry
Set security for a WS-MetadataExchange request
Set the client.policy based on a service provider policy using wsadmin
Learn about WS-Policy

 

Related

Additional Application Programming Interfaces (APIs)
Policies applied settings
Policy set bindings settings