WSSecurity policy and binding properties

WSSecurity policy and binding properties

Use the attributes parameter for the setPolicyType and setBinding commands to specify additional configuration information for the WSSecurity policy and binding configurations. Application and system policy sets can use the WSSecurity policy and binding configuration.

Before using the commands in this topic, verify that we are using the most recent version of the wsadmin tool. The policy set management commands that accept a properties object as the value for the attributes or bindingLocation parameters are not supported on previous versions of the wsadmin tool. For example, the commands do not run on a v6.1.0.x node.

Use the following commands in the PolicySetManagement group of the AdminTask object to customize your policy set configuration.

Use the -attributes parameter for the getPolicyType and getBinding commands to view the properties for our policy and binding configuration. To get an attribute, pass the property name to the getPolicyType or getBinding command.
Use the -attributes parameter for the setPolicyType and setBinding commands to add, update, or remove properties from your policy and binding configurations. To add or update an attribute, specify the property name and value. The setPolicyType and setBinding commands update the value if the attribute exists, or adds the attribute and value if the attribute does not exist. To remove an attribute, specify the value as an empty string (""). The -attributes parameter accepts a properties object.

If a property name or value supplied with the -attributes parameter is not valid, then the setPolicyType and setBinding commands fail with an exception. The property that is not valid is logged as an error or warning in the SystemOut.log file. However, the command exception might not contain the detailed information for the property that caused the exception. When the setPolicyType and setBinding commands fail, examine the SystemOut.log file for any error and warning messages that indicate that the input for the -attributes parameter contains one or multiple properties that are not valid.
IBM recommends using the High Performance Extensible Logging (HPEL) log and trace infrastructure . We view HPEL log and trace information using the logViewer .
For transitioning users: In WAS v7.0 and later, the security model was enhanced to a domain-centric security model instead of a server-based security model. The configuration of the default global security (cell) level and default server level bindings has also changed in this version of the product. In the WAS v6.1 Feature Pack for Web Services, we can configure one set of default bindings for the cell and optionally configure one set of default bindings for each server. In v7.0 and later, we can configure one or more general service provider bindings and one or more general service client bindings. After we have configured general bindings, we can specify which of these bindings is the global default binding. We can also optionally specify general binding used as the default for an application server or a security domain. trns
To support a mixed-cell environment, WAS supports v7.0 and v6.1 bindings. General cell-level bindings are specific to v7.0 and later Application-specific bindings remain at the version that the application requires. When the user creates an application-specific binding, the application server determines the required binding version to use for application.

If the attributes parameter is not specified for the getPolicyType or getBinding command, the command returns all properties. If a partial property name is passed to the getPolicyType or getBinding command, the command returns all properties with names that start with the partial property name. For example, If SignatureProtection is passed to the getPolicyType command, the command returns all properties with names that start with "SignatureProtection", which might include:
SignatureProtection.response:
   int_body.SignedParts.Body,SignatureProtection.response:int_body.SignedParts.Header_0.Name
and
SignatureProtection.response:int_body.SignedParts.Header_0.Namespace
There are an extensive number of combinations of settings available to secure the web service applications. Because of the number of attributes and configuration options from the WS-Security Version 1.0 specification, all attributes are not defined in this topic. The following sections explain the hierarchy structure for the WSSecurity policy and binding attributes:

WSSecurity policy properties
WSSecurity binding properties
setPolicyType and setBinding command examples

WSSecurity policy properties

Use the getPolicyType command to review a properties object with the properties configured in your current WSSecurity policy file. Security policy schemata define the security assertions. Because the elements in the schema have hierarchical relationship, the property names for security policy also have the similar hierarchy. The hierarchical relationship between property names in the security policy is represented by a period (.) between two levels, concatenating the parent and child attributes. Examples of the properties include, but are not limited to, IncludeToken, Name, Namespace, XPath, XPathVersion. The following list describes the top-level assertion policy property names for the WSSecurity policy file:

AsymmetricBinding

We can specify zero or one binding assertion.

