Web services security custom properties

Custom properties for Web services security can be set in various levels of the application server and for Java API for XML-based RPC (JAX-RPC) versus Java API for XML-Based Web Services (JAX-WS) applications. The following list of custom properties provides information on where the custom property is set and how it is used.

The following custom properties are available for Web services security:

com.ibm.ws.wssecurity.sc.FaultCode [Fix Pack 39 or later]

Use this custom property in a JAAS login module to set the SOAP fault code in the event of an error. If this property is not specified, the SOAP fault code wsse:FailedAuthentication is always returned.

In the custom JAAS login module, set the com.ibm.ws.wssecurity.sc.FaultCode property on the wssecurity context to the QName of the fault code that you want to use. For example:

fcQname = new QName(
          "http://schemas.xmlsoap.org/ws/2003/06/secext",
          "FailedCheck"); 
this._context = propertyCallback.getProperties();
 _context.put("com.ibm.ws.wssecurity.sc.FaultCode", fcQname);
Data type String
Default none

com.ibm.wsspi.wssecurity.config.request.setMustUnderstand and com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne

In WebSphere® Application Server prior to Version 6.1x, the mustUnderstand=1 attribute in the <wsse:Security> tag in the SOAP header on the request from the Web Services client was hardcoded. It was not possible to configure the mustUnderstand attribute in the SOAP Web services security header. In an update to the product, an administrator can configure the attribute using outbound generator custom properties.

You can configure the following outbound generator custom properties for Web services security:
com.ibm.wsspi.wssecurity.config.request.setMustUnderstand

The com.ibm.wsspi.wssecurity.config.request.setMustUnderstand custom property specifies the mustUnderstand setting in outbound consumer requests. If the value of the property is set to zero (0), no, or false, then the mustUnderstand attribute is not set in the WS-Security header within outbound consumer requests.

Data type String
Value Zero (0), no, false
Default true

In SOAP messages, the default value for the mustUnderstand attribute is zero (0). According to the SOAP specification, if the intended value for the attribute is zero, then the attribute must not be present in the message.

com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne

The com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne custom property specifies that the provider should always respond with a mustUnderstand="1" attribute in the SOAP security header. If the value is set to one (1), yes, or true, the provider responds with the mustUnderstand="1" attribute in the WS-Security header. The default value of the attribute is false.

Data type String
Value One (1), yes, or true
Default false

By default, the response contains the same mustUnderstand attribute as the request. For example, if the inbound request has mustUnderstand="1", the response also includes mustUnderstand="1". If the request does not have a mustUnderstand attribute, the response does not include a mustUnderstand attribute.

For JAX-RPC applications, you can specify both properties in the following locations within the administrative console:
  • Click Servers >Application Servers > server name >Web services: Default bindings for Web services security, then under Additional Properties, click Properties.
  • Click Servers >Application Servers > server name >Web services: Default bindings for Web services security, then under Default Generator Bindings, click Properties.

If you are using an assembly tool with a JAX-RPC WS-Security version 1.0 application, you can set the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand custom property on the security request generator extension or binding. You can set the com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne custom property on the response generator extension or binding. A setting in the binding takes precedence over a setting in the extension.

If using an assembly tool with a JAX-RPC WS-Security specification draft 13–level application, you can set the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand custom property as a parameter on the port qualified name binding. You can set the com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne custom property as a parameter on the port component binding.

[Updated in February 2012] For JAX-WS applications, you can set these custom properties as inbound custom properties or inbound and outbound custom properties for the policy set bindings. Complete the following steps in the administrative console to set the custom property:
  • Expand Services > Policy sets.
  • Click General provider policy set bindings or General client policy set bindings.
  • Click the binding_name.
  • Under the Policy heading, click WS-Security > Custom properties.
[Updated in February 2012]
feb2012
[Updated in February 2012] You can also set these custom properties as parameters or as inbound binding properties on your application using wsadmin tooling. The following WS-Security policy-type property names are used in setBinding:
  • application.parameters
  • application.securityinboundbinding config.properties
[Updated in February 2012]
feb2012
However, properties values in the application.securityoutboundbindingconfig.properties properties take precedence over properties in application parameters. The follow example shows how to use Jython wsadmin commands to obtain the ID of the policy set attachment for a consumer, then set the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand property to false in the outbound binding configuration:
AdminTask.getPolicySetAttachments([-applicationName
HelloSvcClientEAR -attachmentType client])

AdminTask.setBinding([-policyType WSSecurity -bindingLocation "[
[application HelloSvcClientEAR] [attachmentId 1490] ]"
-attributes "[[application.securityoutboundbindingconfig.properties_999.name
com.ibm.wsspi.wssecurity.config.request.setMustUnderstand]
[application.securityoutboundbindingconfig.properties_999.value
false]]" -attachmentType client])

