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.
Name | Values | Description |
---|---|---|
stsURI | This custom property does not have a default value. |
Use this custom property to specify the Security Token Service (STS) address. This custom property is required for the token consumer. However, this custom property is optional for the token generator if the requested token exists in the RunAs Subject and its verification is not required. |
wstrustClientBinding | This custom property does not have a default value. |
Use this custom property to specify the binding name for the WS-Trust client. |
wstrustClientBindingScope | You can specify an application or domain value. | Use this custom property to specify the type
of bindings that are used for the WS-Trust client. The
following conditions apply:
This custom property is optional. |
wstrustClientPolicy | This custom property does not have a default value. |
Use this custom property to specify the policy set name for the WS-Trust client. |
wstrustClientSoapVersion | You can specify a 1.1 or 1.2 value. |
Use this custom property to specify the SOAP message version that the trust client uses to generate the SOAP message. The SOAP message is sent to the Security Token Service (STS). If you do not define this custom property, the generic security token login module uses the SOAP version of the application when it generates the SOAP message for the trust client request. The default value corresponds to the SOAP version that is used by the application client. This custom property is optional. |
wstrustClientWSTNamespace | Specify one of the following values:
|
Use this custom property to specify which trust client namespace the generic security token login modules uses when it makes the WS-Trust request. |
wstrustValidateClientBinding | By default, the value for this custom property is the same value that is specified for the wstrustClientBinding custom property. |
Use this custom property to specify the bindings that are used by the WS-Trust Validate request. If you do not specify this custom property, the WS-Trust Validate request uses the same bindings that are used by WS-Trust Issue, which are defined by the wstrustClientBinding custom property. |
wstrustValidateClientPolicy | By default, the value for this custom property is the same value that is specified for the wstrustClientPolicy custom property. |
Use this custom property to specify the policy sets to use with the WS-Trust Validate request. If you do not specify a value for this custom property, WS-Trust Validate uses the same policy set as WS-Trust Issue, which is defined by the required wstrustClientPolicy custom property. |
wstrustIssuer | You can use any string value. |
Use this custom property to specify the issuer for the request token. This custom property is optional |
wstrustValidateTargetOption | The default value is the WS-Trust base extension value. You can specify a token value or a base value, which is also the default value. |
Use this custom property to specify whether the WS-Trust client passes the validation token to the WS-Trust Security Token Service using the ValidateTarget or the Base element extension. The
following conditions apply:
|
Name | Value | Description |
---|---|---|
useRunAsSubject | You can use a True or False value. By default, a True value is used. This value for this custom property is not case sensitive. |
Use this custom property to specify whether the generic security token login modules use the token from the RunAs Subject for the outgoing request. By default, the login module uses the validated tokens in the RunAs Subject first. The following conditions apply:
|
useRunAsSubjectOnly | You can use a True or False value. By default, a False value is used. This value for this custom property is not case sensitive. |
Use this custom property to disable or enable WS-Trust Issue in the generic security token login module. If you set this custom property to a true value, the generic security token login module uses the token from the RunAs Subject and WS-Trust Validate to exchange the tokens. The generic security token login module does not use WS-Trust Issue to request a token even if WS-Trust Validate fails or it does not find a matching token in the RunAs Subject. |
useToken | You can use any string value of the ValueType value for the security token. |
When you use a security token in a RunAs Subject to validate and exchange tokens for an outbound request, you can use this custom property to specify which token ValueType value in the RunAs Subject to validate and exchange for the requested token. For example, you might have a token with a ValueType value of Token_1 in the RunAs Subject. However, the ValueType value of Token_2 is the required token. You can set this custom property to Token_1 . If you do not define this custom property, the validation token is the token from the RunAs Subject that has the same ValueType value as the required token. This custom property is optional. |
validateUseToken | You can use a True or False value. By default, a True value is used. This value for this custom property is not case sensitive. |
Use this custom property to specify whether the token generator uses WS-Trust Validate to validate the token from the RunAs Subject. By default, the generic security token login module validates a token from the RunAs Subject against the Security Token Service (STS) before sending the token in the SOAP message to the service provider. If you set this custom property value to false and the generic security token login module finds a matching token from the RunAs Subject, the login module does not invoke WS-Trust Validate to validate the matching token. Instead, it sends the matching token to the downstream service provider without validation. |
wstrustIncludeTokenType | You can use a True or False value. By default, a True value is used. This value for this custom property is not case sensitive. |
Use this custom property to specify whether the WS-Trust RequestedSecurityToken token includes the requested token ValueType value. If you do not specify this custom property, the generic security token login modules includes the requested token type in the WS-Trust RequestedSecurityToken token. This custom property is optional. |
Name | Value | Description |
---|---|---|
exchangedTokenType | The valid value for this custom property is the string ValueType value for the token that is supported by the system default login modules. |
Use this custom property to specify the new token with the defined ValueType value, which the trust service must return after successful validation. If you do not specify a value for the custom property, the generic security token login module accepts whichever token the trust service returns. This custom property is optional. |
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.
Data type | String |
Values | True, False |
Default | False |
The value for this property is case-insensitive.
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 Serverauthorization 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.
Data type | String |
Default | system.DEFAULT |
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 |
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])
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.
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 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 propery allows the user registry check to be skipped for identity tokens. 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, the UNTConsumeLoginModule that is provided with the product cannot be used. The following WS-Security custom property is added to the UNTConsumeLoginModule to allow the user registry check to be skipped for identity tokens:
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.