SymmetricBinding

We can specify zero or one binding assertion. AsymmetricBinding and SymmetricBinding cannot co-exist in a security policy file.

Wss11

We can specify zero or one Wss11 assertion.

Wss10

We can specify zero or one Wss10 assertion.

Trust10

We can specify zero or one Trust10 assertion.

SignatureProtection

We can specify zero or any number of signature protection assertions.

EncryptionProtection

We can specify zero or any number of encryption protection assertions

SupportingTokens

We can specify zero or any number of supporting token assertions.

For example, the following policy file example displays an AsymmetricBinding assertion:
    <sp:AsymmetricBinding>
      <wsp:Policy>
        <sp:InitiatorSignatureToken>
          <wsp:Policy>
            <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy
						/200512/IncludeToken/AlwaysToRecipient">
              <wsp:Policy>
                <sp:WssX509V3Token10 />
              </wsp:Policy>
            </sp:X509Token>
          </wsp:Policy>
        </sp:InitiatorSignatureToken>
        <sp:RecipientSignatureToken>
          <wsp:Policy>
            <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy
						/200512/IncludeToken/AlwaysToInitiator">
              <wsp:Policy>
                <sp:WssX509V3Token10 />
              </wsp:Policy>
            </sp:X509Token>
          </wsp:Policy>
        </sp:RecipientSignatureToken>
        <sp:AlgorithmSuite>
          <wsp:Policy>
            <sp:Basic256/>
          </wsp:Policy>
        </sp:AlgorithmSuite>
        <sp:Layout>
          <wsp:Policy>
            <sp:Strict/>
          </wsp:Policy>
        </sp:Layout>
      </wsp:Policy>
    </sp:AsymmetricBinding><sp:AsymmetricBinding>
      <wsp:Policy>
        <sp:InitiatorSignatureToken>
          <wsp:Policy>
            <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy
						/200512/IncludeToken/AlwaysToRecipient">
              <wsp:Policy>
                <sp:WssX509V3Token10 />
              </wsp:Policy>
            </sp:X509Token>
          </wsp:Policy>
        </sp:InitiatorSignatureToken>
        <sp:RecipientSignatureToken>
          <wsp:Policy>
            <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy
						/200512/IncludeToken/AlwaysToInitiator">
              <wsp:Policy>
                <sp:WssX509V3Token10 />
              </wsp:Policy>
            </sp:X509Token>
          </wsp:Policy>
        </sp:RecipientSignatureToken>
      </wsp:Policy>
      <sp:AlgorithmSuite>
        <wsp:Policy>
          <sp:Basic256/>
        </wsp:Policy>
      </sp:AlgorithmSuite>
      <sp:Layout>
        <wsp:Policy>
          <sp:Strict/>
        </wsp:Policy>
      </sp:Layout>
    </sp:AsymmetricBinding>
The AsymmetricBinding assertion returns the following property name and value pairs. The nested wsp:Policy layers are not displayed in the returned properties. Additionally, some properties return the true value which indicates that the WSSecurity configuration includes the related XML elements. To edit these properties, set the value as true to include the property, or set the value as an empty string, "", to remove the property.
AsymmetricBinding.Layout = Strict
AsymmetricBinding.AlgorithmSuite.Basic256 = true AsymmetricBinding.RecipientSignatureToken.X509Token_0.IncludeToken = http://docs.oasis-open.org
/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToInitiator
AsymmetricBinding.InitiatorSignatureToken.X509Token_0.WssX509V3Token10 = true AsymmetricBinding.InitiatorSignatureToken.X509Token_0.IncludeToken = http://docs.oasis-open.org
/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient
AsymmetricBinding.RecipientSignatureToken.X509Token_0.WssX509V3Token10 = true 
Additionally, the following policy file example displays a SupportingTokens assertion:
<sp:SupportingTokens>
        <wsp:Policy wsu:Id="request:custom_auth">
            <spe:CustomToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/
							ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                    <spe:WssCustomToken uri=http://bar.com/MyCustomToken localname="tokenv1">
                    </spe:WssCustomToken>
                </wsp:Policy>
            </spe:CustomToken>
        </wsp:Policy>
    </sp:SupportingTokens
