+

Search Tips   |   Advanced Search

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 you are using the most recent version of wsadmin.sh. 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 wsadmin.sh. For example, the commands do not run on a Version 6.1.0.x node.

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

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.

This topic references one or more of the application server log files. As a recommended alternative, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

For transitioning users: In WAS v7 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 Version 7.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, WebSphere Application Server supports Version 7.0 and Version 6.1 bindings. General cell-level bindings are specific to Version 7.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

There are an extensive number of combinations of settings that are 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

Use the getPolicyType command to review a properties object with the properties configured in the 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:


WSSecurity binding properties

Use the getBinding command to review a properties object with the properties configured in the current WSSecurity binding configuration. We can also use the console to configure your WSSecurity bindings. Use the information center topics for configuring WSSecurity bindings with 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.

The following examples display several sets of properties to configure for the 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

Specifies the order for a caller when using wsadmin scripts, where X is the unique string identifying 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 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 console command assistance, add a backslash character (\) before each single quote to escape the single quote.gotcha

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:

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:


Related concepts

  • Web Services Security default policy sets


    Related tasks

  • Configure application and system policy sets for web services
  • Configure the WS-Security policy
  • Use High Performance Extensible Logging to troubleshoot applications

  • PolicySetManagement (AdminTask)
    http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss