This chapter provides additional information about WSIT security features in NetBeans Integrated Development Environment (“the IDE”).
This chapter covers the following topics:
The security mechanism that you need to select reflects the commonly available infrastructure between your organization and another organization with which you will be communicating. The following list provides some common communication issues that need to be addressed using security mechanisms:
Asymmetric binding is used for message protection. This binding has two binding specific token properties: the initiator token and the recipient token. If the message pattern requires multiple messages, this binding defines that the initiator token is used for the message signature from initiator to the recipient, and for encryption from recipient to initiator. The recipient token is used for encryption from initiator to recipient, and for the message signature from recipient to initiator.
Some organizations have a Kerberos infrastructure, while other organizations have a PKI infrastructure (asymmetric binding). WS-Trust allows two communicating parties having different security infrastructure to communicate securely with one another. In this scenario, the client authenticates with a third party (STS) using its infrastructure. The STS returns a (digitally-signed) SAML token containing authorization and authentication information regarding the client, along with a key. The client then simply relays the token to the server and uses the STS-supplied key to ensure integrity and confidentiality of the messages sent to the server.
Kerberos is not supported in this release.
Symmetric binding is used for message protection. This binding has two binding specific token properties: encryption token and signature token. If the message pattern requires multiple messages, this binding defines that the encryption token used from initiator to recipient is also used from recipient to initiator. Similarly, the signature token used from initiator to recipient is also used from recipient to initiator.
In some cases, the client does not have its own certificates. In this case, the client can choose a security mechanism that makes use of symmetric binding and could use a Username token as a signed supporting token for authentication with the server. The symmetric binding in this case serves the purpose of integrity and confidentiality protection.
In the absence of a notion of secure session, the client would have to reauthenticate with the server upon every request. In this situation, if the client is sending a Username token, the client will be asked for its username and password on each request, or, if the client is sending a certificate, the validity of the certificate has to be established with every request. This is expensive! Enable Secure Conversation to remove the requirement for re-authentication.
The use of the same session key (Secure Conversation) for repeated message exchanges is sometimes considered a risk. To reduce that risk, enable Require Derived Keys.
RSA Signatures (signatures with public-private keys) is more expensive than Symmetric Key signatures. Use the Secure Conversation option to enable Symmetric Key signatures.
Enabling WSS 1.1 enables an encrypted key generated by the client to be reused by the server in the response to the client. This saves the time otherwise required to create a Symmetric Key, encrypt it with the client public key (which is also an expensive RSA operation), and transmit the encrypted key in the message (it occupies markup and requires Base64 operations).
When a web service or a web service client are configured for WSIT features, this information is saved in WSIT Configuration files. The following sections discuss the WSIT configuration files for the service and for the client:
WSIT features are configured on a web service in the following way:
Right-click the web service in NetBeans IDE.
Select Edit Web Service Attributes.
Select and/or configure the appropriate WSIT features on the WSIT Configuration tab for the web service. Many of the WSIT features are discussed in Chapter 7, Using WSIT Security.
Select OK to close the dialog.
Run the web application by right-clicking the project node and selecting Run Project.
The service-side WSIT Configuration file that is used when the web service is deployed can be viewed by expanding the Web Pages->WEB-INF elements of the application in the tree, and then double-clicking the wsit-package.service.xml file to open it in the editor.
For the example application Example: Username Authentication with Symmetric Keys (UA), the WSIT configuration file for the service is named wsit-org.me.calculator.CalculatorWS.xml, and looks like this:
<?xml version="1.0" encoding="UTF-8"?> <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" name="CalculatorWSService" targetNamespace="http://calculator.me.org/" xmlns:tns="http://calculator.me.org/" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsu= "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsaws="http://www.w3.org/2005/08/addressing" xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy" xmlns:sc="http://schemas.sun.com/2006/03/wss/server" xmlns:wspp="http://java.sun.com/xml/ns/wsit/policy" xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy" > <message name="add"/> <message name="addResponse"/> <portType name="CalculatorWS"> <wsdl:operation name="add"> <wsdl:input message="tns:add"/> <wsdl:output message="tns:addResponse"/> </wsdl:operation> </portType> <binding name="CalculatorWSPortBinding" type="tns:CalculatorWS"> <wsp:PolicyReference URI="#CalculatorWSPortBindingPolicy"/> <wsdl:operation name="add"> <wsdl:input> <wsp:PolicyReference URI="#CalculatorWSPortBinding_add_Input_Policy"/> </wsdl:input> <wsdl:output> <wsp:PolicyReference URI="#CalculatorWSPortBinding_add_Output_Policy"/> </wsdl:output> </wsdl:operation> </binding> <service name="CalculatorWSService"> <wsdl:port name="CalculatorWSPort" binding="tns:CalculatorWSPortBinding"/> </service> <wsp:Policy wsu:Id="CalculatorWSPortBindingPolicy"> <wsp:ExactlyOne> <wsp:All> <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/> <sp:SymmetricBinding> <wsp:Policy> <sp:ProtectionToken> <wsp:Policy> <sp:X509Token sp:IncludeToken= "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never"> <wsp:Policy> <sp:WssX509V3Token10/> </wsp:Policy> </sp:X509Token> </wsp:Policy> </sp:ProtectionToken> <sp:Layout> <wsp:Policy> <sp:Strict/> </wsp:Policy> </sp:Layout> <sp:IncludeTimestamp/> <sp:OnlySignEntireHeadersAndBody/> <sp:AlgorithmSuite> <wsp:Policy> <sp:Basic128/> </wsp:Policy> </sp:AlgorithmSuite> </wsp:Policy> </sp:SymmetricBinding> <sp:Wss11> <wsp:Policy> <sp:MustSupportRefKeyIdentifier/> <sp:MustSupportRefIssuerSerial/> <sp:MustSupportRefThumbprint/> <sp:MustSupportRefEncryptedKey/> </wsp:Policy> </sp:Wss11> <sp:SignedSupportingTokens> <wsp:Policy> <sp:UsernameToken sp:IncludeToken= "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <sp:WssUsernameToken10/> </wsp:Policy> </sp:UsernameToken> </wsp:Policy> </sp:SignedSupportingTokens> <sc:KeyStore wspp:visibility="private" alias="xws-security-server" storepass="changeit" type="JKS" location="C:\Sun\glassfish\domains\domain1\config\keystore.jks"/> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> <wsp:Policy wsu:Id="CalculatorWSPortBinding_add_Input_Policy"> <wsp:ExactlyOne> <wsp:All> <sp:EncryptedParts> <sp:Body/> </sp:EncryptedParts> <sp:SignedParts> <sp:Body/> <sp:Header Name="To" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="From" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="FaultTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="ReplyTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="MessageID" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="RelatesTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="Action" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="AckRequested" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> <sp:Header Name="SequenceAcknowledgement" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> <sp:Header Name="Sequence" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> </sp:SignedParts> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> <wsp:Policy wsu:Id="CalculatorWSPortBinding_add_Output_Policy"> <wsp:ExactlyOne> <wsp:All> <sp:EncryptedParts> <sp:Body/> </sp:EncryptedParts> <sp:SignedParts> <sp:Body/> <sp:Header Name="To" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="From" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="FaultTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="ReplyTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="MessageID" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="RelatesTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="Action" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="AckRequested" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> <sp:Header Name="SequenceAcknowledgement" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> <sp:Header Name="Sequence" Namespace="http://schemas.xmlsoap.org/ws/2005/02/rm"/> </sp:SignedParts> </wsp:All> </wsp:ExactlyOne > </wsp:Policy> </definitions>
WSIT features are configured on the client in the following way:
Expand the Web Service Reference node for the web service client in NetBeans IDE.
Select Edit Web Service Attributes.
Select and/or configure the appropriate WSIT features on the WSIT Configuration tab for the web service client. Many of the WSIT features are discussed in Chapter 7, Using WSIT Security.
Select OK to close the dialog.
Run the web service client by right-clicking the project node and selecting Run Project.
The WSIT Configuration information can be viewed by expanding Source Packages->META-INF in NetBeans IDE for the client project. This directory contains two files: serviceService.xml and wsit-client.xml.
The serviceService.xml file is an XML file that must conform to the WSDL specification. The WSIT configuration is written to this file. For the example application Example: Username Authentication with Symmetric Keys (UA), the WSIT configuration file for the client is named CalculatorWSService.xml, and looks like this:
<?xml version="1.0" encoding="UTF-8"?> <!-- Published by JAX-WS RI at http://jax-ws.dev.java.net. RI’s version is JAX-WS RI 2.1.2-hudson-132-M1. --> <!-- Generated by JAX-WS RI at http://jax-ws.dev.java.net. RI’s version is JAX-WS RI 2.1.2-hudson-132-M1. --> <definitions xmlns:wsu= "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://calculator.me.org/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://calculator.me.org/" name="CalculatorWSService" xmlns:tc="http://schemas.sun.com/ws/2006/05/trust/client" xmlns:wspp="http://java.sun.com/xml/ns/wsit/policy" xmlns:sc="http://schemas.sun.com/2006/03/wss/client"> <types> <xsd:schema> <xsd:import namespace="http://calculator.me.org/" schemaLocation= "http://localhost:8080/CalculatorApplication/CalculatorWSService?xsd=1"> </xsd:import> </xsd:schema> </types> <message name="add"> <part name="parameters" element="tns:add"></part> </message> <message name="addResponse"> <part name="parameters" element="tns:addResponse"></part> </message> <portType name="CalculatorWS"> <operation name="add"> <input message="tns:add"></input> <output message="tns:addResponse"></output> </operation> </portType> <binding name="CalculatorWSPortBinding" type="tns:CalculatorWS"> <wsp:PolicyReference URI="#CalculatorWSPortBindingPolicy"/> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"> </soap:binding> <operation name="add"> <soap:operation soapAction=""></soap:operation> <input> <soap:body use="literal"></soap:body> </input> <output> <soap:body use="literal"></soap:body> </output> </operation> </binding> <service name="CalculatorWSService"> <port name="CalculatorWSPort" binding="tns:CalculatorWSPortBinding"> <soap:address location="http://localhost:8080/CalculatorApplication/CalculatorWSService"> </soap:address> </port> </service> <wsp:Policy wsu:Id="CalculatorWSPortBindingPolicy"> <wsp:ExactlyOne> <wsp:All> <tc:PreconfiguredSTS wspp:visibility="private"/> <sc:CallbackHandlerConfiguration wspp:visibility="private"> <sc:CallbackHandler default="wsitUser" name="usernameHandler"/> <sc:CallbackHandler default="changeit" name="passwordHandler"/> </sc:CallbackHandlerConfiguration> <sc:KeyStore wspp:visibility="private" storepass="changeit" type="JKS" location="C:\Sun\glassfish\domains\domain1\config\keystore.jks"/> <sc:TrustStore wspp:visibility="private" storepass="changeit" type="JKS" location="C:\Sun\glassfish\domains\domain1\config\cacerts.jks" peeralias="xws-security-server"/> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> </definitions>
The wsit-client.xml file imports the serviceService.xml file. For the example shown about, the wsit-client.xml file looks like this:
<?xml version="1.0" encoding="UTF-8"?> <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" name="mainclientconfig"> <import location="CalculatorWSService.xml" namespace="http://calculator.me.org/"/> </definitions>
The following fields shown in Table 8–1 are used to configure different security policies. Not every option is available for every mechanism, but many of the policies include the same configuration options, so they are grouped here for the purposes of defining them in one central location.
Table 8–1 Security Mechanism Configuration Options
Option |
Description |
---|---|
Algorithm Suite |
This attribute specifies the algorithm suite required for performing cryptographic operations with symmetric or asymmetric key-based security tokens. An algorithm suite specifies actual algorithms and allowed key lengths. A mechanism alternative will define what algorithms are used and how they are used. The value of this attribute is typically referenced by a security binding and is used to specify the algorithms used for all cryptographic operations performed under the security binding. The default value is Basic 128 bit. Some of the algorithm suite settings require that Unlimited StrengthEncryption be configured in the Java Runtime Environment (JRE), particularly the algorithm suites that use 256 bit encryption. Instructions for downloading and configuring unlimited strength encryption can be found at the following URLS: http://java.sun.com/products/jce/javase.html http://java.sun.com/javase/downloads/index_jdk5.jsp#docs Read the OASIS specification WS-Security Policy section on Security Binding Properties for more description of the components for each of these algorithm suites. A link to this document can be found at https://wsit.dev.java.net/. |
Encrypt Before Signing |
If selected, specifies that the order of message protection is to encrypt the SOAP content, then sign the entire SOAP body. Encryption key and signing key must be derived from the same source key. If not selected, the default behavior is Sign Before Encrypt. |
Encrypt Signature |
Specifies whether the signature must be encrypted. If selected, the primary signature must be encrypted and any signature confirmation elements must also be encrypted. If not selected (the default), the primary signature must not be encrypted and any signature confirmation elements must not be encrypted. |
Establish Secure Session (Secure Conversation) |
Secure Conversation enables a consumer and provider to establish a shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use (possibly derived) session keys that increase the overall security while reducing the security processing overhead for each message. In the absence of a notion of secure session, the client would have to reauthenticate with the server upon every request. In this situation, if the client is sending a Username token, it has to authenticate on every request, or, if the client is sending a certificate, the validity of the certificate has to be established on every request. This is expensive. Enable Secure Conversation to get over this requirement for re-authentication. When this option and Require Derived Keys are both enabled, a derived key will be used. If not, the original session key will be used. Note on Secure Conversation with Reliable Message Delivery: Reliable Messaging can be used independently of the security mechanisms; however, when Reliable Messaging (RM) is used with a security mechanism, it requires the use of Secure Conversation, which will be automatically configured for a security mechanism when Reliable Messaging is selected before the security mechanism is selected. If Secure Conversation is selected for a security mechanism and the Reliable Messaging option was not selected before the security mechanism was specified, Reliable Messaging will need to be manually selected in order for Secure Conversation to work. Reliable messaging, as well as the Advanced configuration options and Deliver Messages in Exact Order feature, is discussed in Chapter 6, Using Reliable Messaging. |
Issuer Address |
This optional element specifies the address of the issuer (STS) that will accept the security token that is presented in the message. This element’s type is an endpoint reference. An STS contains a set of interfaces to be used for the issuance, exchange, and validation of security tokens. An example that creates and uses an STS can be found at Example: STS Issued Token (STS). For example, for JAX-WS services, the Issuer Address is: http://localhost:8080/jaxws-sts/sts For WCF STS, the Issuer Address is: http://131.107.72.15/Security_Federation_SecurityTokenService_Indigo/ Symmetric.svc/Scenario_5_IssuedTokenForCertificate_MutualCertificate11 |
Issuer Metadata Address |
Specifies the address from which to retrieve the issuer metadata. They should be just the URLs. For example, for JAX-WS services, the Issuer Metadata Address is as follows: http://localhost:8080/jaxws-sts/sts For WCF STS, the Issuer Metadata Address is as follows: http://131.107.72.15/Security_Federation_SecurityTokenService_Indigo/ Symmetric.svc For more information, read Configuring A Secure Token Service (STS). |
Key Type |
Applicable for Issued Token mechanisms only. The type of key the service provider desires. The choices are public key or symmetric key. Symmetric key cryptography relies on a shared secret and is usually faster than public key cryptography. Public key cryptography relies on a key that is made public to all and is primarily used for encryption but can be used for verifying signatures. |
Key Size |
Applicable for Issued Token mechanisms only. The size of the symmetric key requested, specified in number of bits. This is a request, and, as such, the requested security token is not obligated to use the requested key size, nor is the STS obligated to issue a token with the same key size. That said, the recipient should try to use a key at least as strong as the specified value if possible. The information is provided as an indication of the desired strength of the security. Valid choices include 128, 192, and 256. |
Require Client Certificate |
Select this option to require that a client certificate be provided to the server for verification. If you are using a security mechanism with SSL, a client certificate will be required by the server both during its initial handshake and again during verification. |
Require Derived Keys Require Derived Keys for: Issued Token, Secure Session, X509 Token |
A derived key is a cryptographic key created from a password or other user data. Derived keys allow applications to create session keys as needed, eliminating the need to store a particular key. The use of the same session key (for example, when using Secure Conversation) for repeated message exchanges is sometimes considered a risk. To reduce that risk, enable Require Derived Keys. |
Require Signature Confirmation |
When the WSS Version is 1.1, select this option to reduce the risk of attacks because signature confirmation indicates that the responder has processed the signature in the request. For more information, read section 8.5, Signature Confirmation, of the Web Services Security: SOAP Message Security 1.1 specification at http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf. |
SAML Version |
Specifies which version of the SAML token should be used. The SAML Version is something the CallbackHandler has to verify, not the security runtime. SAML tokens are defined in WSS: SAML Token Profile documents, available from http://www.oasis-open.org/specs/index.php. For an example that uses SAML Callbacks, refer to Example: SAML Authorization over SSL (SA). |
Security Header Layout |
Specifies which layout rules to apply when adding items to the security header. The options are:
Examples of the layout rules are described in the OASIS WS-SecurityPolicy specification, a link to which can be found at https://wsit.dev.java.net/. |
Supporting Token |
Specifies the type of supporting token to be used. Supporting Tokens are included in the security header and may sign and/or encrypt additional message parts. Valid options for supporting tokens include X.509 tokens, Username tokens, SAML tokens, or an Issued Token from an STS. For more information on these options, read Supporting Token Options. |
Token Type |
The type of SAML token the service provider requires, for example, urn:oasis:names:tc:SAML1.0:assertion.Choices are 1.0, 1.1, or 2.0. |
WSS Version |
Specifies which version of the Web Services Security specification should be followed, 1.0 or 1.1. These specifications can be viewed from http://www.oasis-open.org/specs/index.php. Enabling WSS 1.1 enables an encrypted key generated by the client to be reused by the Server in the response to the client. This saves the time otherwise required to create a Symmetric Key during the course of response, encrypt it with the client public key (which is also an expensive RSA operation), and transmit the encrypted key in the message (it occupies markup and requires Base64 operations). Enabling WSS 1.1 also enables encrypted headers. |