The SupportingTokens assertion returns the following property name and value pairs. The nested wsp:Policy layers are not displayed in the returned property.
SupportingTokens.request:custom_auth.CustomToken_0.WssCustomToken.uri=http://bar.com
/MyCustomToken
SupportingTokens.request:custom_auth.CustomToken_0.IncludeToken=http://docs.oasis-open.org
/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient
SupportingTokens.request:custom_auth.CustomToken_0.WssCustomToken.localname=tokenv1
The CustomToken property contains a subscript zero notation ( _0 ) because the property might be displayed multiple times from the same type of token such as the RecipientSignatureToken or InitiatorSignatureToken tokens.
Although most property names follow the hierarchical relationship format described previously, the following exceptions exist:
The wsu:Id element
This element uses the actual value for the ID instead of using Id as the attribute name. The following policy file example property:
<wsp:Policy wsu:Id="response:int_body">
  <sp:SignedParts>
    <sp:Body/>
  </sp:SignedParts>
</wsp:Policy>
The previous wsu:Id example returns the following properties:
SignatureProtection.response:int_body.SignedParts.Body = true 
The Header element
Because there can be multiple Header elements, the Header_n notation is used to represent this property. See the following policy file example:
 <wsp:Policy wsu:Id="request:conf_body">
     <sp:EncryptedParts>
       <sp:Body/>
       <sp:Header Name="MyElement" Namespace="http://foo.com/MyNamespace" />
     </sp:EncryptedParts>
   </wsp:Policy>
The previous Header example returns the following properties:
EncryptionProtection.request:conf_body.EncryptedParts.Header_0.Name=MyElement
EncryptionProtection.request:conf_body.EncryptedParts.Header_0.Namespace=http://
foo.com/MyNamespace
The XPath element
The XPath_n notation is used to represent this property because there can be multiple XPath elements. See the following policy file example:
<wsp:Policy wsu:Id="request:int_body">
      <sp:SignedElements>
        <sp:XPath>SomeXPathExpression</sp:XPath>
        <sp:XPath>SomeOtherXPathExpression</sp:XPath>
      </sp:EncryptedElements>
    </wsp:Policy>
The previous XPath example returns the following properties:
SignatureProtection.request:int_body.SignedElements.XPath_0=SomeXPathExpression
SignatureProtection.request:int_body.SignedElements.XPath_1=SomeOtherXPathExpression
The X509Token element
Use the X509Token_n notation to represent this property because multiple X509Token elements can exist. For an example, see the AsymmetricBinding assertion.

The CustomToken element
Use the CustomToken_n notation to represent this property because multiple CustomToken elements can exist. For an example, see the SupportingTokens assertion.
WSSecurity binding properties

Use the getBinding command to review a properties object with the properties configured in your current WSSecurity binding configuration. We can also use the administrative console to configure the WSSecurity bindings. Use the information center topics for configuring WSSecurity bindings with administrative console for more information.

The properties defined in this section reflect the hierarchy of the binding schema. Each part of the property name is a lowercase version of the schema type. For example, the application.securityinboundbindingconfig.tokenconsumer_0.jaasconfig.configname property follows the hierarchal format. The attributes begin with application or bootstrap. Attributes that begin with application represent bindings associated with the main WS-Security policy. Attributes that begin with bootstrap represent bindings associated with the WS-Security bootstrap policy, where the WS-Security policy uses Secure Conversation.

