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:
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.
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.
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.
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.
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])
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.
The com.ibm.wsspi.wssecurity.encrypt.expandData custom property specifies whether the WS-Security engine must expand the data that is being encrypted before the WS-Security engine starts the encryption process. Expanding the data before encrypting that data ensures that the WS-Security engine can properly locate the beginning of the SOAP body.
If this property is not specified, when encryption is completed on data from a JAX-WS Web services sender, characters that appear ahead of the SOAP body might be erroneously included in the encrypted data. When this encrypted data is sent to the server, and then decrypted, the extra characters prevent the decrypted data from forming a valid SOAP body. This situation causes an XMLStreamException to occur when the WS-Security engine attempts to transform the decrypted bytes into an object model for processing. This situation is prevented if the data is expanded before the encryption process starts.
Valid values for this property are true and false. The default value is false.
This property is set on the Encrypted message part bindings administrative console page. To locate the Encrypted message part bindings administrative console page, in the administrative console, click Policy sets > Service clients > application_name > binding_name >WS-Security-> Authentication and protection > encrypted_part_name .
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.
Data type | String |
Values | true, false |
Default | false |
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.
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 |
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 currency issues.
If the second validation attempt fails, a trust validation failure is returned to the client.
The com.ibm.wsspi.wssecurity.login.useSoap12FaultCodes custom property specifies whether the WS-Security runtime is updated to emit the proper SOAP 1.2 fault code when a fault is returned in response to a SOAP 1.2 message.
When this property is set to true, the WS-Security runtime is returns a SOAP 1.2 fault code in response to a SOAP 1.2 message.
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.
<?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>