com.ibm.wsspi.wssecurity.login.useStandardFaultCodes [Fix Pack 23 or later]

This custom property enables the JAX-WS runtime to return Oasis standard fault codes for Web services security. To receive the Oasis standard fault codes, you must set this custom property to true. You can set the custom property in the custom bindings for an application or in the WS-Security default binding. To set the custom property in the WS-Security default binding through the administrative console, complete the following steps:
  1. Expand Services > Policy sets.
  2. Click Default policy set bindings.
  3. Under the Policy heading, click WS-Security.
  4. Under the Main message security policy bindings heading, click Custom properties.
Avoid trouble Avoid trouble: On the custom properties panel, you can set this property as an inbound custom property or an inbound/outbound custom property. It is not valid as an outbound custom property.gotcha

com.ibm.wsspi.wssecurity.dsig.inclusiveNamespaces

This custom property, which applies to both the JAX-RPC and JAX-WS applications, specifies whether to disable the inclusive namespace prefix list for XML digital signatures. WebSphere Application Server, by default, includes the prefix in the digital signature for Web services security. You can set this custom property to false if you do not want inclusive namespaces set as an element. Some implementations of Web services security cannot handle this prefix list. If you experience a signature validation failure when a signed SOAP message is sent and you are using another vendor in your environment, check with your service provider for a possible fix to their implementation before you disable this property.

For JAX-RPC applications, you can set the custom property in the administrative console in the signing information or as a Web services security custom property in additional properties or in the default or custom generator bindings. For more information, see the additional properties and generator sections of the Configuring custom properties to secure Web services topic. Prior to Version 6.1.0.19 and 6.0.2.31, you can add this custom property to the signing information only. To add the custom property to the signing information, complete the following steps:
  1. Click Applications > Enterprise Applications > application_name.
  2. Click Manage Modules > module_name.
  3. Under Web Services Security Properties, click Web services: Client security bindings or Web services: Server security bindings.
  4. Under Request generator (sender) binding or Response generator (sender) binding, click Edit custom.
  5. Under Required properties, click Signing information > signing_information_name > Properties.
  6. Specify the custom property and its value.
For JAX-WS applications, you can configure this custom property in the outbound signing information. To configure the custom property, complete the following steps:
  1. Click Services > Service clients > or Services > Service providers.
  2. Click the service_name > binding_name.
  3. Under Policy, click WS-Security
  4. Under Message Security Policy Bindings, click Authentication and protection >
  5. Under either Request message signature and encryption protection or Response message signature and encryption protection, click the signature_message_part_reference. When you click the signature_message_part_reference name, you are accessing the configuration for the signed message part binding.
  6. Specify the custom property and its value.

com.ibm.wsspi.wssecurity.config.disableWSSIfApplicationSecurityDisabled [Fix Pack 25 or later]

When you set the com.ibm.wsspi.wssecurity.config.disableWSSIfApplicationSecurityDisabled custom property to true, Web services security does not enforce the configured WS-Security constraints if application security is disabled on the application server. You can use this custom property to debug services in a non-secure environment without needing to remove security constraints from Web services applications.

Best practice Best practice: Use this custom property for diagnosis purposes only. Do not use it in a production environment.bprac
Data type String
Values true, false
Default false
You can set this custom property as an inbound custom property or an inbound and outbound custom property for the default policy set bindings. Complete the following steps in the administrative console to set the custom property:
  1. Expand Services > Policy sets.
  2. Click Default policy set bindings.
  3. Under the Policy heading, click WS-Security.
  4. Under the Main message security policy bindings heading, click Custom properties.
You can also set this custom property as a parameter or as an inbound binding property on your application using wsadmin tooling. The following WS-Security policy-type property names are used in setBinding:
  • application.parameters
  • application.securityinboundbinding config.properties

com.ibm.wsspi.wssecurity.config.gen.checkCacheUsernameTokens [Fix Pack 27 or later]

The com.ibm.wsspi.wssecurity.config.gen.checkCacheUsernameTokens custom property specifies whether to cache UsernameTokens all of the time, which is the default behavior, or cache them as determined by a set of rules. You can configure this custom property for the token generator or as an additional property.

When the com.ibm.wsspi.wssecurity.config.gen.checkCacheUsernameTokens custom property is set to false, UsernameTokens are always cached on client threads. When you set this custom property to true, the web services security run time determines whether UsernameTokens are cached based on the following rules:
  • Never cache UsernameTokens if the application is running on an application server.
  • Cache UsernameTokens if the token generator for the UsernameToken has the following callback handler configured: com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler.

This custom property applies to the JAX-RPC run time only. Use an assembly tool, such as Rational Application Developer, to set the custom property within the encrypted message part bindings.