Some property names might have an _n notation appended to them. This notation represents a list of items. For example, multiple tokenconsumer properties exist and are listed from tokenconsumer_0 through tokenconsumer_n, where the set of tokenconsumer values are:
application.securityinboundbindingconfig.tokenconsumer_0.callbackhandler.
certpathsettings.certstoreref.reference
application.securityinboundbindingconfig.tokenconsumer_0.callbackhandler.
certpathsettings.trustanchorref.reference
application.securityinboundbindingconfig.tokenconsumer_0.callbackhandler.classname
application.securityinboundbindingconfig.tokenconsumer_0.classname
application.securityinboundbindingconfig.tokenconsumer_0.jaasconfig.configname
application.securityinboundbindingconfig.tokenconsumer_0.name
application.securityinboundbindingconfig.tokenconsumer_0.valuetype.localname
application.securityinboundbindingconfig.tokenconsumer_0.valuetype.uri
Additionally, some properties in the security binding file return a value of true when queried. To set these properties, set the value to true to include the property, or set the value to an empty string ("") to remove the property. For example, the time stamp, nonce, and trustAnyCertificate properties follow this pattern.

Use the setBinding command and the attributes parameter to add or remove properties to the WSSecurity binding configuration.
To add a property, use the setBinding command to pass the property name with a non-zero length string value. To add a list item, use the _n notation to reflect a numeric value that is greater than any current numeric value for the property. For example, if the tokenconsumer_0 and tokenconsumer_1 properties exist in the configuration, specify the new tokenconsumer property as tokenconsumer_2. After adding a property, use the getBinding command to view the most recent list of configured properties.
To remove a property, use the setBinding command to pass the property name with an empty string (""). For example, to remove all of the tokenconsumer_0 properties, specify the following property with the attributes parameter:
application.securityinboundbindingconfig.tokenconsumer_0=""
The previous example removes all properties that begin with the application.securityinboundbindingconfig.tokenconsumer_0 property name.
The following examples display several sets of properties to configure for our binding. This list does not include all properties to configure for the WSSecurity binding. Use this information as a reference to determine how to form specific property names.
signinginfo element
Configure signing information. For a custom binding, an unlimited number of signinginfo elements specified for the securityoutboundbindingconfig and securityinboundbindingconfig assertions can exist. In the default bindings, the system allows a maximum of two signinginfo elements for the securityoutboundbindingconfig and securityinboundbindingconfig assertions. The following example displays the format for two signinginfo elements:
application.securityinboundbindingconfig.signinginfo_0.signingkeyinfo_0
.reference=con_signkeyinfo
application.securityinboundbindingconfig.signinginfo_0.signingpartreference_0
.reference=request:int_body
application.securityoutboundbindingconfig.signinginfo_0.signingpartreference_0
.reference=response:int_body
application.securityoutboundbindingconfig.signinginfo_0.signingpartreference_0.timestamp=true
encryptioninfo element
Configure encryption information. For a custom binding, an unlimited number of encryptioninfo elements specified for the securityoutboundbindingconfig and securityinboundbindingconfig assertions can exist. In the default bindings, the system accepts a maximum of two encryptioninfo elements for the securityoutboundbindingconfig and securityinboundbindingconfig assertions. The following example displays the format for two encryptioninfo properties:
application.securityinboundbindingconfig.encryptioninfo_0.encryptionpartreference
.nonce=true
application.securityinboundbindingconfig.encryptioninfo_0.encryptionpartreference
.reference=request:conf_body
application.securityoutboundbindingconfig.encryptioninfo_0.encryptionpartreference
.nonce=true
application.securityoutboundbindingconfig.encryptioninfo_0.encryptionpartreference
.timestamp=true
tokengenerator element
In the default bindings, the tokengenerator elements that the signinginfo or encryptioninfo elements do not reference are considered to be authentication token generators. Each authentication token generator must have a unique valuetype element. The following example displays an example of a generator for an X.509 protection token:
application.securityoutboundbindingconfig.tokengenerator_0.name=gen_signtgen
application.securityoutboundbindingconfig.tokengenerator_0.classname=com.ibm.ws.wssecurity.wssapi.token
.impl.CommonTokenGenerator
application.securityoutboundbindingconfig.tokengenerator_0.valuetype.uri=
application.securityoutboundbindingconfig.tokengenerator_0.valuetype.localname=http://docs.oasis-open.org
/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.classname=com.ibm.websphere.wssecurity
.callbackhandler.X509GenerateCallbackHandler
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.key.alias=soaprequester
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.key.keypass={xor}PDM2OjEr
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.key.name=CN=SOAPRequester, 
OU=TRL, O=IBM, ST=Kanagawa, C=JP
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.keystore.path=${USER_INSTALL_ROOT}
/etc/ws-security/samples/dsig-sender.ks
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.keystore.storepass={xor}PDM2OjEr
application.securityoutboundbindingconfig.tokengenerator_0.callbackhandler.keystore.type=JKS
application.securityoutboundbindingconfig.tokengenerator_0.jaasconfig.configname=system.wss.generate.x509
The following example displays a generator for a username authentication token:
application.securityoutboundbindingconfig.tokengenerator_1.name=gen_usernametoken
application.securityoutboundbindingconfig.tokengenerator_1.classname=com.ibm.ws.wssecurity
.wssapi.token.impl.CommonTokenGenerator
application.securityoutboundbindingconfig.tokengenerator_1.valuetype.uri=
application.securityoutboundbindingconfig.tokengenerator_1.valuetype.localname=http://docs
.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken
application.securityoutboundbindingconfig.tokengenerator_1.callbackhandler.classname=com.ibm
.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHandler
application.securityoutboundbindingconfig.tokengenerator_1.callbackhandler.basicAuth.userid=user1
application.securityoutboundbindingconfig.tokengenerator_1.callbackhandler.basicAuth.password=myPassword
application.securityoutboundbindingconfig.tokengenerator_1.securityTokenReference.reference=request:uname_token
application.securityoutboundbindingconfig.tokengenerator_1.jaasconfig.configname=system.wss.generate.unt
tokenconsumer element
In the default bindings, the tokenconsumer elements that the signinginfo or encryptioninfo elements do not reference are authentication token consumers. Each authentication token consumer must have a unique valuetype element. The following example displays the format for a set of tokenconsumer elements:
application.securityinboundbindingconfig.tokenconsumer_0.name=con_unametoken
application.securityinboundbindingconfig.tokenconsumer_0.classname=com.ibm.ws.wssecurity.wssapi
.token.impl.CommonTokenConsumer
application.securityinboundbindingconfig.tokenconsumer_0.valuetype.localname=http://docs.oasis-open.org
/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken
application.securityinboundbindingconfig.tokenconsumer_0.valuetype.uri=
application.securityinboundbindingconfig.tokenconsumer_0.callbackhandler.classname=com.ibm.websphere
.wssecurity.callbackhandler.UNTConsumeCallbackHandler
application.securityinboundbindingconfig.tokenconsumer_0.jaasconfig.configname=system.wss.consume.unt
application.securityinboundbindingconfig.tokenconsumer_0.securitytokenreference.reference=request:uname_token
actor element
Defines the actor uniform resource identifier (URI) to be included in the WSSecurity headers of a generated message, as displayed by the following example:
application.securityinboundbindingconfig.actor=http://myActor.com
application.securityoutboundbindingconfig.actor=http://myActor.com
certstorelist element
Defines certificate store configurations and signing information, as displayed by the following example:
application.securityinboundbindingconfig.certstorelist.collectioncertstores_0
.name=DigSigCertStore
application.securityinboundbindingconfig.certstorelist.collectioncertstores_0
.provider=IBMCertPath
application.securityinboundbindingconfig.certstorelist.collectioncertstores_0
.x509certificates_0.path=${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer
keyinfo element
Defines key information for signing and encryption configurations, as displayed by the following example:
application.securityinboundbindingconfig.keyinfo_0.classname=com.ibm.ws.wssecurity.wssapi
.CommonContentConsumer
application.securityinboundbindingconfig.keyinfo_0.name=con_signkeyinfo
application.securityinboundbindingconfig.keyinfo_0.tokenreference.reference=con_tcon
application.securityinboundbindingconfig.keyinfo_0.type=STRREF
trustanchor property
Defines configuration information used to validate the trust of the signer certificate, as displayed by the following example:
application.securityinboundbindingconfig.trustanchor_0.keystore.path=${USER_INSTALL_ROOT}
/etc/ws-security/samples/dsig-receiver.ks
application.securityinboundbindingconfig.trustanchor_0.keystore.storepass={xor}LDotKTot
application.securityinboundbindingconfig.trustanchor_0.keystore.type=JKS
application.securityinboundbindingconfig.trustanchor_0.name=DigSigTrustAnchor
timestampexpires element
Defines an expiration date for the configuration, as displayed by the following example:
application.securityoutboundbindingconfig.timestampexpires.expires=5
application.securityinboundbindingconfig.caller_X.order
Order for a caller when using wsadmin scripts, where X is the unique string that identifies the instance of the caller:
-attributes [[application.securityinboundbindingconfig.caller_0.order 2]]
setPolicyType and setBinding command examples

Use the previous reference information with the setPolicyType and setBinding commands to modify the policy and binding configuration data.

The administrative console command assistance provides incorrect Jython syntax for the setPolicyType command. The XPath expression for the response message part protection of the Username WSSecurity policy set contains single quotes (') within each XPath property value, which Jython does not support. To fix the command from the administrative console command assistance, add a backslash character (\) before each single quote to escape the single quote.
The following example uses the setBinding command to set the enabled and provides properties for the myCustomSecurityPS custom policy set, which contains a ReliableMessaging policy:
AdminTask.setBinding('[-bindingLocation "" -bindingName cellWideBinding2 -policyType
 WSSecurity
 -attributes [[application.securityinboundbindingconfig.caller_0.order 2][inResponsewithSSL:configAlias 
NodeDefaultSSLSettings]
[inResponsewithSSL:config properties_directory/ssl.client.props]
[outAsyncResponsewithSSL:configFile properties_directory/ssl.client.props]
[outAsyncResponsewithSSL:configAlias NodeDefaultSSLSetings]
[outRequestwithSSL:configFile properties_directory/ssl.client.props]
[outRequestwithSSL:configAlias NodeDefaultSSLSettings]]]')
The following setPolicyType command enables the WSSecurity policy and creates a signature protection assertion:
AdminTask.setPolicyType('-policySet myPolicySet -policyType WSSecurity -attributes 
"[[enabled true][provides 
Some_amount_of_security][SignatureProtection.request:app_signparts.SignedElements.XPath_0 
SignatureProtectionV2]]"')
The following setBinding command specifies key information for a server-specific binding:
AdminTask.setBinding('-policyType WSSecurity -bindingLocation "[[server server1][node 
node01]]" 
-attributes "[[application.securityinboundbindingconfig.keyinfo_0.name dec_server_keyinfo]
[application.securityinboundbindingconfig.keyinfo_0.classname 
com.ibm.ws.wssecurity.wssapi.CommonContentGenerator]
[application.securityinboundbindingconfig.keyinfo_0.type STRREF]]"')
The following setBinding command specifies key information for an attachment-specific binding:
AdminTask.setBinding('-policyType WSSecurity -bindingLocation "[[application PolicySet]
[attachmentId 999]]" 
-attributes "[[application.securityinboundbindingconfig.keyinfo_0.name dec_app_keyinfo]
[application.securityinboundbindingconfig.keyinfo_0.classname 
com.ibm.ws.wssecurity.wssapi.CommonContentGenerator]
[application.securityinboundbindingconfig.keyinfo_0.type STRREF]]" -attachmentType application 
 -bindingName myBindingName')
The following setBinding command specifies trust anchor information for a cell-wide binding:
AdminTask.setBinding('-policyType WSSecurity -bindingLocation "" -attributes 
"[application.securityinboundbindingconfig.trustanchor_0.name DigSigTrustAnchor2]"')
Related:

Web Services Security default policy sets
Configure application and system policy sets for web services
Configure the WS-Security policy
Use High Performance Extensible Logging to troubleshoot applications
PolicySetManagement
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss