You can configure name-value pairs of data, where the name is a property key and the value is a string value that you can use to set internal system configuration properties. Defining a new property enables you to configure a setting beyond that which is available through options in the administrative console.
Custom properties for web services security can be set in various levels of the application server and for JAX-RPC versus JAX-WS applications. The following list of custom properties provides information on where the custom property is set and how it is used.
The web services security generic security token login module custom properties and the Web services security SAML token custom properties are documented in other information topics. Links to these topics are provided in the Related reference section of this topic.
You can define the following web services security custom properties:
Use this custom property to configure a digital signature, you can enable the web services security runtime to use SHA-2 signature algorithms.
For JAX-WS applications, set the following custom property in the signing information section of request or response to enable SHA-2 signature algorithms. Ensure that same value is used for both the client and provider when configuring this custom property.
Information | Value |
---|---|
Data type | String |
Values | rsa-sha256, rsa-sha384, rsa-sha512, hmac-sha256, hmac-sha384, hmac-sha512, or dsa-sha256 |
When you select the signature_message_part_reference name, you are accessing the configuration for the signed message part binding.
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 |
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 |
These two custom properties allow the administrator to control the setting of the mustUnderstand attribute in the SOAP Security header. These properties are set as outbound 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.
Information | Value |
---|---|
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.
Information | Value |
---|---|
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.
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 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.
Data type | Boolean |
Default | true |
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.
Use this property in conjunction with the com.ibm.wsspi.wssecurity.dsig.enableEnvelopedSignatureProperty JVM custom property to indicate to the WS-Security runtime that you want the WS-Security runtime to calculate the digest value as it did in Versions 7.0.0.21 and earlier for either outbound XML Digital Signature creation or inbound verification. For more information, see Java Virtual Machine (JVM) custom properties for a description of when you might want to use this JVM custom property.
This property is specified as either an Inbound, Outbound, or Inbound and Outbound custom property for the WS-Security policy set bindings.
This custom property determines how the WS-Security run time builds the SOAP Security header that is sent in an outbound SOAP message. By default, the run time uses a fast path using internal web services security (WSS) object representations to build the Security header. Alternatively, the Axis2 run time and objects can be used to build the Security header.
This property is set in the WS-Security policy set bindings as an outbound custom property or an inbound and outbound custom property. This property can be set to true or false. When this property is set to true, WSS Objects are used to build the Security header. When this property is set to false, Axis2 objects are used to build the Security header.
When using both WS-Security and WS-Addressing policies for both inbound and outbound messages, a problem might occur where the Body element appears in the header element in the outbound SOAP message. If this error occurs, set the com.ibm.wsspi.wssecurity.generator.useWSSObject custom property to false.
The default value is true.
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.
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.
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>
This JAX-WS custom property is added to the WebSphere WS-Security runtime to indicate that an EncodingType attribute should be added to nonce elements. When this custom property is set to true, the EncodingType attribute is added to all nonce elements in the SOAP Security header.
This property indicates whether a token consumer and/or token generator is enabled to obtain its token from the tokenHolder on the message context.
This property is only valid for JAX-WS applications.
Valid values for this property are true and false. The default value is false.
This property indicates whether a token consumer and/or token generator is enabled to obtain its token from the set of SecurityTokens in the inbound message. If there is more than one token in the inbound message that matches the value type of the token generator, then the token selected will be indeterminate.
This property is only valid for JAX-WS applications.
Valid values for this property are true and false. The default value is false.
For more information on the tokenHolder list, see passThroughToken in com.ibm.wsspi.wssecurity.core.config.IssuedTokenConfigConstants
When configuring a username token for the JAX-WS programming model, to protect against replay attacks it is strongly recommended that you add custom properties, com.ibm.wsspi.wssecurity.token.username.addNonce and com.ibm.wsspi.wssecurity.token.username.addTimestamp, to the callback handler configuration for token generation. These custom properties enable and verify the nonce and timestamp for message authentication. The value of the properties must be set to true.
When configuring a username token for the JAX-WS programming model, to protect against replay attacks it is strongly recommended that you add custom properties, com.ibm.wsspi.wssecurity.token.username.verifyNonce and com.ibm.wsspi.wssecurity.token.username.verifyTimestamp, to the callback handler configuration for the token consumer. These custom properties enable and verify the nonce and timestamp for message authentication. The value of the properties must be set to true.
This property allows the user registry check to be skipped
for identity tokens in JAX-WS. This means that the user name associated
with the identity token in an identity assertion scenario can pass
through the UNTConsumeLoginModule without generating a registry error.
Typically an identity token must not contain a password, and there
might, or might not be a trust token. For example there might be
a blind trust.
This property does not affect any UsernameToken that contains a password.
If you need
to bypass the registry check for a UsernameToken that contains a password,
see twbs_replace_authmethod_usernametoken. If a caller configuration
is required for the UsernameToken, see twbs_config_wssec_caller_no_reg.
When the property is set to true, the UNTConsumeLoginModule does not validate the inbound UsernameToken if, and only if, the UsernameToken does not contain a password.
Valid values for this property are true and false. The default value is false.
Web services security supports both LTPA (Version 1) and LTPA Version 2 (LTPA2) tokens. The LTPA2 token, which is more secure than Version 1, is supported in Version 7.0 by the JAX-WS run time only. You can set the Enforce token version interoperability option on the token generator to determine whether an LTPA (Version 1) or an LTPA2 token is retrieved when a request message is received. However, if you want to force the run time to use LTPA (Version 1) tokens only, you can set the com.ibm.wsspi.wssecurity.tokenGenerator.ltpav1.pre.v7 custom property to true
com.ibm.wsspi.wssecurity.tokenGenerator.ltpav1.pre.v7 custom property value | Enforce token version value | Result |
---|---|---|
false | Disabled | The run time can use both LTPA (Version 1) and LTPA2 tokens. |
not specified, which implies a false value | Disabled | The run time can use both LTPA (Version 1) and LTPA2 tokens. |
true | Disabled | The run time can use LTPA (Version 1) tokens only. |
true | Enabled | The run time can use LTPA (Version 1) tokens only. |
For more information, see the documentation about enabling or disabling single sign-on interoperability mode for the LTPA token.
When this property is set to true, the policy assertion is generated as a SamlToken if WSDL export is enabled on a WebSphere JAX-WS service provider that has a SAML policy set attached. If this property is set to false, a CustomToken assertion is generated.
This property applies to outbound or inbound and outbound requests.
The default value for this property is false.