Data type String
Values true, false
Default false

com.ibm.wsspi.wssecurity.config.token.inbound.retryOnceAfterTrustFailure [z/OS] [AIX HP-UX Linux Solaris Windows] [Fix Pack 33 or later]

The com.ibm.wsspi.wssecurity.config.token.inbound.retryOnceAfterTrustFailure custom property specifies whether a trust store can be reloaded after an application server starts.

A trust store is a key store. By default, JAX-WS WS-Security does not acknowledge the refresh of any keystores while the application server is running. For performance reasons, keystores are cached in memory when each application is started. Because the cache is shared among applications, even if a single application is stopped, its keystores remain in the cache. Therefore, if a trusted certificate, that is used by an X.509 token consumer, is added to a trust store after the application server starts, the trust validation fails.

If you set the com.ibm.wsspi.wssecurity.config.token.inbound.retryOnceAfterTrustFailure property to true, when a trust validation occurs, the WS-Security runtime reloads its configured trust store and tries the trust validation one more time. The reloaded trust store is only used for this single re-validation attempt. The keystore object in the cache is not replaced because replacing the keystore object might cause concurrency issues.

If the second validation attempt fails, a trust validation failure is returned to the client.

The default value for this property is false.
Avoid trouble Avoid trouble: This property is set as a custom property on the Callback handler for an X.509, PKIPath, or PKCS#7 token consumer. To set the property in the administrative console, click binding_name > WS-Security > Authentication and protection > token_name > Callback handler For an application using the WS-Security WSS API, this property can also be set on the Callback handler for the token consumers that are previously listed.gotcha

com.ibm.wsspi.wssecurity.consumer.timestampRequired

The com.ibm.wsspi.wssecurity.consumer.timestampRequired property specifies whether Timestamp is not expected in the security header for the response when the Include timestamp in security header setting is selected for the WS-Security policy.

The JAX-WS WS-Security runtime is updated to comply with the OASIS WS-SecurityPolicy 1.2 specification Timestamp Required requirement. If you want to configure an application to not require an inbound time stamp when an outbound time stamp is configured you can add the com.ibm.wsspi.wssecurity.consumer.timestampRequired custom property to your Web Services Security settings and set that property to false. When this property is set to false, even if the Include timestamp in security header is selected as a setting for the WS-Security policy, a Timestamp is not expected in the security header for a response.

The default value for this property is true.

Avoid trouble Avoid trouble: On the custom properties panel, you can set this property as either an inbound or an inbound/outbound custom property. It is not valid as an outbound custom property.gotcha
Data type Boolean
Default true

com.ibm.wsspi.wssecurity.login.useSoap12FaultCodes [Fix Pack 35 or later]

[Updated in March 2011] The com.ibm.wsspi.wssecurity.login.useSoap12FaultCodes custom property specifies that the WS-Security runtime must emit a SOAP 1.2 fault code when a fault is returned in response to a SOAP 1.2 message. [Updated in March 2011]

mar2011

[Updated in March 2011] When this property is set to true, the WS-Security runtime returns a SOAP 1.2 fault code in response to a SOAP 1.2 message. [Updated in March 2011]

mar2011

When this property is set to false, the WS-Security runtime returns a SOAP 1.1 fault code in response to a SOAP 1.2 message.

The default value for this property is false.

This property needs to be set as either a WS-Secrutiy Inbound or Inbound and Outbound custom properties for a specific binding.

Following is an example of a valid SOAP 1.2 fault that is returned when this property is set to true:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv=" http://www.w3.org/2003/05/soap-envelope"> 
  <soapenv:Body> 
    <soapenv:Fault> 
      <soapenv:Code> 
        <soapenv:Value>soapenv:Sender</soapenv:Value>
        <soapenv:Subcode>
          <soapenv:Value xmlns:axis2ns1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">axis2ns1:FailedAuthentication</soapenv:Value>
        </soapenv:Subcode> 
      </soapenv:Code> 
      <soapenv:Reason> 
        <soapenv:Text>CWWSS6521E: The Login failed because  
          of an exception: javax.security.auth.login.LoginException:  
          CWWSS7062E: Failed to check username [user1] and password in  
          the UserRegsitry: WSSUserRegistryProcessor.checkRegistry()=false 
        </soapenv:Text> 
      </soapenv:Reason> 
      <soapenv:Detail></soapenv:Detail> 
    </soapenv:Fault> 
  </soapenv:Body> 
</soapenv:Envelope>



Related tasks
Configuring custom properties to secure Web services
Related reference
[Fix Pack 21 or later] Inbound and outbound custom properties
Related information
http://www.w3.org/TR/xml-exc-c14n/
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 1:23:07 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=rwbs_customproperties
File name: rwbs_customproperties.html