Network Deployment (Distributed operating systems), v8.0 > Reference > Commands (wsadmin scripting)
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 you use 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 v6.1.0.x node.
Use the following commands and parameters 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 your 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.
New feature: Beginning in WAS v8.0 you can configure the server to use the HPEL log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files or native z/OS logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.New feature:
For transitioning users: In WebSphere Application Server 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, you 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, you can configure one or more general service provider bindings and one or more general service client bindings. After we have configured general bindings, you can specify which of these bindings is the global default binding. You can also optionally specify general binding that are used as the default for an application server or a security domain. trns
To support a mixed-cell environment, WebSphere Application Server 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.NameandSignatureProtection.response:int_body.SignedParts.Header_0.NamespaceThere are an extensive number of combinations of settings that are available to secure your 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 that are 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
SupportTokens
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 = trueAdditionally, 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:SupportingTokensThe SupportingTokens assertion returns the following property name and value pairs. The nested wsp:Policy layers are not displayed in the returned property.
SupportTokens.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=tokenv1The 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 that are configured in your current WSSecurity binding configuration. We can also use the admin console to configure your WSSecurity bindings. Use the information center topics for configuring WSSecurity bindings with admin 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 that are associated with the main WS-Security policy. Attributes that begin with bootstrap represent bindings that are 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.uriAdditionally, 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 your 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 your 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
Use this property to 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
Use this property to 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.x509The 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 your policy and binding configuration data. The admin 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 admin 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]"')
Web Services Security default policy sets
Configure application and system policy sets for web services using wsadmin.sh
Configure the WS-Security policy
Use HPEL to troubleshoot applications
Related
PolicySetManagement command group
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss