Web services security custom properties

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 allows configuration of a setting beyond what 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:

com.ibm.websvcs.client.serializeSecurityContext

When a JAX-WS client is run on an application server, service calls can be slower when base security is enabled than when base security is not enabled. To adjust service call speed, you can use the com.ibm.websvcs.client.serializeSecurityContext property. When the com.ibm.websvcs.client.serializeSecurityContext property is set to false in the request context on the binding provider for the service call, the WebSphere® security context will not be serialized to the web services message context. The following example illustrates setting this property.

javax.xml.ws.BindingProvider bp;

bp.getRequestContext().put("com.ibm.websvcs.client.serializeSecurityContext", "false");

Note: The com.ibm.websvcs.client.serializeSecurityContext property cannot be used in conjunction with a Reliable Messaging policy set.

Information	Value
Data type	String
Values	True, False
Default	True

com.ibm.ws.wssecurity.createSTR

The com.ibm.ws.wssecurity.createSTR property creates a security token reference to the security token in the SOAP security header when you specify a True value.

You can set this property to True, the com.ibm.ws.wssecurity.createSTR property creates a security token reference to the security token in the SOAP security header. Set this custom property to True when the following conditions exist:

The referencing mechanism for the token signature is the STR Dereference Transform, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform
The SignedParts element for the WS-Security policy contains an XPath value that represents the SecurityTokenReference.

This property is configured as a custom property on the SAML token generator. It is not configured on the callback handler.

Information	Value
Data type	String
Values	True, False
Default	False

The value for this property is case-insensitive.

com.ibm.ws.wssecurity.dsig.SignatureAlgorithm

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.

The com.ibm.ws.wssecurity.dsig.SignatureAlgorithm custom property specifies the SHA-2 signature algorithms for XML digital signatures. By default, WebSphere Application Server uses SHA1withRSA or HMACSHA1 to generate digital signatures.

Information	Value
Data type	String
Values	rsa-sha256, rsa-sha384, rsa-sha512, hmac-sha256, hmac-sha384, hmac-sha512, or dsa-sha256

For JAX-WS applications, you can configure the com.ibm.ws.wssecurity.dsig.SignatureAlgorithm custom property from either the outbound signing information or inbound signing information. To configure com.ibm.ws.wssecurity.dsig.SignatureAlgorithm, complete the following steps:

Click Services > Service clients or Service providers > service_name > binding_name > WS-Security > Authentication and protection to access the WS-Security authentication and protection page.
Under either Request message signature and encryption protection or Response message signature and encryption protection, click the signature_message_part_reference name to access the configuration for the signed message part binding.
Specify the custom property. For example com.ibm.ws.wssecurity.dsig.SignatureAlgorithm and enter the wanted algorithm as a property value with one of the values identified in the previous table.

com.ibm.ws.wssecurity.dsig.CanonicalizationAlgorithm

Use this custom property to configure the canonicalization algorithm for digital signature.

For JAX-WS applications, set the com.ibm.ws.wssecurity.dsig.CanonicalizationAlgorithm custom property in the signing information section of request or response. This property only needs to be set for outbound messages.

Information	Value
Data type	String
Default	http://www.w3.org/2001/10/xml-exc-c14n#

To configure com.ibm.ws.wssecurity.dsig.CanonicalizationAlgorithm custom property, complete the following steps:

Click Services > Service clients or Service providers > service_name > binding_name > WS-Security > Authentication and protection to access the WS-Security authentication and protection page.
Under either Request message signature and encryption protection or Response message signature and encryption protection, click the signature_message_part_reference name to access the configuration for the signed message part binding.
Specify the com.ibm.ws.wssecurity.dsig.CanonicalizationAlgorithm custom property, and enter the wanted canonicalization algorithm as the property value. An example value is http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments.

com.ibm.ws.wssecurity.sc.FaultCode

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);

Information	Value
Data type	String
Default	none

com.ibm.ws.wssecurity.useInboundBodyOptimization

Use this JVM custom property to force the WS-Security runtime to use key encryption. You can use this property when the run time has a problem evaluating the decryption key from an inbound encrypted message. To force key encryption, set the property to false.

Information	Value
Data type	String
Default	true

com.ibm.ws.wssecurity.useOldCloneCriteria

When this Java™ virtual machine (JVM) system property is set to true, only Lightweight Third Party Authentication (LTPA) tokens are cloned before being put into the runAs subject.

Information	Value
Data type	String
Default	false

com.ibm.wsspi.wssecurity.Caller.assertionLoginConfig

The com.ibm.wsspi.wssecurity.Caller.assertionLoginConfig property, which is configured on the caller part, specifies the name of the JAAS login configuration that is used by Web Services Security to obtain WebSphere Application Server authorization credentials. You must configure this property using an assembly tool such as the Rational® Application Developer. For more information, see the Configuring the caller in consumer security constraints topic for Rational Application Developer. Within this topic, this custom property is set when you configure identity assertion.

Use this property with WS-Security V1.0 JAX-RPC applications only.

Information	Value
Data type	String
Default	system.DEFAULT

com.ibm.wsspi.wssecurity.config.disableWSSIfApplicationSecurityDisabled

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: Use this custom property for diagnosis purposes only. Do not use it in a production environment.

Information	Value
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 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.

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

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.

Information	Value
Data type	String
Values	true, false
Default	false

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

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.

You can configure the following outbound generator custom properties for Web Services Security:

com.ibm.wsspi.wssecurity.config.request.setMustUnderstand custom property

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.

Avoid trouble: The instructions for setting the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand property are the same as the instructions for setting com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne.

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

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.

For JAX-WS applications, you can set the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand and com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne custom properties as outbound custom properties or as inbound and outbound custom properties for the policy set bindings. Complete the following steps in the administrative console to set the custom properties:

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.

You can also set the com.ibm.wsspi.wssecurity.config.request.setMustUnderstand and com.ibm.wsspi.wssecurity.config.response.forceMustUnderstandEqualsOne custom properties as parameters or as an outbound binding properties on your application using wsadmin tooling. The following WS-Security policy-type property names are used in setBinding:

application.parameters
application.securityinboundbindingconfig.properties

For JAX-RPC applications, you can specify both properties in the following locations within the administrative console:

Click Servers > Server Types > WebSphere application servers > server name. Under Security, click JAX-WS and JAX-RPC security runtime. Under JAX-RPC Default Generator Bindings, click Properties.
Click Servers > Server Types > WebSphere application servers > server name. Under Security, click JAX-WS and JAX-RPC security runtime. Under Custom properties, click Custom 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.

com.ibm.wsspi.wssecurity.config.token.inbound.retryOnceAfterTrustFailure

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: This property is set as a custom property on the Callback handler for an X.509, PKIPath, or PKCS#7 token consumer. To set this 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.

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: 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.

Information	Value
Data type	Boolean
Default	true

com.ibm.wsspi.wssecurity.core.NonceCacheTimeout

Specify a value in seconds for the Nonce cache timeout field. The value that is specified for the Nonce cache timeout field indicates the number of seconds a nonce remains cached before it is discarded. The minimum value is 300. The default value is 600.