Home

Web Service

1. CalculatorWSPortBinding 2 Optimize Transfer Of Binary Data MTOM Figure 4 2 Enabling MTOM CREATING A CLIENT TO CONSUME A WSIT ENABLED WEB SERVICE 39 This setting configures the web service to optimize messages that it trans mits and to decode optimized messages that it receives Deploying and Testing a Web Service Now that you have configured the web service to use message optimization you can deploy and test it To deploy and test the web service perform the following steps 1 Right click the project node select Properties and select Run 2 Type CalculatorWSService wsd1 in the Relative URL field and click OK 3 Right click the project node and choose Run Project The IDE starts the web container builds the application and displays the WSDL file page in your browser You have now successfully tested the deployment of a web service with message optimization enabled Creating a Clientto Consume a WSIF enabled Web Service Now that you have built and tested a web service that uses the WSIT Message Optimization technology you can create a client that accesses and consumes that web service The client will use the web service s WSDL to create the function ality necessary to satisfy the interoperability requirements of the web service To create a client to access and consume the web service perform the following steps 1 Choose File New Project select Web Application from the Web category
2. The following illustrates how the xsi type is preserved across an unmarshal marshal operation e A value of type uint is marshalled by WCF serialization mechanism as lt objvalue xsi type xs unsignedShort gt e JAXB 2 0 unmarshaller unmarshals the value as an instance of Unsigned Short and assigns it to parameter objvalue e The objvalue is marshalled back by JAXB 2 0 marshaller with an XSi type of xs int lt objvalue xsi type xs unsignedShort gt Guideline Use mapSimpleTypedef customization where roundtripping of XML Schema types in Table 9 1 are used in xsi type However it is preferable to avoid the use of CLR types listed in Table 9 1 since they are specific to NET platform DEVELOPING A MICROSOFT NET CLIENT 181 The syntax of the mapSimp leTypeDef customization is shown below lt jxb bindings version 2 0 xmIns jxb http java sun com xml ns jaxb xmIns xs http www w3 org 2001 XMLSchema gt lt jaxb bindings schemaLocation schema importedby wcfsvcwsd1 node xs schema gt lt jaxb globalBindings mapSimpleTypeDef true gt lt jaxb bindings gt Developing a Microsoft NET Client This section describes how to develop a NET client that uses data binding Do the following steps to generate a Microsoft NET client from a Java web ser vice WSDL file 1 Generate WCF web service client artifacts using the svcuti1 exe tool svcutil exe lt java web service wsd1 gt svcutil
3. Figure 6 6 Client side Certificate Configuration Dialog 9 Click OK to close the dialog 83 84 USING WSIT SECURITY Configuring Validators A validator is an optional set of classes used to check the validity of a token a certificate a timestamp or a username and password Applications that run under a GlassFish 9 1 container do not need to configure Callback Handlers and Validators when using the IDE with WSIT enabled This is because the container handles the callbacks and validation You only need to make sure that the certificates are available at locations that GlassFish requires and or create authorized users using the Admin Console described in Adding Users to GlassFish page 72 Validators are always optional because there are defaults in the runtime regard less of the container and regardless of whether the application is a JSR 109 or a non JSR 109 deployment For non JSR 109 deployment you only need to specify a validator when you want to override the default validators For JSR 109 deployments there is no point in specifying an overriding validator as these will be overridden back to the defaults by GlassFish thus the Validators button is not available when the selected web service is a JSR 109 compliant application To set the validator configuration options for a non JSR 109 compliant applica tion such as a J2SE client perform the following steps 1 Right click the web service and select Edit Web
4. Java code fragment XmlType propOrder name age oc public class OcPerson XmlElement required true public String name public int age WEB SERVICE START FROM JAVA 173 Define open content Xm1AnyElement public List lt Object gt oc Schema fragment lt xs complexType name ocPerson gt lt xsS Sequence gt lt xs element name name type xs string gt lt xs element name age type xs int gt lt xSiany minOccurs 0 maxOccurs unbounded gt lt xsS Sequence gt lt xs complexType gt NET auto generated code from schema public class ocPerson private String name private int age private System Xm1 XmlElement anyField lt public String name public int age public System Xm1 Xm lElement Any get return this anyField set this anyField value Example Open content using Xm1AnyAttribute Java code fragment Xm1lType propOrder name age public class OcPerson public String name public int age 174 DATA CONTRACTS Define open content xm1AnyAttribute public java util Map oc Schema fragment lt xs complexType name ocPerson gt lt xsS Sequence gt lt xs element name name type xs string gt lt xs element name age type xs int gt lt xs Sequence gt lt xs anyAttribute gt lt xs complexType gt NET auto gener
5. 2 Create the CalculatorApplication example by following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 EXAMPLE SAML AUTHORIZATION OVER SSL SA b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet 3 Expand CalculatorApplication Web Services then right click the node for the web service CalculatorWS and select Edit Web Service Attributes 4 Unselect the Reliable Messaging option if it is selected 5 Select Secure Service 6 From the drop down list for Security Mechanism select SAML Authori zation over SSL 7 Click the Keystore button to provide your keystore with the alias identify ing the service certificate and private key To do this click the Load Aliases button and select xws security server Click OK to close the dialog 8 For this example the Truststore information that you need is specified by default so there is no need to change these settings 9 Click OK to exit the WSIT Configuration editor A new file is added to the project To view the WSIT configuration file expand Web Pages WEB INF then double click the file wsit org me calculator CalculatorWS xm1 This file contains the sc Key Store and sc Truststore elements 10 To require the service to use SSL you have to specify the security require ments in
6. The Java WSIT Tutonal For Web Services Interoperability Technologies Milestone Release 6 August 24 2007 Copyright 2007 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 U S A All rights reserved U S Government Rights Commercial software Government users are subject to the Sun Microsystems Inc standard license agreement and applicable provisions of the FAR and its supple ments This distribution may include materials developed by third parties Sun Sun Microsystems the Sun logo Java J2EE JavaServer Pages Enterprise JavaBeans Java Naming and Directory Interface EJB JSP J2EE J2SE and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems Inc in the U S and other countries Unless otherwise licensed software code in all technical materials herein including articles FAQs sam ples is provided under this License Products covered by and information contained in this service manual are controlled by U S Export Con trol laws and may be subject to the export or import laws in other countries Nuclear missile chemical biological weapons or nuclear maritime end uses or end users whether direct or indirect are strictly pro hibited Export or reexport to countries subject to U S embargo or to entities identified on U S export exclusion lists including but not limited to the denied persons and specially designated nationals lists is strictly prohibit
7. 10 Right click on the CalculatorWSServletClient node and select Run Project Example Mutual C ertific ates Sec unity MCS The section includes the following topics e Securing the Example Service Application MCS page 101 e Securing the Example Web Service Client Application MCS page 102 EXAMPLE MUTUAL CERTIFICATES SECURITY MCS Securing the Example Service Application MCS The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing security to both the web service and to the web service client For this example the security mechanism of Mutual Certificates Security page 62 is used to secure the application To add security to the service part of the example follow these steps 1 If you haven t already completed these steps complete them now a Update the GlassFish keystore and truststore files as described in Updat ing GlassFish Certificates page 74 2 Create the CalculatorApplication example by following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet 3 Expand CalculatorApplication Web Services then right click the node for the web service CalculatorWS
8. gt lt xS complexType name purchaseOrder gt lt xs element name items minOccurs 0 gt lt xs simpleType gt lt xs list itemType xs int gt lt xs simpleType gt lt xs element gt lt xs complexType gt XML serialization lt po gt lt items gt 1 2 3 lt items gt lt po gt NET auto generated code from schema partial class purchaseOrder private string itemsField public string items get return this itemsField set this itemsField value 164 DATA CONTRACTS Arrays Example Single and multidimensional Arrays Java code fragment public class FamilyTree public Person persons public Person family NET auto generated code from schema public partial class familyTree private person persons private person families public person persons get return this membersField set this membersField value public person families get return this familiesField set this familiesField value Fields Properties The following guidelines apply to mapping of Javabean properties and Java fields but for brevity Java fields are used Xmibement The Xm1Element annotation maps a property field to an XML element This is also the default mapping in the absence of any other JAXB 2 0 annotations The annotation parameters in XmlElement can be used to specify whether the ele ment is optional or requir
9. 33 34 BOOTSTRAPPING AND CONFIGURATION description to generate code that can send SOAP messages to and receive SOAP messages from the web service endpoint Creating a Client from WSDL To create a web service client that can access and consume a web service pro vider you must obtain the information that defines the interoperability require ments of the web service provider Providers make this information available by means of WSDL files WSDL files may be made available in service registries or published on the Internet via a URL or both You can use a web browser or the Netbeans IDE to obtain WSDL files A WSDL file contains descriptions of the following e Network services The description includes the name of the service the location of the service and ways to communicate with the service that is what transport to use e Web services policies Policies express the capabilities requirements and general characteristics of a web service Web service providers use policies to specify policy information in a standardized way Policies convey con ditions on interactions between two web service endpoints Typically the provider of a web service exposes a policy to convey conditions under which it provides the service A requester a client might use the policy to decide whether or not to use the service Web Services Metadata Exchange WS MEX is the protocol for requesting and transferring the WSDL from the provider to the c
10. USING WSIT SECURITY and or encrypted include an XPath expression or a URI which indicates the version of XPath to use Specifying Security at the Operation Input Message or Output Message Level To specify security mechanisms at the level of the operation input message or output message perform the following steps 1 Right click the web service and select Web Service Attributes The Web Service Attributes editor is displayed 2 Select Secure Service 3 Select a security mechanism The following mechanisms do not support Input message level protection e Username Authentication with Symmetric Keys page 61 e Transport Security SSL page 62 e Message Authentication over SSL page 64 e SAML Authorization over SSL page 64 e SAML Sender Vouches with Certificates page 65 4 Expand the lt operation gt Operation node 5 Expand the Operation node It should look like Figure 6 7 SPECIFYING SECURITY AT THE OPERATION INPUT MESSAGE OR OUTPUT MESSAGE LEVEL 87 Calculatorws x add Operation add Transaction Not Supported 7 Input Message Authentication Token t4 M Signed I Endorsing Message Parts a Output Message Message Parts Figure 6 7 Web Service Attributes Editor Page Operation Level 6 Expand the Operation section The section will be grayed out if Secure Service is not selected 7 Specify the followin
11. es META INF To view the WSDL file containing the WSIT security elements in the tree drill down from the project to Source Packages META INF and then double click on lt service gt Service wsdl Summary of Configuration Requirements The following sections summarize the options that need to be configured for each of the security mechanisms on both the service and client side The config uration requirements for the client are dependent upon which security mecha nism is specified on the server side The following sections assume that you have completed the steps described in Configuring SSL and Authorized Users page 68 for creating an authorized user and setting up your system for SSL and Updating GlassFish Certificates page 74 for upgrading the GlassFish certificates if the security mechanism you are using requires these things Summary of Service Side Configuration Requirements Table 6 1 summarizes the options that need to be configured for each of the security mechanisms Each of the columns is briefly discussed after the table Table 6 1 Summary of Service Side Configuration Requirements Mechanism Username Auth w Symmetric Keys SUMMARY OF SERVICE SIDE CONFIGURATION REQUIREMENTS Keystore Truststore User in GlassFish Mutual Certs YES no alias Transport Sec Message Auth over SSL User name Token Message Auth over SSL X 509 Token YES no alias SAML Auth
12. set this uriField value C code fragment purchaseOrder tmpU new purchaseOrder tmpU uri new System Uri Hello System UriKind Relative Example Xm1SchemaType and Xm1Serializer Java code fragment public class PurchaseOrder Xm1SchemaType Cname anyURI public java net URI uri NET auto generated code from schema Using svcutil exe serializer XmlJSerializer lt wsdl file gt public partial class purchaseOrder private string uriField public string uri get return this uriField set this uriField value C code fragment purchaseOrder tmpU new purchaseOrder tmpU uri mailto mailto mduerst ifi unizh ch Duration Guideline Use NET s System Xm1 Xm1Convert to generate a lexical representation of xs duration when the binding is to a type of System string javax xm datatype Duration maps to xs duration NET maps xs dura tion to a different datatype for DataContractSerializer and XmlSerializer e DataContractSerializer binds xs duration to NET Sys tem TimeSpan WEB SERVICE START FROM JAVA 153 e XmlSerializer binds xs duration to NET System string When xs duration is bound to NET System string the string value must be a lexical representation for xs duration NET provides utility Sys tem Xm1 Xm1Convert for this purpose Example Mapping xs duration using DataContactSerializer Java code fragment public cl
13. Download the sample kits from the following locations e https wsit dev java net source browse check out wsit wsit docs howto wsit enabled fromjava zip e https wsit dev java net source browse check out wsit wsit docs howto wsit enabled fromwsd1 zip e https wsit dev java net source browse check out wsit wsit docs howto csclient enabled fromjava zip e https wsit docs dev java net releases m6 wsittutorial zip Typographical Conventions Table 1 lists the typographical conventions used in this tutorial Table 1 Typographical Conventions Emphasis titles first occurrence of terms URLs code examples file names path names tool names monospace application names programming language keywords tag interface class method field names and properties italic monospace Variables in code file paths and URLs lt italic monospace gt User selected file path components Menu selections indicated with the right arrow character gt for example First Second should be interpreted as select the First menu then choose Sec ond from the First submenu Feedback Please send comments broken link reports errors suggestions and questions about this tutorial to the tutorial team at users wsit dev java net ABOUT THIS TUTORIAL l Intoduction This tutorial describes how to use the Web Services Interoperability Technolo gies WSIT a product of Sun Microsystems web services intero
14. MD5 1A 0E E9 69 7D DQ 80 AD 5C 85 47 91 EB 0D 11 B1 If the certificates were not successfully update your response will look something like this keytool error java lang Exception Alias lt wssip gt does not exist c Verify that the v3 certificate has been imported into the GlassFish key store To do this run the following keytool command 75 76 USING WSIT SECURITY lt JDK_HOME gt bin keytool list keystore keystore jks alias xws security server storepass changeit lt JDK_HOME gt bin keytool list keystore keystore jks alias xws security client storepass changeit If the certificates were successfully updated your response should look something like this xws security server Aug 20 2007 PrivateKeyEntry Certificate fingerprint MD5 E4 3 A9 02 3C B0 36 0C C1 48 6E 0E 3E 5C 5E 84 If your certificates were not successfully update your response will look more like this keytool error java lang Exception Alias lt xws security server gt does not exist NOTE The XWSS keystore s are sample keystores containing sample v3 certif icates These sample keystores can be used for development and testing of secu rity with WSIT technology Once an application is in production you should definitely use your own v3 certificates issued by a trusted authority In order to use WSIT security on GlassFish you will have to import your trusted stores into GlassFish s keystore and specify those certificates from N
15. Xm1Element name foo Example Mapping a field property using XmlElementRefs Java code fragment public class PurchaseOrder Xm1ElementRefs Xm1ElementRef name plane type PlaneType class Xm1ElementRef name auto type AutoType class public TransportType shipBy XmlRootElement name plane public class PlaneType extends TransportType XmlRootElement name auto 168 DATA CONTRACTS public class AutoType extends TransportType Xm1RootElement public class TransportType Schema fragment lt XML schema generated by wsgen gt lt xs complexType name purchaseOrder gt lt xs choice gt lt xs element ref plane gt lt xs element ref auto gt lt xs choice gt lt xs complexType gt lt XML global elements gt lt xs element name plane type autoType gt lt xs element name auto type planeType gt lt xs complexType name autoType gt lt content omitted details not relevant to example gt lt xs complexType gt lt xs complexType name planeType gt lt content omitted details not relevant to example gt lt xs complexType gt NET auto generated code from schema public partial class purchaseOrder private transportType itemField System Xm 1 Serialization XmlElementAttributeC auto typeof autoType Order 4 System Xm1 Serialization XmlElementAttributeC plane typeof p
16. e AddNumbersException java e custom schema xm e sun jaxws xml 128 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS e web xml e These files are standard in any Ant build environment Examples of these files are provided in the wsit enabled fromjava sample directory e build xml e build properties Web Service Implementation J ava File The sample files define a web service that takes two integers adds them and returns the result If one of the integers is negative an exception is thrown The starting point for developing a web service that uses the WSIT technologies is a Java class file annotated with the javax jws WebService annotation The WebService annotation defines the class as a web service endpoint The following file wsit enabled fromjava src fromjava serverAddNum bersImp1 java implements the web service interface package fromjava server import javax jws WebService import javax jws WebMethod WebService public class AddNumbersImp1 WebMethod action addNumbers public int addNumbers Cint numberl int number2 throws AddNumbersException if Cnumberl1 lt Q number2 lt Q throw new AddNumbersException Negative number cannot be added Numbers number1 number2 return number1 number2 Note To ensure interoperability with Windows Communication Foundation WCF clients you must specify the action element of webMethod in your end point implementation c
17. example POST Click OK to close this dialog g Check the Enable User Data Constraint box Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL monn a amp h Click the XML tab to view the resulting deployment descriptor addi tions Right click the CalculatorApplication node and select Run Project If the server presents its certificate slas accept this certificate A browser will open and display the WSDL file for the application Follow the steps to secure the client application as described in the next section EXAMPLE TRANSPORT SECURITY SSL Securing the Example Web Service Client Application SSL This section demonstrates adding security to the web service client that refer ences the web service created in the previous section This web service is secured using the security mechanism described in Transport Security SSL page 62 To add security to the client that references this web service complete the fol lowing steps 1 Create the client application by following the steps described in Creating a Client to Consume a WSIT Enabled Web Service page 29 with the exception that you need to specify the secure WSDL when creating the Web Service Client To do this create the client application up to the step where you create the Servlet step 7 as of this writing by following the steps described in Creating a Client to Consume a WSIT Enabled Web Ser vice page 29 w
18. over SSL YES no alias Endorsing Cert SAML Sender Vouches with Cert YES no alias SAML Holder of Key YES no alias STS Issued Token STS Issued Token with Ser vice Cert STS Issued Endorsing Token 53 54 USING WSIT SECURITY e Keystore lIf this column indicates YES click the Keystore button and configure the keystore to specify the alias identifying the service certificate and private key For the GlassFish keystores the file is keystore jks and the alias is xws security server assuming that you ve updated the GlassFish default certificate stores as described in Updating GlassFish Certificates page 74 e Truststore If this column indicates YES click the Truststore button and configure the truststore to specify the alias that contains the certificate and trusted roots of the client For the GlassFish keystores the file is cac erts jks and the alias is xws security client assuming that you ve updated the GlassFish default certificate stores as described in Updating GlassFish Certificates page 74 e STS If this column indicates YES you must have a Security Token Ser vice that can be referenced by the service An example of an STS can be found in the section Creating and Securing the STS STS page 117 The STS is secured using a separate non STS security mechanism The secu rity configuration for the client side of this application is dependent
19. public byte retByteArray byte inByteArray return inByteArray lt In rpclit mode the above Java web service method will throw an exception if the following XML instance with xsi nil is passed by a NET client gt lt RetByteArray xmIns http tempuri org gt lt inByteArray a nil true xmins xmIns a http ww w3 org 2001 XMLSchema instance gt lt RetByteArray gt 10 Using Atomic Transactions Tiss chapter explains how to configure and use WSIT WS TX which imple ments Web Services AtomicTransactions WS AT and Web Services Coordina tion WS Coordination WSIT WS TX enables Java EE transactions to work across heterogeneous systems that support WS AT and WS Coordination About the basic WSIX Example The basicWSTX example shows the following on the client side 1 Developers use existing Java Transaction APIs JTA Invocations of transacted web service operations flow transactional context from client to web service Persistent resources updated with client created transactions are all com mitted or rolled back as a single atomic transaction 2 After the client side code commits or aborts the JTA transaction the client confirms that all operations in the transaction succeeded or failed via calls to verify methods on the transacted web service 183 184 USING ATOMIC TRANSACTIONS The example also shows the following on the service side 1 A transacted web service implemented
20. s truststore To configure your environment to run the example a Change to the lt INSTALL gt wsittutorial examples wstx basi cW STX Samp1eService directory 188 b USING ATOMIC TRANSACTIONS cd lt INSTALL gt wsittutorial examples wstx basicWSTX Sam pleService Issue the following command to configure your environment to run the example ant setup Register the GlassFish server instances domain and domain2 in the Net Beans IDE a ie If the Sun Java System Application Server domain1 is already regis tered go to Step 4g If it is not go to Step 4b In the Runtime tab right click Servers and select Add Server The Add Server Instance dialog displays Choose the server Sun Java System Application Server from the pull down and give it a descriptive name such as Sun Java System Applica tion Server domain Server and then press Next Press the Browse button navigate to the location where the GlassFish server is installed then press Choose Select domain from the pulldown then press Next Enter the admin account password adminadmin in the Admin Pass word field then press Finish The server instance you just registered is the one in which you will run the web service SampleService Right click Servers and select Add Server The Add Server Instance dia log displays Choose the server Sun Java System Application Server from the pull down and give it
21. the system to point to the client and server keystore and truststore files Steps for doing this are described in Configuring SSL For Your Applica tions page 69 Configuring SSL For Your Applications This section describes adding the steps to configure your application for SSL These steps will need to be accomplished for any application that uses one of the mechanisms e Transport Security SSL page 62 see Example Transport Security SSL page 103 e Message Authentication over SSL page 64 e SAML Authorization over SSL page 64 see Example SAML Authori zation over SSL SA page 106 The following steps are generic to any application but have example configura tions that will work with the tutorial examples in particular Example SAML Authorization over SSL SA page 106 and Example Transport Security SSL page 103 To configure SSL for your application follow these steps 1 Select one of the mechanisms that require SSL These include Transport Security SSL page 62 Message Authentication over SSL page 64 and SAML Authorization over SSL page 64 2 Server Configuration e GlassFish is already configured for SSL No further SSL configuration is necessary if you are using Transport Security However if you are using one of the Message Security mechanisms with SSL you must update the GlassFish certificates as described in Updating GlassFish Certificates page 74 e Configure a user on GlassFis
22. vice retrieving its WSDL file and using the WSDL file to create a web service client that can access and consume a web service The process consists of the following steps which are shown in Figure 1 2 Client Application Get URL Web Service Get URL Registry MetadataExchange Request vim gf mso dntces Polo Access and Consume the Web Service Web Service Web Service Client Figure 1 2 Bootstrapping and Configuration 1 Client acquires the URL for a web service that it wants to access and con sume How you acquire the URL is outside the scope of this tutorial For example you might look up the URL in a Web Services registry 2 The client uses the URL and the wsimport tool to send a MetadataExchan geRequest to access the web service and retrieve the WSDL file The WSDL file contains a description of the web service endpoint including WS Policy assertions that describe the security and or reliability capabili INTRODUCTION ties and requirements of the service The description describes the require ments that must be satisfied to access and consume the web service 3 The client uses the WSDL file to create the web service client 4 The web service client accesses and consumes the web service Chapter 3 explains how to bootstrap and configure a web service client and a web service endpoint that use the WSIT technologies Message Optimization Technology A primary function of web services application
23. which contains the latest security con figuration information e Example Username Authentication with Symmetric Keys UA page 97 e Example Mutual Certificates Security MCS page 100 e Example Transport Security SSL page 103 e Example SAML Authorization over SSL SA page 106 e Example SAML Sender Vouches with Certificates SV page 111 e Example STS Issued Token STS page 115 Example Usemame Authentication with Symmetric Keys UA The section includes the following topics e Securing the Example Service Application UA page 98 e Securing the Example Web Service Client Application UA page 99 98 USING WSIT SECURITY Securing the Example Service Application UA The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing security to both the web service and to the web service client For this example the security mechanism of Username Authentication with Symmetric Keys page 61 is used to secure the application To add security to the service part of the example follow these steps 1 If you haven t already completed these steps complete them now a Update the GlassFish keystore and truststore files as described in Updat ing GlassFish Certificates page 74 b Create a user on GlassFish as described in Adding Users to GlassFish page 72 Create the CalculatorApplication example by
24. 11 Select the WSIT Configuration tab of the MySTSService dialog 12 Provide the client s private key by pointing to an alias in the keystore To do this expand the Certificates node click the Load Aliases button for the keystore and select xws security client from the Alias list 13 Verify the STS s certificate by pointing to an alias in the client truststore To do this from the Certificates node click the Load Aliases button and select wssip from the Alias list 14 Expand the Username Authentication node and verify that the default user name and password as specified in GlassFish If you followed the steps in Adding Users to GlassFish page 72 this will be User Name wsitUser and Password changeit 15 Click OK to close this dialog 16 Compile and run this application by right clicking the CalculatorWSServ letClient project and selecting Run Project EXAMPLE OTHER STS EXAMPLES 121 Example Other STS Examples Another STS example application can be found at the following URL https wsit dev java net source browse wsit wsit samples ws trust Further Information For more information on securing web applications using the WSIT technology visit the Project Tango web site at https wsit dev java net On this page you will find information about the specifications implemented in this product source code support information links to documentation updates and much more Some other sources that contain blogs and or
25. Class 169 Open Content 172 Enum Type 174 Package 175 Web Service Start from WSDL 176 Java Client 176 Customizations for WCF Service WSDL 177 generateElementProperty 177 Developing a Microsoft NET Client 181 BP 1 1 Conformance 182 BP 1 1 R2211 182 Using Atomic Transactions 183 About the basicWSTX Example 183 Building Deploying and Running the basicWSTX Example 187 INDEX ia tae eee ees 6 LOS About This Tutonal Tiss tutorial explains how to develop web applications using the Web Service Interoperability Technologies WSIT The tutorial describes how when and why to use the WSIT technologies and also describes the features and options that each technology supports WSIT developed by Sun Microsystems implements several new web services technologies including WS Security WS Trust WS SecureConversation WS ReliableMessaging WS AtomicTransactions Data Binding and Optimization WSIT was also tested in a joint effort by Sun Microsystems Inc and Microsoft with the expressed goal of ensuring interoperability between web services appli cations developed using either WSIT and the Windows Communication Founda tion WCF product Who Should Use This Tutonal This tutorial is intended for programmers who are interested in developing and deploying Java based clients and service providers that can interoperate with Microsoft NET 3 0 clients and service providers vii Viii ABOUT THIS TUTORIAL
26. File Folder at the top RW N Select Web Services from the Categories list Select Secure Token Service STS from the File Type s list Click Next Enter the name MySTS for the Web Service Class Name Select org me my sts from the Package list 10 Click Finish The IDE takes a while to create the STS When created it displays under the project s Web Services node as MySTSService and MySTS java dis plays in the right pane Oo AON DN 11 The STS wizard creates an empty implementation of provider class Implement the provider implementation class by copying the following code into the MySTS java file a Add these import statements to the list of imports import com sun xml ws security trust sts BaseSTSImp1 import javax annotation Resource import javax xml ws Provider import javax xml ws Service 118 USING WSIT SECURITY import javax xml ws ServiceMode import javax xml ws WebServiceContext import javax xml ws WebServiceProvider import javax xml transform Source import javax xml ws handler MessageContext b Add the following Resource annotation after the line public class MySTS implements javax xml ws Pro vider lt Source gt Resource protected WebServiceContext context c Change the following line of code public class MySTS implements javax xml ws Provider lt Source gt to public class MySTS extends BaseSTSImp1 implements javax xml ws Provider lt Source gt d For the invo
27. How to Use This Tutonal This tutorial addresses the following technology areas e Bootstrapping and Configuration e Message Optimization e Reliable Messaging WS RM e Web Services Security 1 1 WS Security e Web Services Trust WS Trust e Web Services Secure Conversation WS Secure Conversation e Data Contracts e Atomic Transactions WS AT About the Examples This section tells you everything you need to know to install build and run the examples Required Software To use this tutorial you must download and install the following software e The latest Java SE 5 0 Update 12 or JDK 6 0 Update 2 with which the WSIT Milestone 6 software has been extensively tested e GlassFish version 2 Build 58 your web container You can run the examples in this tutorial that use a web container without the NetBeans IDE on either GlassFish or Tomcat However for this edi tion of the tutorial you can only run the examples that use a web con tainer and the NetBeans IDE with GlassFish e WSIT distribution Milestone Release 6 Release Candidate 1 e Netbeans IDE 5 5 1 FCS e WSIT plug in modules Version 2 41 for Netbeans IDE 5 5 1 See the WSIT Installation Instructions located at https wsit docs dev java net releases m6 install html for instructions about downloading and installing all the required software ABOUT THIS TUTORIAL ix To run the examples described in this tutorial you must also download the WSIT samples kits
28. Location ity_Federation_SecurityTokenService_Indigo Symmetric svc wsdl Metadata DSR Service Name MySTSService S Port Name CustomBinding IMySTSService Namespace Jntpyfempuriorg y S Cancel Help Figure 6 9 WSIT Configuration Page Secure Token Service on Client STS Example 1 Endpoint with Metadata e Endpoint http 131 107 72 15 Security_Federation_SecurityTokenService_Indigo Symmetric svc Scenario_5_IssuedTokenForCerti ficate_MutualCertificatell e Metadata http 131 107 72 15 Security_Federation_SecurityTokenService_Indigo Symmetric svc STS Example 2 Endpoint with WSDL Location Service Name Port Name and Namespace e Endpoint http 131 107 72 15 EXAMPLE APPLICATIONS 97 Security_Federation_SecurityTokenService_Indigo Symmetric svc Scenario_5_IssuedTokenForCerti ficate_MutualCertificatel11 e WSDL Location http 131 107 72 15 Security_Federation_SecurityTokenService_Indigo Symmetric svc wsdl e Service Name MySTSService e Port Name CustomBinding_IMySTSService e Namespace http tempuri org Example Applications The following example applications demonstrate configuring web services and web service clients for different security mechanisms If you are going to work through the examples sequentially you must manually undo the changes to the service and then refresh the client in order for the client to receive the most recent version of the service s WSDL file
29. Options 43 Creating Web Service Providers and Clients that use Reliable Messag ing 45 Using Secure Conversation With Reliable Messaging 45 Using WST Security eceeceeeeeeceeee ee s47 Configuring Security Using NetBeans IDE 48 Securing the Service 48 Securing the Client 50 Summary of Configuration Requirements 52 Summary of Service Side Configuration Requirements 52 Summary of Client Side Configuration Requirements 54 Security Mechanisms 61 Username Authentication with Symmetric Keys 61 Mutual Certificates Security 62 Transport Security SSL 62 Message Authentication over SSL 64 SAML Authorization over SSL 64 Endorsing Certificate 65 SAML Sender Vouches with Certificates 65 SAML Holder of Key 66 Chapter 7 CONTENTS STS Issued Token 66 STS Issued Token with Service Certificate 67 STS Issued Endorsing Token 67 Configuring SSL and Authorized Users 68 Configuring SSL For Your Applications 69 Adding Users to GlassFish AD Configuring Keystores and Truststores 74 Updating GlassFish Certificates 74 Specifying Aliases with the Updated Stores 76 Configuring the Keystore and Truststore 77 Configuring Validators 84 Securing an Operation 85 Specifying Security at the Operation Input Message or Output Message Level 86 Supporting Token Options 89 Configuring A Secure Token Service STS 90 Creating a Third Party STS 91 Specifying an STS on the Service Side 94 Specifying an STS on the Client Side 94 Example Applications 97 Exa
30. Service Attributes The Web Service Attributes editor is displayed 2 Enable Secure Service 3 Click the Validator button 4 On the Validator Configuration page specify the following options when necessary e Username Validator Specifies the validator class to be used to vali date username and password on the server side This option is only used by a web service NOTE When using the default Username Validator make sure that the username and password of the client are registered with GlassFish using Admin Console described in Adding Users to GlassFish page 72 if using GlassFish or is included in the tomcat users xml file if using Tomcat e Timestamp Validator Specifies the validator class to be used to check the token timestamp to determine whether the token has expired or is still valid SECURING AN OPERATION e Certificate Validator Specifies the validator class to be used to vali date the certificate supplied by the client or the web service e SAML Validator Specifies the validator class to be used to validate SAML token supplied by the client or the web service 5 Click OK to close the dialog Securing an Operation This section discusses specifying security mechanisms at the level of a web ser vice operation The lt operation_name gt Operation section consists of three subsections These include e Operation At times you may need to configure different operations with different supporting to
31. XML schema fea tures The WCF serialization mechanisms DataContractSerializer and Xm1Serializer provide different levels of support for XML schema features Thus the following step will ensure that the WSDL schema file can be consumed by the WCF serialization mechanisms svcutil lt wsd1 file gt svcutil exe tool by default uses DataContractSerializer but falls back to Xm1Serializer if it encounters an XML schema construct not supported by Xm1Formatter Java Client A Java client is always developed starting from a WSDL See section Custom izations for WCF Service WSDL page 177 for guidelines CUSTOMIZATIONS FOR WCF SERVICE WSDL 177 Customizations for WCF Service WSDL When developing either a Java web service or a Java client from a WCF service WSDL generated using DataContractSerializer the following JAXB 2 0 cus tomizations are useful and or required e generateElementProperty e mapSimpleTypeDef The following sections explain the use and rationale of these customizations generateHementProperty WCE service WSDL generated from a programming language such as C using DataContractSerializer may contain XML Schema constructs which result in JAXBElement lt T gt in generated code A JAXBElement lt T gt type can also some times be generated when a WSDL contains advanced XML schema features such as substitution groups or elements that are both optional and nillable In all such cases JAXBElement lt T gt provides
32. a descriptive name such as Sun Java System Applica tion Server domain2 Client and then press Next Press the Browse button navigate to the location where the GlassFish server is installed then press Choose Select domain2 from the pulldown then press Next Enter the admin account password adminadmin in the Admin Pass word field then press Finish The server instance you just registered is the one in which you will run the web service client Samp1eService Client Associate the SampleService web service with the appropriate instance domain1 of the GlassFish server a Select File then Open Project BUILDING DEPLOYING AND RUNNING THE BASICWSTX EXAMPLE 189 b Browse to the lt wsit tutorial home gt examp1les wstx basicWSTX directory select the SampleService project and select Open Project Folder c In the Projects tab right click SampleService select Properties then select the Run category d Use the Server pulldown to point to the Sun Java System Application Server the default domain or the Glassfish server instance domain1 you registered in Step 4 e Click OK Set the proper transaction attributes for each mapping wsd1 binding wsd1 operation in the SimpleService war web service This operation creates file SampleService SampleService war web WEB INF wsit wstx sample service Simple xml in which the transaction attribute settings for the Samp1eService war are stored
33. and click Next 2 Name the project for example CalculatorWSServletClient 3 Make sure that the J2EE version is set to Java EE 5 then click Finish 4 Right click the CalculatorWSServletClient node and select New Web Service Client The New Web Service Client window appears 5 Cut and paste the URL of the web service that you want the client to con sume into the WSDL URL field for example http localhost 8080 40 6 MESSAGE OPTIMIZATION CalculatorApplication CalculatorWSService wsdl the URL of the CalculatorWS web service Type org me calculator client in the Package field and click Finish The Projects tab displays the new web service client shown in Figure 4 3 Projects ax Files Runtime 5 5 Web Pages H WEB INF Be index jsp B C Web Service References 5 Calculator wS gt Figure 4 3 Web Service Client 7 10 11 12 13 14 15 Right click the CalculatorWSServletClient project node and choose New Servlet Name the servlet ClientServlet specify the package name for example org me calculator client and click Finish To make the servlet the entry point to your application right click the project node choose Properties click Run type ClientServlet in the Relative URL field and click OK Double click ClientServlet java so that it opens in the Source Editor In the Source Editor remove the line that comments out the body of the processRequest
34. and select Edit Web Service Attributes 4 Unselect Reliable Messaging if it is selected 5 Select Secure Service 6 From the drop down list for Security Mechanism select Mutual Certifi cates Security 7 Click the Keystore button then click the Load Aliases button and select xws security server Click OK to close the dialog 8 Click OK to close the WSIT Configuration dialog A new file is added to the project To view the WSIT configuration file expand Web Pages WEB INF then double click the file wsit org me calculator CalculatorWS xm1 This file contains the sc Key Store element 9 Right click the CalculatorApplication node and select Run Project A browser will open and display the WSDL file for the application 10 Verify that the WSDL file contains the AsymmetricBinding element 101 102 USING WSIT SECURITY 11 Follow the steps to secure the client application as described in the next section Securing the Example Web Service Client Application MCS This section demonstrates adding security to the web service client that refer ences the web service created in the previous section This web service is secured using the security mechanism described in Mutual Certificates Security page 62 To add security to the client that references this web service complete the fol lowing steps 1 NM BW WN Create the client application following the steps described in Creating a Client to Consume a WSIT En
35. as a Java servlet The Edit Web Service Attributes feature in the NetBeans WSIT plug in is used to configure Transaction Attributes of each web service operation 2 A transacted web service implemented as Container Managed Transaction CMT No configuration is necessary for this case 3 Managed Java EE resources participating in a distributed transaction hav ing its transacted updates all committed or rolled back Both transacted web service operations servlet and CMT EJB manipulate these resources This example only shows how to use XATransaction enabled JMS While this example shows WSIT to WSIT operations the client is configured to run on one GlassFish instance and the service runs on the other GlassFish instance Either the Java client or the Java web service could be replaced by a semantically equivalent Microsoft implementation The WS Coordination WS AtomicTransaction protocol messages flow back and forth between the two GlassFish instances just as they would in a Sun to Microsoft and a Microsoft to Sun transaction interoperability scenario The basicWSTX example was designed so it could be run in either one or in two GlassFish domains If you run the example in one domain only one coordinator is used no WS Coordination protocol messages will be exchanged We explain how to run the example in two domains so both protocols WS Coordination and WS AtomicTransaction WS AT are used as shown in Figure 10 1 ABOUT THE B
36. be used to establish the correspon dence between the subject of the SAML subject statements in SAML asser tions and SOAP message content The attesting entity presumed to be different from the subject vouches for the verification of the subject The receiver has an existing trust relationship with the attesting entity The attesting entity protects the assertions containing the subject statements in combination with the mes sage content against modification by another party For more information about the Sender Vouches method read the SAML Token Profile document at http docs oasis open org wss oasis wss saml token profi le 1 0 pdf For this mechanism the SAML token is included as part of the message signa ture as an authorization token and is sent only to the recipient The message pay load needs to be signed and encrypted The requestor is vouching for the credentials present in the SAML assertion of the entity on behalf of which the requestor is acting The initiator token which is an X 509 token is used for signature The recipient token which is also an X 509 token is used for encryption For the server this is reversed the recipient token is the signature token and the initiator token is the encryption token A SAML token is used for authorization See Also Example SAML Sender Vouches with Certificates SV page 111 65 66 USING WSIT SECURITY SAML Holder of Key This mechanism protects messages with a
37. can be used 20 INTRODUCTION How Trust Works Figure 1 11 shows how the Web Services Trust technology establishes trust Establish HTTP Connection Security Token Service RequestSecurity Token RequestSecurity TokenResponse Client Q Client Authenticates to Service Web gt Service Figure 1 10 Trust and Secure Conversation To establish trust between a client a Security Token Service and a web service 1 The client establishes an HTTPS connection with the Secure Token Ser vice using one of the following methods e Username Authentication and Transport Security The client authenti cates to the Security Token Service using a username token The Secu rity Token Service uses a certificate to authenticate to the Client Transport security is used for message protection e Mutual Authentication Both the client side and server side use X509 certificates to authenticate to each other The client request is signed using Client s X509 certificate then signed using ephemeral key The web service signs the response using keys derived from the client s key 2 The client sends a RequestSecurityToken message to the Security Token Service 3 The Security Token Service sends a Security Assertion Markup Language SAML token to the Client 4 The client uses the SAML token to authenticate itself to the web service and trust is established All communication uses SOAP messages How THE WSIT TECHNOLOG
38. com xml ns jaxb xmIns wsdl http schemas xmlsoap org wsd1 wsdl Location http localhost 8080 wsit enab ed fromwsd1 addnumbers wsd1 xmIns http java sun com xml ns jaxws gt lt bindings node nsl1 definitions xmIns nsl http schemas xmlsoap org wsd1 gt lt package name fromwsd client gt lt bindings gt lt bindings node nsl definitions ns1 types xsd schema targetNamespace http duke org xmIns xs http www w3 org 2001 XMLSchema xmIns nsl http schemas xmlsoap org wsd1 gt lt jaxb schemaBindings gt UNDEPLOYING A WEB SERVICE 139 lt jaxb package name fromwsdl client gt lt jaxb schemaBindings gt lt bindings gt lt bindings gt Building and Deploying a Client To build and deploy a client for either of the examples provided in this tutorial enter one of the following Ant commands in the top level directory of the respective example either wsit enabled fromjava or wsit enabled from wsd1 depending on which web container you are using For GlassFish ant client For the Apache Tomcat ant Duse tomcat true client This command runs wsimport which retrieves the web service s WSDL and then it runs javac to compile the source Running a Web Service Client To run a client for either of the examples provided in this tutorial enter one of the following Ant commands in the top level directory of the respective exam ple either wsit enabled fromjava or wsit enabled fromwsd1
39. customization generateElementProperty false gt public class Person String getName public void setName String value The above binding is more natural to Java developer than JAXBEle ment lt String gt However it does not roundtrip the value of lt name gt JAXB 2 0 allows generateElementProperty to be set e Globally in lt jaxb globalBindings gt e Locally in lt jaxb property gt customization When processing a WCF service WSDL it is recommended that the genera teElementProperty customization be set in lt jaxb globalBindings gt lt jaxb bindings version 2 0 xmIns jxb http java sun com xml ns jaxb xmIns xs http www w3 org 2001 XMLSchema gt lt jaxb bindings schemaLocation schema importedby wcfsvcwsd1 node xs schema gt lt jaxb globalBindings generateElementProperty false gt lt jxb bindings gt CUSTOMIZATIONS FOR WCF SERVICE WSDL 179 Note The generateElementProperty attribute was introduced in JAXB 2 1 mapSimpleTypeDef XML Schema Part 2 Datatype defines facilities for defining datatypes for use in XML Schemas NET platform introduced the CLR types for some of the XML schema datatypes as described in Table 9 1 Table 9 1 CLR to XML Schema Type Mapping CLR Type XML Schema Type xs unsignedByte xs unsignedInt xs unsignedShor xs unsignedLong However there are no corresponding Java types that map to the XML Schema types listed in Tab
40. depending on which web container you are using For GlassFish ant run For the Apache Tomcat ant Duse tomcat true run This command executes the run target which simply runs Java with the name of the client s class for example fromwsd1 client AddNumbersClient Undeploying a Web Service During the development process it is often useful to undeploy a web service Undeploying a web service means to disable and remove it from the web con tainer Once the web service is removed clients are no longer able to use the web service Further the web service will not restart without explicit redeployment by the user 140 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS To undeploy from GlassFish enter the following commands e asadmin undeploy user admin wsit enabled fromjava e asadmin undeploy user admin wsit enabled fromwsd1 To undeploy from Apache Tomcat enter the following commands e rm CATALINA_HOME webapps wsit enabled fromjava war e rm CATALINA_HOME webapps wsit enab1ed fromwsd war Accessing WSIT Services Using WCF Clients Tiss chapter describes how to build and run a Microsoft Windows Communi cation Foundation WCF client that accesses the addnumbers service described in Chapter 7 Creating a WCF Client The process of creating a WCF C client to the addnumbers service is similar to that for a Java programming language client To create a WCF client you will 1 Use the svcutil exe tool to gene
41. ensures that the service sends an acknowledgement to the cli ents for each message that is delivered thus enabling clients to recognize message delivery failures and to retransmit the message This capability makes the web service a reliable web service 3 In the left pane expand the Web Pages node and the WEB INF node and open the wsit lt endpoint classname gt xm file in the Source Editor Notice that the IDE has added the following tags to the file to enable reli able messaging lt wsp Policy wsu Id CalculatorwWSPortBindingPolicy gt lt wsp ExactlyOne gt 28 WSIT EXAMPLE USING A WEB CONTAINER AND NETBEANS lt wsp Al1 gt lt wsaw UsingAddressing xmlns wsaws http www w3 org 2006 05 addressing wsd1 gt lt wsrm RMAssertion gt lt wsp Al1 gt lt wsp Exact1yOne gt lt wsp Policy gt Deploying and Testing a Web Service Now that you have configured the web service to use WSIT technologies you can deploy and test it To deploy and test the web service perform the following steps 1 Right click the project node select Properties and select Run 2 Type CalculatorWSService wsd1 in the Relative URL field and click OK 3 Right click the project node and choose Run Project The first time Glass fish is started you will be prompted for the admin password The IDE starts the web container builds the application and displays the WSDL file page in your browser You have now successfull
42. exe has the following options for selecting a serializer svcutil exe serializer auto default svcutil exe serializer DataContractSerializer svcutil exe serializer Xml lSerializer We recommend using the default serializer auto option This option ensures that svcutil exe falls back to Xm1Serializer if an XML schema construct is used that cannot be processed by DataContractSe rializer For example in the following class field price is mapped to an XML attribute that cannot be consumed by DataContractSerializer public class POType javax xml bind annotation XmlAttribute public java math BigDecimal price lt XML schema fragment gt lt xs complexType name poType gt lt xs sequence gt lt xsiattribute name price type xs decimal gt lt xs complexType gt 2 Develop the NET client using the generated artifacts 182 DATA CONTRACTS BP 1 1 Conformance JAX WS 2 0 enforces strict Basic Profile 1 1 compliance The following are known cases where NET framework does not enforce strict BP 1 1 semantics and their usage can lead to interoperability problems BP 1 1 R2211 In rpclit mode BP 1 1 http ww ws i org Profiles BasicProfile 1 1 2006 04 10 htm l R2211 disallows the use of xsi nil in part accessors see the R2211 for the actual text From a developer perspective this means that in rpclit mode JAX WS does not allow a null to be passed in a web service method parameter Java Web method
43. following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet Expand CalculatorApplication Web Services then right click the node for the web service CalculatorWS and select Edit Web Service Attributes 4 Unselect Reliable Messaging if it is selected In the CalculatorWSPortBinding section select Secure Service From the drop down list for Security Mechanism select Username Authentication with Symmetric Keys Click the Keystore button to provide your keystore with the alias identify ing the service certificate To do this click the Load Aliases button and select xws security server Click OK to close Click OK to close the WSIT Configuration dialog A new file is added to the project To view the WSIT configuration file expand Web Pages WEB INF then double click the file wsit org me calculator Calculatorws xm1 This file contains the sc Key Store element 9 EXAMPLE USERNAME AUTHENTICATION WITH SYMMETRIC KEYS UA Right click the CalculatorApplication node and select Run Project A browser will open and display the WSDL file for the application 10 Verify that the WSDL file contains the following elements Symmet ricBinding and UsernameToken 1
44. following types of assertions are supported Protection assertions Define the scope of security protection These asser tions identify the message parts that are to be protected and how that is whether data integrity and confidentiality mechanisms are to be used Conditional assertions Define general aspects or pre conditions of the security These assertions define the relationships within and the character istics of the environment in which security is being applied such as the tokens that can be used which tokens are for integrity or confidentiality protection and applicable algorithms to use and so on Security binding assertions Define the security mechanism that is used to provide security These assertions are logical grouping that defines how the conditional assertions are used to protect the indicated message parts For example that an asymmetric token is to be used with a digital signature to provide integrity protection and that parts are to be encrypted with a sym metric key which is then encrypted using the public key of the recipient In its simplest form the security binding assertions restrict what can be placed in the wsse Security header and the associated processing rules Supporting token assertions Define the token types and usage patterns that can be used to secure individual operations and or parts of messages Web Services Security and Trust assertions Define the token referencing and trust options that
45. gt NET auto generated code from schema public partial class purchaseOrder private System Nullable lt decimal gt priceField public decimal price get return this priceField set this priceField value XmlAtiibute A property field can be mapped to an XML attribute using XmlAttribute annotation NET binds an XML attribute to a property Example Mapping field property to XML attribute Java code fragment public class UKAddress extends Address XmlAttribute public int exportCode Schema fragment lt XML Schema fragment gt lt xs complexType name ukAddress gt lt xs complexContent gt lt xs extension base tns address gt lt xs Sequence gt WEB SERVICE START FROM JAVA 167 lt xSiattribute name exportCode type xs int gt lt xsiextension gt lt xs complexContent gt lt xs complexType gt NET auto generated code from schema public partial class ukAddress address private int exportCodeField public int exportCode get return this exportCodeField set this exportCodeField value XmlElementRefs Guideline Xm1ElementRefs maps to a xs choice This binds to a property with name item in the C class If there is another field property named item in the Java class there will be a name clash that NET will resolve by generating name To avoid the nameclash either change the name or use customization for example
46. https is the transport protocol used between a WSIT client and a secure web service using transport binding and you are refer encing localhost when creating the client Note If you use the fully qualified hostname FQHN in the URL for the service WSDL when you are adding the web service client to the client application this workaround is not required It is only required when you specify localhost in the URL for the service WSDL During development not production it is sometimes convenient to use certifi cates whose CN Common Name does not match the host name in the URL A developer would want to use a CN which is different from the host name in the URL in WSIT when using https addresses in Dispatch clients and during wsim port The below mentioned workaround is only for the Dispatch clients which are also used in WS Trust to communicate with STS This has to be done even if the client s main service is not on https but only the STS is on https Java by default verifies that the certificate CN Common Name is the same as host name in the URL If the CN in the certificate is not the same as the host name your web service client fails with the following exception javax xml ws WebServiceException java io IOException HTTPS hostname wrong should be lt hostname as in the certificate gt The recommended way to overcome this issue is to generate the server certificate with the Common Name CN matching the host name To workarou
47. node b Enter the username and password that you created on GlassFish into the Default Username and Default Password fields If you followed the steps in the section Adding Users to GlassFish page 72 the user name is wsitUser and the password is changeit 99 100 USING WSIT SECURITY NOTE In a production environment you should configure a Username Handler and a Password Handler class to eliminate the security risk asso ciated with the default username and password options 7 Provide the server s certificate by pointing to an alias in the client trust store To do this select the Certificates node click the Load Aliases button and select xws security server from the Alias list 8 Click OK to close this dialog 9 In the tree drill down from the project to Source Packages gt META INF Double click on CalculatorWSService xml and verify that lines similar to the following are present lt wsp Al1 gt lt wsaws UsingAddressing xmIns wsaws http www w3 org 2006 05 addressing wsd1 gt lt sc CallbackHand1erConfi guration wspp visibi lity private gt lt sc CallbackHandler default wsitUser name UusernameHandler gt lt sc CallbackHandler default changeit name passwordHandler gt lt sc CallbackHandlerConfiguration gt lt sc TrustStore wspp visibility private location home glassfish domains domainl config cacerts jks storepass Cchangeit peeralias xws security server gt lt wsp Al1 gt
48. or messaging system This is accomplished by defining XML tags for including web service addresses in the SOAP message instead of the HTTP header The imple mentation of these features enables messaging systems to support message transmission in a transport neutral manner through networks that include processing nodes such as endpoint managers firewalls and gate ways Web Services Secure Conversation This specification provides better mes sage level security and efficiency in multiple message exchanges in a stan dardized way It defines basic mechanisms on top of which secure messaging semantics can be defined for multiple message exchanges and allows for contexts to be established and potentially more efficient keys or new key material to be exchanged thereby increasing the overall perfor mance and security of the subsequent exchanges SOAP MTOM The SOAP Message Transmission Optimization Mecha nism MTOM paired with the XML binary Optimized Packaging XOP provides standard mechanisms for optimizing the transmission and or wire format of SOAP messages by selectively encoding portions of the SOAP message while still presenting an XML Infoset to the SOAP application This mechanism enables the definition of a hop by hop contract between a SOAP node and the next SOAP node in the SOAP message path so as to facilitate the efficient pass through of optimized data contained within headers or bodies of SOAP messages that are relayed by
49. perfor mance Therefore you should not enable this option unless ordered delivery is required by the web service Flow Control Specifies whether the Flow Control feature is enabled When enabled this option works in conjunction with the Max Buffer Size setting to determine the maximum number of messages for sequence that can be stored at the endpoint awaiting delivery to the application Messages may have to be withheld from the applica tion if ordered delivery is required and some of their predecessors have not arrived If the number of stored messages reaches the threshold specified in the Max Buffer Size setting incoming mes sages belonging to the sequence are ignored Max Buffer Size If Flow control is enabled specifies the number of messages that will be buffered for a message sequence The default setting is 32 For more information see the description of the Flow Control option Inactivity Timeout Specifies the time interval beyond which either source or destina tion may terminate any message sequence due to inactivity The default setting is 600 000 milliseconds 10 minutes A web ser vice endpoint will always terminate a sequence whose inactivity timeout has expired To keep the sequence active an inactive client will always send a stand alone message with an AckRequested header to act as a heartbeat as the end of the Inactivity timeout interval approaches USING SECURE CONVERSATION WITH RELIABLE MESS
50. require that a truststore be configured on the client side Any kind of signature without WS SecureConversation will generally require a truststore on the server side NOTE For this release we are showing that you place the trusted certificates of other parties in GlassFish s truststore cacerts jks This is not a recommended practice because any certificate you add to the cacerts jks file effectively means it can be a trusted root for any and all certificate chains which can be a security problem In future releases trusted certificates from other parties will be placed in a certstore and only trusted roots will be placed inside cacerts jks 79 USING WSIT SECURITY To set the truststore configuration options on a service perform the following steps 1 Check the table in Summary of Service Side Configuration Requirements page 52 to see if a truststore is required for the selected security mecha nism If so continue 2 Right click the web service and select Edit Web Service Attributes The Web Service Attributes editor is displayed 3 Enable Secure Service 4 Click the Truststore button 5 On the Truststore Configuration page specify the following options e Location By default the location and name of the truststore that stores the public key certificates of the CA and the client s public key certificate is already entered The GlassFish truststore file is lt AS_HOME gt domains domain1 config cacerts jks e S
51. roundtripping support of values in XML instances However JAXBElement lt T gt is not natural to a Java developer So the generateElementProperty customization can be used to generate an alternate developer friendly but lossy binding The different bindings along with the trade offs are discussed below Default Binding The following is the default binding of an optional minOccurs 0 and ni11 able nillable true element lt XML schema fragment lt xs element name person type Person lt xs complexType name Person gt lt xsS Sequence gt lt xs element name name type xs string nillable true minOccurs 0 gt lt xsS Sequence gt lt xs complexType gt Binding public class Person JAXBElement lt String gt getName public void setName JAXBElement lt String gt value 178 DATA CONTRACTS Since the XML element name is both optional and nillable it can be repre sented in an XML instance in one of following ways lt Absence of element name gt lt person gt lt element name is absent gt lt person gt lt Presence of an element name gt lt person gt lt name xsi inil true gt lt person gt The JAXBElement lt String gt type roundtrips the XML representation of name element across an unmarshal marshal operation Customized Binding When generateElementProperty is false the binding is changed as follows set JAXB
52. screencasts about using WSIT include the following e Sun WSIT Bloggers http pipes yahoo com pipes pipe info _id 2iWQPSDG2xGTQWC7p2IyxQ http planet sun com webservices group blogs e Project Tango An Overview https wsit dev java net docs tango overview pdf e Web Services blog http blogs sun com arungupta category webservices e Manual Web Service Configuration In From Java Case and others http blogs sun com japod date 20070226 e Develop WSTrust Application Using NetBeans and others http blog sun com shyamrao e Security in WSIT and others http blogs sun com ashutosh category Sun e WSIT Screencasts https wsit dev java net screencasts htm e Specifications Implemented by WSIT https wsit dev java net specification links htm 122 UsING WSIT SECURITY 1 WSIT Example Using a Web Container Without NetBeans Tiss chapter describes how to use the two supported web containers Glass Fish version 2 or Apache Tomcat 5 5 to create build and deploy a web service and a client that use the Web Services Interoperability Technologies WSIT This chapter also includes examples of the files you must create and the build directories To run the examples described in this chapter download the WSIT samples kits wsit enabled fromjava zip and wsit enabled fromwsd1 zip from the fol lowing location https wsit dev java net source browse wsit wsit docs howto You could also use NetBeans IDE to cr
53. signed SAML assertion issued by a trusted authority carrying client public key and authorization information with integrity and confidentiality protection using mutual certificates The Holder of Key HOK method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message The attesting entity includes a signature that can be verified with the key information in the confir mation method of the subject statements of the SAML assertion referenced for key info for the signature For more information about the Holder of Key method read the SAML Token Profile document at http docs oasis open org wss oasis wss saml token profile 1 0 pdf Under this scenario the service does not trust the client directly but requires the client to send a SAML assertion issued by a particular SAML authority The cli ent knows the recipient s public key but does not share a direct trust relationship with the recipient The recipient has a trust relationship with the authority that issues the SAML token The request is signed with the client s private key and encrypted with the server certificate The response is signed using the server s private key and encrypted using the key provided within the HOK SAML asser tion STS Issued Token This security mechanism protects messages using a token issued by a trusted Secure Token Service STS for message integrity and confidentiality protection An STS is a service
54. the annotation Xm1MimeType which supports specifying the content type but NET ignores this information Example Mapping java awt Image without Xm1MimeType Java code fragment public class Claim public java awt Image photo Schema fragment lt xs complexType name claim gt lt xsS Sequence gt lt xs element name photo type xs base64Binary minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema public partial class claim object System Runtime Serialization IExtensibleDataObject private byte photoField wavne other gernerated code public byte photo WEB SERVICE START FROM JAVA 155 get return this photoField set this photoField value C code fragment try claim tmpC new claimQ System I0 FileStream f new System IO FileStream C icons circleIcon gif System IO FileMode Open int cnt Cint f Length tmpC photo new byte cnt int rCnt f Read tmpC photo cnt catch Exception e Console WriteLine e ToString Example Mapping java awt Image with Xm1MimeType Java code fragment public class Claim Xm1MimeType image gif public java awt Image photo Schema fragment lt xs complexType name claim gt lt xS Sequence gt lt xs element name photo nsl expectedContentTypes image gif type xs base64Binary minOccurs 0 xml
55. the service s application deployment descriptor which is web xml for a web service implemented as a servlet To specify the secu rity information follow these steps From your web service application expand Web Pages gt WEB INF Double click web xm1 to open it in the editor Select the Security tab On the Security Constraints line click Add Security Constraint Under Web Resource Collection click Add Enter a Name for the Resource CalcWebResource Enter the URL Pat tern to be protected Select which HTTP Methods to protect for example POST Click OK to close this dialog g Check the Enable User Data Constraint box Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL h O n h Click the XML tab to view the resulting deployment descriptor addi tions 107 108 USING WSIT SECURITY 11 Right click the CalculatorApplication node and select Run Project Accept the slas certificate if you are prompted to A browser will open and display the WSDL file for the application 12 Verify that the WSDL file contains the TransportBinding and Signed SupportingTokens element which in turn contains a Sam1Token element 13 Follow the steps to secure the client application as described in the next section Securing the Example Web Service Client Application SA This section demonstrates adding security to the web service client that refer ences the web service cre
56. use derived session keys that increase the overall security while reducing the security processing overhead for each message Further WSIT implements two additional features to improve security in web services e Web Services Security Policy Enables web services to use security asser tions to clearly represent security preferences and requirements for web service endpoints e Web Services Trust Enables web service applications to use SOAP mes sages to request security tokens that can then be used to establish trusted communications between a client and a web service WSIT implements these features in such a way as to ensure that web service binding security requirements as defined in the WSDL file can interoperate with and be consumed by WSIT and WCF endpoints For instructions on how to use the WS Security technology see Chapter 6 How WSIT Relates to Windows Communication Foundation WCF Web services interoperability is an initiative of Sun and Microsoft The goal is to produce web services consumers and producers that support platform indepen dence and then to test and deliver products to market that interoperate across different platforms WSIT is the product of Sun s web services interoperability initiative Windows Communication Foundation WCF is Microsoft s unified programming model for building connected systems WCF which is now available as part of the WSIT SPECIFICATIONS 7 NET Framework 3 0 produc
57. use follow the steps in Spec ifying an STS on the Service Side page 94 An example that creates and uses an STS can be found in Example STS Issued Token STS page 115 e On the client side specify the information for a preconfigured STS This is mainly used for a local STS that is in the same domain as the client Con figuring the STS for the client is described in Specifying an STS on the Cli ent Side page 94 Creating a Third Party STS Use the STS wizard to create an STS from a WSDL file When using the STS wizard provide the name of the STS implementation class This class must extend com sun xml ws security trust sts BaseSTSImp1 After complet ing the steps of the wizard your application will contain a new service that is an STS and includes a provider implementation class STS WSDL and a WSIT configuration file with a predefined set of policies To use the STS wizard to create an STS follow these steps 1 Create a new project for the STS by selecting File New Project Select Web then Web Application then Next Enter a Project Name Click Finish Right click the STS Project node select New then click File Folder at the top A U N Select Web Service from the Categories list Select Secure Token Service STS from the File Type s list Click Next Enter a name for the Web Service Class Name oO N OA U 91 92 USING WSIT SECURITY 9 Enter or select a name for the Package list
58. xwss dev java net servlets ProjectDocu mentList folderID 6645 amp expandFo 1 der 6645 amp fo1 der ID 6645 e An example application in this tutorial that uses a SAML Callback Handler can be found in Example SAML Authorization over SSL SA page 106 When writing SAML Callback Handlers for different security mechanisms set the subject confirmation method to SV Sender Vouches or HOK Holder of Key and the appropriate SAML Assertion version depending on the SAML ver sion and SAML Token Profile selected when setting the security mechanism for the service For example the following code snippet for one of the SAMLCallbackHandlers listed above demonstrates how to set the subject confirmation method and sets the SAMLAssertion version to 1 0 profile 1 0 ifCcallbacks i instanceof SAMLCallback try SAMLCallback sam1Callback C CSAMLCallback callbacks i Set confirmation Method to SV SenderVouches or HOK Holder of Key sam1Callback setConfi rmationMethod Csam1Callback SV_ASSERTION_TYPE if Csam1Callback getConfirmationMethod equals sam1Callback SV_ASSERTION_TYPE samlCallback setAssertionElement createSVSAMLAssertion svAssertion_sam110 sam1Callback getAssertionElementQ 59 60 USING WSIT SECURITY sam1Callback setAssertionElement createSVSAMLAssertion20 svAssertion_saml20 sam1Callback getAssertionElementQ selse ifCsam1Callback getConfi rmationMethod equals sam1C
59. 1 Follow the steps to secure the client application as described in the next section Securing the Example Web Service Client Application UA This section demonstrates adding security to the web service client that refer ences the web service created in the previous section This web service is secured using the security mechanism described in Username Authentication with Symmetric Keys page 61 When this security mechanism is used with a web service the web service client must provide a username and password in addition to specifying the certificate of the server To add security to the client that references this web service complete the fol lowing steps 1 2 Nn W Create the client application by following the steps described in Creating a Client to Consume a WSIT Enabled Web Service page 29 NOTE Whenever you make changes on the service refresh the client so that the client will pick up the change To refresh the client right click the node for the Web Service Reference for the client and select Refresh Cli ent Expand the node for the web service client application Calculator WSServletClient Expand the node for Web Service References Right click on CalculatorWSService select Edit Web Service Attributes Select the WSIT Configuration tab of the CalculatorWSService dialog For this testing environment provide a default username and password To do this a Expand the Username Authentication
60. 10 Click Finish The IDE takes a while to create the STS When created it displays under the project s Web Services node as lt your_STS gt Service and the Java file displays in the right pane 11 The STS wizard creates an empty implementation of provider class Implement the provider implementation class An example of this can be found in Creating and Securing the STS STS page 117 12 Back in the Projects window right click the STS project folder and select Edit Web Service Attributes to configure the STS 13 Select Secure Service 14 Select a Security Mechanism but not one of the STS mechanisms The example application uses Username Authentication with Symmetric Keys 15 Select the Configure button For Algorithm Suite option specify a value that matches the value of the web service Set the Key Size to 128 if you have not configured Unlimited Strength Encryption Select OK to close the configuration dialog NOTE Some of the algorithm suite settings require that Unlimited Strength Encryption be configured in the Java Runtime Environment JRE particularly the algorithm suites that use 256 bit encryption Instructions for downloading and configuring unlimited strength encryp tion can be found at the following URLS http java sun com products jce javase htm http java sun com javase downloads index_jdk5 jsp docs 16 Select Act as Secure Token Service STS The default values will create a valid STS Optionally
61. 5 Select Secure Service This option enables WSIT security for all of the operations of a web service For information on how to secure selected operations refer to Securing an Operation page 85 6 Select a Security Mechanism from the list Most of the mechanisms are fully functional without further configura tion however if you d like to customize the mechanism click Configure to specify the configuration for that mechanism 49 50 USING WSIT SECURITY 7 Specify Keystore Truststore STS SSL and or user information as required for the selected security mechanism Refer to the entry for the selected security mechanism in Table 6 1 for further information This table summarizes the information that need to be set up for each of the security mechanisms 8 Click OK to save your changes 9 Run the web application by right clicking the project node and selecting Run Project 10 Verify the URL of the WSDL file before proceeding with the creation of the web service client The client will be created from this WSDL file and will get the service s security policies through the web service reference URL when the client is built or refreshed The 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 lt package gt lt service gt xm file to open it in the editor Steps for confi
62. AGING 45 Creating Web Service Providers and Clients that use Reliable Messaging Examples and detailed instructions on how to create web service providers and clients that use reliable messaging are provided in Chapters 2 and 7 of this tuto rial e Foran example of creating a web service and a client using a web container and NetBeans IDE see Chapter 2 e Foran example of creating a web service and a client using only a web con tainer see Chapter 7 Using Secure Conversation With Reliable Messaging If Secure Conversation is enabled for the web service endpoint the web service acquires a Security Context Token SCT for each application message sequence that is each message sequence is assigned a different SCT The web service then uses that token to sign all messages exchanged for that message sequence between the source and destination for the life of the sequence Hence there are two benefits in using Secure Conversation with Reliable Messaging e The sequence messages are secure while in transit between the source and destination endpoints e Ifthere are different users accessing data at the source and destination end points the SCT prevents users from seeing someone else s data Note Secure Conversation is a WS Security option not a reliable messaging option If Secure Conversation is enabled on the web service endpoint Reliable Messaging uses Security Context Tokens For more information on how to use Secure C
63. AML Callback Handler class for the client lt wsp Al1 gt lt wsaws UsingAddressing xmlns wsaws http www w3 org 2006 05 addressing wsd1 gt lt sc CallbackHandlerConfi guration wspp visibility private gt lt sc CallbackHandler name samlHandler classname xwss saml1 Sam1CallbackHandler gt lt sc CallbackHand1erConfiguration gt lt sc KeyStore wspp visibility private location lt GF_HOME gt domains domainl config keystore jks storepass Cchangeit alias xws security client keypass changeit gt lt sc TrustStore wspp visibility private location lt GF_HOME gt domains domainl config cacerts jks storepass changeit peeralias xws security server gt lt wsp Al1 gt 12 Compile and run this application by right clicking the CalculatorClient node and selecting Run Project Example SAML Sender Vouc hes with Certificates SV The topics covered in this section include the following e Securing the Example Service Application SV page 112 e Securing the Example Web Service Client Application SV page 113 112 USING WSIT SECURITY Securing the Example Service Application SV The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing security to both the web service and to the web service client For this example the security mechanism of SAML Sender Vouches with Certif icates page 65 is u
64. ASICWSTX EXAMPLE 185 Domain 1 Client Servlet AT Coordinator AT Coordinator emia m Root Subordinate Web Service Initiator App i i l Transacted Application Message Request Figure 10 1 WS Coordination and WS AtomicTransaction Protocols in Two GlassFish Domains Figure 10 2 shows the components that make up the example 186 USING ATOMIC TRANSACTIONS Domain 2 Domain 1 SimpleService Client Servlet servlet web service Txn initiator transacted operations SimpeServiceASCMTEJIB EJB web service transacted operations JMS Resources jms ConnectionFac tory XATransaction Library FacaceWebServiceBean accessor EJB web sevice transacted operations JDBC Resources jabe connectionPool XATransaction jdbc java Progra mmingLibrary Figure 10 2 Components in the basicWSTX Example The service which runs in domain1 is comprised of two components e SimpleService a web service that is implemented as a servlet with trans acted operations e SimpleServiceASCMTEJB a container managed transaction Enterprise bean CMT EJB web service The SimpleService web service uses two JMS resources that are created in domain1 e jms ConnectionFactory an XATransaction connection factory e jms Queue a JMS queue The client servlet which runs in domain2 initiates the transaction BUILDING DEPLOYING AND RUNNING THE BASICWSTX EXAMPLE 187 Building Deploying and Running the basic WSI
65. C Adding 0 and 1 number1 number2 int result port addNumbers number1 number2 CREATING A WCF CLIENT 143 Console WriteLineC Result is 0 n n result numberl 10 Console WriteC Adding 0 and 1 number1 number2 result port addNumbers number1 number2 Console WriteLineC Result is 0 n n result port CloseQ catch CSystem ServiceModel FaultException e Console WriteLineC Exception e Message if port null port CloseQ Building and Running the Client The example bundle contains all the files you need to build and run a WCF client that accesses a WSIT web service written in the Java programming language The csclient enabled fromjava zip bundle contains the following files e Client cs the C client class e build bat the build batch file Generating the Proxy Class and Configuration File When creating a Java programming language client you use the wsimport tool to generate the proxy and helper classes used by the client class to access the web service When creating a WCF client the svcutil exe tool provides the same functionality as the wsimport tool svcutil exe generates the C proxy class and contracts for accessing the service from a C client program The example bundle contains a batch file build bat that calls svcutil exe to generate the proxy class The command is svcutil config Client exe config http localhost 8080 wsit enabled fromjava addn
66. E 25 Notice that this web service performs a very simple operation It takes two inte gers adds them and returns the result Perform the following steps to use the IDE to create this web service 1 Click on the Runtime tab in the left pane and verify that GlassFish is listed in the left pane If it is not listed refer to Registering GlassFish with the IDE page 23 and register it 2 Choose File New Project select Web Application from the Web cate gory and click Next 3 Assign the project a name that is representative of services that will be pro vided by the web service for example CalculatorApplication set the Project Location to the location of the Sun application server and click Finish Note As of this writing when creating the web service project be sure to define a Project Location that does not include spaces in the directory name Spaces in the directory might cause the web service and web service clients to fail to build and deploy properly To avoid this problem Sun recommends that you create a direc tory for example C work and put your project there 4 Right click the CalculatorApplication node and choose New gt Web Ser vice 5 Enter the web service name CalculatorWS and the package name org me calculator in the Web Service Name and the Package fields respectively 6 Select Create an Empty Web Service 7 Click Finish The IDE then creates a skeleton CalculatorwsS java file for t
67. ET 2 0 and 3 0 frameworks to non default locations Running the AddNumbers Client After the client has been built run the client by following these steps 1 Atacommand prompt navigate the location where you extracted the exam ple bundle 2 Enter the following command CREATING A WCF CLIENT 145 Client exe You will see the following output Adding 10 and 20 Result is 30 Adding 10 and 20 Exception Negative numbers can t be added 146 ACCESSING WSIT SERVICES USING WCF CLIENTS 9 Data Contacts Tas chapter describes guidelines for e Designing a XML schema exposed by a web service starting from Java e Consuming a WCF service generated WSDL XML schema when design ing a Java client or Java web service e Developing a Microsoft WCF client A WSIT client service uses JAXB 2 0 for XML serialization generating XML schemas from Java classes and generating Java classes from XML schemas A WCE client service uses either Xm1Serializer or DataContractSerializer for like tasks JAXB 2 0 and the WCF XML serialization mechanisms differ in two fundamental ways First JAXB 2 0 supports all of XML schema NET s DataContractSerializer and XmlSerializer support different XML schema sets Second WCF s XMLSerializer DataContractSerializer and JAXB 2 0 differ in their mapping of programming language datatypes to XML Schema constructs As a result a XML schema generated from a programming language on one platform and consumed
68. Each individual WSIT technology such as Reliable Messaging Addressing or Secure Conversation provides a set of policy assertions it can process Those assertions provide the necessary configuration details to the WSIT run time to enable proper operation of the WSIT features used by a given web service The assertions may specify particular configuration settings or rely on default set tings that are pre determined by the specific technology For instance in the snippet shown below the wsrm AcknowledgementInterval and wsrm Inac tivityTimeout settings are both optional and could be omitted The following snippet shows WS Policy assertions for WS Addressing and WS Reliable Mes saging lt wsp Policy wsu Id AddNumbers_policy gt lt wsp Exact1yOne gt lt wsp Al1 gt lt wsaw UsingAddressing gt lt wsrm RMAssertion gt 126 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS lt wsrm InactivityTimeout Mi11liseconds 600000 gt lt wsrm AcknowledgementInterval Milliseconds 200 gt lt wsrm RMAssertion gt lt wsp Al1 gt lt wsp Exact1yOne gt lt wsp Policy gt This snippet is valid in either a WSIT configuration file wsit lt pack age gt lt service gt xm1 or in a Web Services Description Language WSDL file This snippet is from the WSIT configuration file in the example wsit enabled fromjava etc wsit fromjava server AddNumbersImp1 xml Creating a Web Service You can create a web service starting from Java cod
69. IES WORK How Secure Conversation Works Figure 1 11 shows how the Web Services Secure Conversation technology establishes a secure conversation when the Trust technology is not used Client Authenticates to the Service Web Client Service Service Authenticates to Client Figure 1 11 Secure Conversation To establish a secure conversation between a Client and a web service 1 The client sends a X509 Certificate to authenticate itself to the web service 2 The web service sends a X509 Certificate to authenticate itself to the client All communication uses SOAP messages 22 INTRODUCTION 2 WSIT Example Using a Web Container and NetBeans Tiss chapter describes how to use NetBeans IDE and GlassFish to build and deploy a web service and client that use WSIT technologies It includes exam ples of the files that the IDE helps you create and examples of the build directo ries and the key files that the IDE produces to create a web service and a client This chapter covers the following topics Registering GlassFish with the IDE page 23 Creating a Web Service page 24 Configuring WSIT Features in the Web Service page 26 Deploying and Testing a Web Service page 28 Creating a Client to Consume a WSIT Enabled Web Service page 29 Registering GlassFish with the IDE Before you create the web service perform the following steps to register Glass fish with the IDE 23 24 WSIT EXAM
70. InC Result result catch Exception ex TODO handle custom exceptions here out printIn lt body gt out printin lt htm1 gt out closeQ 16 Change the value for int i and int j to other numbers such as 3 and 4 17 Change the System out print1n statement to out printIn 18 Add a line that prints out an exception if an exception is thrown The try catch block should look as follows new and changed lines are highlighted in bold text try Call Web Service Operation org me calculator client CalculatorWS port service getCalculatorWSPort TODO initialize WS operation arguments here int i 3 int j 4 TODO process result here int result port add i j 42 MESSAGE OPTIMIZATION out printin lt p gt Result result catch Exception ex out printIn lt p gt Exception ex 19 Right click the project node and choose Run Project The server starts if it was not running already the application is built and deployed and the browser opens and displays the calculation result You have successfully created and deployed a client that can access a web ser vice with message optimization enabled Message Optimization and Secure Conversation The Web Services Secure Conversation technology has message optimization benefits While providing better message level security it also improves the effi ciency of multiple message exchanges It accomplishes this by pro
71. Java code 24 Web Service Attributes editor 38 web services attributes editing 48 51 57 81 94 95 securing 48 Web Services Description Language See WSDL 33 Web Services Interoperability Technolo gy 2 See WSIT 7 Web services trust description 6 Windows Communication Foundation See WCF 6 WSDL 3 9 33 wsimport 3 WSIT 3 and Indigo 6 description 2 joint testing 7 platform 7 Web service 7 WS Metadata Exchange protocol 9 WS Secure Conversation 6 WS Security configuring 48 51 81 95 WS Trust configuring 48 51 81 95 X XML Infoset 11
72. PLE USING A WEB CONTAINER AND NETBEANS Start the IDE and choose Tools Server Manager from the main window The Server Manager window appears Click Add Server Select the Sun Java System Application Server assign a name to server instance and click Next The platform folder location win dow appears Specify the platform location of the server instance and the domain to which you want to register and click Finish The Server Manager window appears Enter the server username and password that you supplied when you installer the web container the default is admin adminadmin and click Close Creating a Web Service The starting point for developing a web service to use the WSIT technologies is a Java class file annotated with the javax jws WebService annotation The WebService annotation defines the class as a web service endpoint The follow ing Java code shows a web service The IDE will create most of this Java code for you package org me calculator import javax jws WebService import javax jws WebMethod import javax jws WebParam WebService public class Calculator WebMethod action Samp1e_operation public String operation WebParam name param_name String param implement the web service operation here return param WebMethod action add public int add WebParam name i int i WebParam name j int j int k i j return k CREATING A WEB SERVIC
73. System Runtime Serialization IExtensibleDataObject private System Runtime Serialization ExtensionDataObject extensionDataField private System DateTime orderDateField public System Runtime Serialization ExtensionDataObject ExtensionData get return this extensionDataField set this extensionDataField value public System DateTime orderDate get return this orderDateField set this orderDateField value C code fragment purchaseOrder tmpP new purchaseOrder tmpP orderDate System DateTime Now UUID Guideline Use Leach Salz variant of UUID at runtime WEB SERVICE START FROM JAVA 159 java util UUID maps to schema type xs string NET maps xs string to System string The constructors in java util UUID allow any variant of UUID to be created Its methods are for manipulation of the Leach Salz variant Example Mapping UUID Java code fragment public class ReportUid public java util UUID uuid Schema fragment lt xsS complexType name reportUid gt lt xsS Sequence gt lt xs element name uuid type xs string minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema public partial class reportUid object System Runtime Serialization IExtensibleDataObject private System Runtime Serialization ExtensionData0bject extensionDataField private string uuidField public System Runtime Serialization Extens
74. To set the transaction attributes for the Samp1eService war web service a In the Projects tab open the SampleService war project b Open the Web Services node c Right click Simple and select Edit Web Service Attributes d Select the WSIT tab and open the Operation node and then the method node in each section Select the indicated setting for each of the following operations from the Transaction pulldown e Set init to Required e Set publishRequired to Required e Set publishSupports to Supported e Set verify to Required 190 USING ATOMIC TRANSACTIONS Figure 10 3 shows how this is done for the publishRequi red oper ation Username Authenticatio ame authentication with symmetric keys for integrity and c tion O Allow TCP Transport Allow East Infoset 08 init Operation Operation Input Message Output Message 0A publishRequired Operation Operation Transaction Required vi Not Supported Input Mes Mandatory Required Figure 10 3 Setting the Transaction Attribute for the publi shRequi red Method e Click OK Transaction attributes for SampleServiceASCMTEJB do not need to be set EJB 3 0 transaction attributes are used 7 Deploy the SampleService web service Right click SampleService and select Deploy Project NetBeans will start domain1 and deploy the webservice to that domain 8 Register the Sam
75. USTSTORE supplied by the users You can also specify the passwords for keystores and truststores by specifying a Cal backHand ler class that implements the javax security auth callback CallbackHandler interface in the Keystore Password Truststore Password or Key Password fields e Load Aliases Click this button to populate the Alias list with all of the certificates available in the selected keystore This option will only work if the truststore location and password are correct e Truststore Alias Select the alias of the server certificate and private key in the client truststore Refer to the table in Specifying Aliases with the Updated Stores page 76 to determine which alias is appropriate for the selected security mechanism 8 When the certificates are configured as suggested for some of the examples in this chapter the dialog will look like this CalculatorwSService x WSIT Configuration WSDL Customization Transport Certificates keystore Location _ Sun glassfish domains domaini configikeystore ks Browse Keystore Password Keystore Alias fows security server Load Aliases H Key Password Truststore Location Ic Sun glassfish damains domain1 config cacerts jks Browse Truststore Password g TERANSE Truststore Alias l xws security server x Load Aliases Username Authentication Secure Token Service OK Cancel Help
76. X Example Complete the following steps to configure your environment then build deploy and run the basicWSTX example 1 Download the sample kit for this example from https wsit docs dev java net releases m6 wsittutorial zip 2 Ensure that properties that point to your local GlassFish and WSIT Tuto rial installations have been set a Copy file lt INSTALL gt wsittutorial examples bp project app server properties sample to file lt INSTALL gt wsittutorial exam ples bp project app server properties b Set the javaee home and wsit tutorial home properties in the file lt INSTALL gt wsittutorial examples bp project app server properties c Ensure that GlassFish and Ant 1 6 5 or higher have been installed and are on the path GlassFish includes Ant 1 6 5 which can be found in the lt javaee home gt 1lib ant bin directory 3 Set up your environment to run the basicWSTX example This step performs the following configuration tasks for you e Starts domain1 e Creates the resources jms Queue and XATransaction jms Connec tionFactory used in the example e Creates and sets up two GlassFish domains The domains can either be created on one machine or on two different machines We ll show you how to do it on one machine The first domain domain is created as part of the GlassFish installation e Establishes trust between the two domains by installing each domain s slas security certificate in the other domain
77. Xm1SchemaType for a strongly typed binding of XMLGregorianCalendar to one of the XML schema calendar types WEB SERVICE START FROM JAVA 157 Example Xm1GregorianCalendar without Xm1SchemaType Java code fragment public class PurchaseOrder public javax xml datatype XMLGregorianCalendar orderDate Schema fragment lt xsS complexType name purchaseOrder gt lt xS Sequence gt lt xs element name orderDate type xs anySimpleType minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema public partial class purchaseOrder private string orderDateField public string orderDate get return this orderDateField set this orderDateField value C code fragment purchaseOrder tmpP new purchaseOrder tmpP orderDate System Xm1 Xm1Convert ToString System DateTime Now System Xml1 Xm 1DateTimeSerializerMode RoundtripKind 158 DATA CONTRACTS Example XMLGregorianCalendar with Xm1SchemaType Java code fragment public class PurchaseOrder Xm1SchemaType name dateTime public javax xml datatype XMLGregorianCalendar orderDate Schema fragment lt xs complexType name purchaseOrder gt lt xsS Sequence gt lt xs element name orderDate type xs dateTime minOccurs 0 gt lt xsS Sequence gt lt xs complexType gt INET auto generated code from schema public partial class purchaseOrder object
78. abled Web Service page 29 NOTE Whenever you make changes on the service refresh the client so that the client will pick up the change To refresh the client right click the node for the Web Service Reference for the client and select Refresh Cli ent Expand the node for the web service client CalculatorWSServletClient Expand the node for Web Service References Right click on CalculatorWSService select Edit Web Service Attributes Select the WSIT Configuration tab of the CalculatorWSService dialog Provide the client s private key by pointing to an alias in the keystore To do this a Expand the Certificates node b Click the Load Aliases button for the keystore c Select xws security client from the Alias list Provide the server s certificate by pointing to an alias in the client trust store To do this from the Certificates node a Click the Load Aliases button for the truststore b Select xws security server from the Alias list c Click OK to close this dialog In the tree drill down from the project to Source Packages gt META INF Double click on CalculatorWSService xml and verify that lines similar to the following are present EXAMPLE TRANSPORT SECURITY SSL 103 lt wsp Al1 gt lt wsaws UsingAddressing xmlns wsaws http www w3 org 2006 05 addressing wsd1 gt lt sc KeyStore wspp visibility private location C Sun glassfish domains domainl config keystore jks sto
79. age exchanges when reliable messaging is enabled Web Service Client Web sereen JAX WS 4 Client Runtime Server Runtime RM Source Create Sequence Handshake Module Application Message Sequence RM g Destination e Application Message Module Acknowledgements Sequence Figure 1 8 Application Message Exchange with Reliable Messaging Enabled With reliable messaging enabled the Reliable Messaging source module is plugged into the JAX WS web service client The source module transmits the application messages and keeps copies of the messages until their receipt is acknowledged by the destination module via the exchange of protocol messages The destination module acknowledges messages and optionally buffers them for ordered delivery guarantee After guaranteeing order if configured the destina 18 INTRODUCTION tion module allows the messages to proceed through the JAX WS dispatch for delivery to the endpoint or application destination How Secunty Works The following sections describe how the WSIT security technologies security policy trust and secure conversation work How Security Policy Works The WSIT Web Service Security Policy implementation builds on the features provided by the Web Service Policy implementation in WSIT It enables users to use XML elements to specify the security requirements of a web service end point that is how messages are secured on the communication path between the client and the
80. age handles the following e Defines an XML based envelope to describe what is in the message and how to process the message e Includes XML based encoding rules to express instances of applica tion defined data types within the message e Defines an XML based convention for representing the request to the remote service and the resulting response WSIT SPECIFICATIONS 11 In SOAP 1 2 implementations web service endpoint addresses can be included in the XML based SOAP envelope rather than in the transport header for example in the HTTP transport header thus enabling SOAP messages to be transport independent Web Services Addressing The Java APIs for W3C Web Services Address ing were first shipped with Java Web Services Developer s Pack 2 0 JWSDP 2 0 This specification defines a set of abstract properties and an XML Infoset representation that can be bound to a SOAP message so as to reference web services and to facilitate end to end addressing of endpoints in messages A web service endpoint is an entity processor or resource that can be referenced and to which web services messages can be addressed Endpoint references convey the information needed to address a web service endpoint The specification defines two constructs message addressing properties and endpoint references that normalize the informa tion typically provided by transport protocols and messaging systems in a way that is independent of any particular transport
81. ags the web service has been deployed and is working If not check the web container log for any error messages CREATING A WEB SERVICE CLIENT 135 related to the sample WAR you have just deployed For GlassFish the log can be found at lt AS_HOME gt domains domain1 logs server log For Apache Tom cat the appropriate log file can be found at lt TOMCAT_HOME gt logs cat alina out Creating a Web Service Client Unlike developing a web service provider creating a web service client applica tion always starts with an existing WSDL file This process is similar to the pro cess you use to build a service from an existing WSDL file The WSDL file that the client consumes already contains the WS policy assertions and in some cases any value added WSIT policy assertions that augment Sun s implementa tion but can safely be ignored by other implementations Most of the policy assertions are defined in the WS specifications Sun s implementation pro cesses these standard policy assertions The policy assertions describe any requirements from the server as well as any optional features the client may use The WSIT build tools and run time environ ment detect the WSDL s policy assertions and configure themselves appropri ately if possible If an unsupported assertion is found an error message describing the problem will be displayed Typically you retrieve the WSDL directly from a web service provider using the wsimport too
82. akes assertions based on evidence that it trusts to whoever trusts it or to specific recipients To communicate trust a service requires proof such as a signature to prove knowledge of a security token or set of security tokens A ser vice itself can generate tokens or it can rely on a separate STS to issue a security token with its own trust statement note that for some security token formats this can just be a re issuance or co signature This forms the basis of trust brokering The issued token security model includes a target server a client and a trusted third party called a Security Token Service STS Policy flows from server to client and from STS to client Policy may be embedded inside an issued token assertion or acquired out of hand There may be an explicit trust relationship between the server and the STS There must be a trust relationship between the client and the STS CREATING A THIRD PARTY STS When the web service being referenced by the client uses any of the STS secu rity mechanisms refer to table in Summary of Service Side Configuration Requirements page 52 an STS must be specified You can specify the STS in one of these ways e On the service side specify the endpoint of the Issuer element and or spec ify the Issuer Metadata Exchange Mex address of the STS If you need to create a third party STS follow the steps in Creating a Third Party STS page 91 If you already have an STS that you want to
83. allback HOK_ASSERTION_TYPE sam1Callback setAssertionElement createHOKSAMLASsertion hokAssertion_sam110 sam1Callback getAssertionElementQ sam1Callback setAssertionElement createHOKSAMLASsertion20 hokAssertion_sam120 sam1Callback getAssertionElementQ catch Exception e e printStackTraceQ else throw unsupportedCallback SECURITY MECHANISMS 61 Secunty Mechanisms The following lists the possible choices for security mechanisms These mecha nisms are discussed in the following sections e Username Authentication with Symmetric Keys page 61 e Mutual Certificates Security page 62 e Transport Security SSL page 62 e Message Authentication over SSL page 64 e SAML Authorization over SSL page 64 e Endorsing Certificate page 65 e SAML Sender Vouches with Certificates page 65 e SAML Holder of Key page 66 e STS Issued Token page 66 e STS Issued Token with Service Certificate page 67 e STS Issued Endorsing Token page 67 A table that summarizes the configuration options on the server side is available in Summary of Service Side Configuration Requirements page 52 Usemame Authentication with Symmetric Keys The Username Authentication with Symmetric Keys mechanism protects your application for integrity and confidentiality Symmetric key cryptography relies on a single shared secret key that is used to both sign and encrypt a message Symmetric keys a
84. an intermediary Further it enables message optimization to be done in a binding indepen dent way 12 INTRODUCTION Reliable Messaging Specifications Reliability is measured by a system s ability to deliver messages from point A to point B without error Figure 1 5 shows the specifications that were imple mented to ensure reliable delivery of messages between two web services end points Web Services Atomic Transactions Reliability Standards Supporting Web Services Web Services Web Services Standards Security Policy Addressing Core XML XML Standards Infoset Schema Figure 1 5 Reliable Messaging Specifications In addition to the Core XML specifications and supporting standards Web Ser vices Security and Web Services Policy which are required building blocks the reliability feature is implemented using the following specifications e Web Services Reliable Messaging This specification defines a standardized way to identify track and manage the reliable delivery of messages between exactly two parties a source and a destination so as to recover from failures caused by messages being lost or received out of order The specification is also extensible so it allows additional functionality such as security to be tightly integrated The implementation of this specification integrates with and complements the Web Services Security and the Web Services Policy implementations e Web Services Coordinat
85. andlers page 59 e STS If this column indicates YES you must have a Security Token Ser vice that can be referenced by the service An example of an STS can be found in the section Creating and Securing the STS STS page 117 The STS is secured using a separate non STS security mechanism The secu rity configuration for the client side of this application is dependent upon SUMMARY OF CLIENT SIDE CONFIGURATION REQUIREMENTS the security mechanism selected for the STS and not on the security mech anism selected for the application e SSL To use a mechanism that uses secure transport SSL you must con figure the system to point to the client and server keystore and truststore files Steps for doing this are described in Configuring SSL For Your Applications page 69 e User in Glassfish To use a mechanism that requires a user database for authentication you can add a user to the file realm of GlassFish Instruc tions for doing this can be found at Adding Users to GlassFish page 72 Configuring Usemame Authentication on the Client On the client side a user name and password must be configured for some of the security mechanisms For this purpose you can use the default Username and Password Callback Handlers when deploying to GlassFish specify a SAML Callback Handler specify a default user name and password for development purposes create and specify your own Callback Handlers if the container you are using does n
86. ass PurchaseReport public javax xml datatype Duration period Schema fragment lt xs complexType name purchaseReport gt lt xsS Sequence gt lt xs element name period type xs duration minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema Using svcutil exe serializer DataContractSerializer lt wsdl file gt public partial class purchaseReport object System Runtime Serialization IExtensibleDataObject private System TimeSpan periodField vanne other gernerated code public System TimeSpan period get return this periodField set this periodField value C code fragment purchaseReport tmpR new purchaseReport tmpR period new System TimeSpan MaxValue Example Mapping xs duration using Xm1Serializer NET auto generated code from schema Using svcutil exe serializer XmlSerializer lt wsdl file gt public partial class purchaseReport private string periodField public string period 154 DATA CONTRACTS get return this periodField set this periodField value C code fragment purchaseReport tmpR new purchaseReport tmpR period System Xm1 Xm1Convert ToString new System TimeSpan 23 0 Binary Types java awt Image javax xml transform Source and javax activa tion DataHandler map to xs base64Binary NET maps xs base64Binary to byte JAXB 2 0 provides
87. ated code from schema public class ocPerson private String name private double age private System Xm1 XmlAttribute anyAttrField lt public String name public double age public System Xm1 XmlElement anyAttr get return this anyAttrField set this anyAttrField value Enum Type A Java enum type maps to an XML schema type constrained by enumeration fac ets This in turn binds to NET type enum type WEB SERVICE START FROM JAVA 175 Example Java enum gt xs simpleType with enum facets gt NET enum Java code fragment public enum USState MA NH Schema fragment lt xs simpleType name usState gt lt xsirestriction base xs string gt lt xs enumeration value NH gt lt xs enumeration value MA gt lt xsirestriction gt lt xs simpleType gt NET auto generated code from schema public enum usState NH MA Package The following package level JAXB annotations are relevant from an interopera bility standpoint e Xm1Schema customizes the mapping of package to XML namespace e Xm1SchemaType customizes the mapping of XML schema built in type The Xm1SchemaType annotation can also be used at the property field level as was seen in the previous example XMLGregorianCalendar page 156 XmiSc hema A package is mapped to an XML namespace The following attributes of the XML namespace can be customized using the Xm1Sche
88. ated in the previous section This web service is secured using the security mechanism described in SAML Authorization over SSL page 64 To add security to the client that references this web service complete the fol lowing steps 1 For this example we are using a non JSR 109 compliant client for variety To do this create the client application up to the step where you create the Servlet step 7 as of this writing by following the steps described in Cre ating a Client to Consume a WSIT Enabled Web Service page 29 with the following exceptions a In the step where you are directed to cut and paste the URL of the web service that you want the client to consume into the WSDL URL field enter https lt fully qual ified hostname gt 8181 CalculatorAp plication CalculatorWSService wsdl to indicate that this client should reference the web service using the secure port The first time you access this service accept the certificate slas when you are prompted This is the server certificate popping up to confirm its identity to the client In some cases you might get an error dialog telling you that the URL https lt fully qualified hostname gt 8181 CalculatorAppli cation CalculatorWSService wsd1 couldn t be downloaded How ever this the correct URL and it does load when you run the service So when this error occurs repeat the steps that create the Web Service Client using the secure WSDL The second time the web servic
89. available to sign and or encrypt before clicking the Add Header button include To Addressing From Addressing FaultTo Addressing ReplyTo Addressing MessageID Addressing RelatesTo Addressing and Action Addressing After clicking Add Header and then clicking All Headers you may also specify AckRequested RM SequenceAcknowl edgement RM and Sequence RM 14 There are no XPath elements displayed by default Click Add XPath to add rows that enable you to specify signature and or encryption for an XPath expression or a URI which indicates the version of XPath to use By default the Required field is selected This is an editable field Double click on the XPath row to specify the XPath expression or URI Only one XPath element is allowed NOTE There is a limitation when specifying XPath elements To use XPath elements switch off Optimize Security manually by adding the disableStreamingSecurity policy assertion For information on how to do this refer to http blogs sun com venu for more information on disableStreamingSecurity 15 To remove an element select it in the Message Part section and then click Remove to remove it from message security 16 Click OK to save these settings Supporting Token Options The following are choices for supporting tokens Username Token A username token is used to identify the requestor by their username and optionally using a password or shared secret or password equi
90. ces refreshed to get new web service attributes To refresh the client web service references for this example a c In the Projects tab open the SampleServiceClient then open Web Ser vice References Right click SimpleService and select Refresh Client to refresh the client node and regenerate the WSDL for the simpleServlet Right click SimpleAsCMTE b to do the same for the CMT EJB client Deploy and Run the client Right click SampleClient and select Run Project NetBeans will start domain2 deploy the servlet and EJB CMT clients to that domain then dis 192 USING ATOMIC TRANSACTIONS play the results for both in a pop up browser window as shown in Figure 10 4 WS TX Simple Client ee ww ey v http flocalhost 1852 SampleClien v MA Xx Google 2 H we amp Gws 7x Simple Clent Tama i gt Bl ab peace v G Toos a WS TX Simple Client Calling WS TX Simple Web Service implemented as Servlet Finished publishedRequired Sent 3 message s verified 3 message s sent Finished publishSupports invocation Pass verified rolled back messages not sent Calling WS TX Simple Web Service implemented as CMT EJB Finished publishedRequired Sent 3 message s verified 3 message s sent Finished publishSupports invocation Pass verified rolled back messages not sent Figure 10 4 basicWSTX Results A Advanced Configuration page 48 51 81 95 aliase
91. code generated by svcutil public partial class purchaseOrder private purchaseOrderItem itemField System Xm1 Serialization XmlElementAttributeC item Form System Xm1 Schema Xm1SchemaForm Unqualified IsNullable true Order Q public purchaseOrderItem item get return this itemField set this itemField value NET auto generated code from schema public partial class purchaseOrderItem private string productNameField public string productName get return this productNameField set this productNameField value Xmilype xs all Guideline Avoid using Xm1Type propOrder Xm1Type propOrder maps a Java class to a XML Schema complex type with xs all content model Since XML Schema places severe restrictions on xsiall the use of Xm1Type propOrder is therefore not recommended So the following example shows the mapping of a Java class to xs al1 but the corresponding NET code generated by svcutil is omitted WEB SERVICE START FROM JAVA 171 Example Mapping a class to xs al1 using XmlType Java code fragment Xm1Type propOrder public class USAddress public String name public String street Schema fragment lt xs complexType name USAddress gt lt xs all gt lt xs element name name type xs string gt lt xs element name Street type xs string gt lt xsiall gt lt xs complexType gt XmiType simple content Gui
92. d Select Secure Service From the drop down list for Security Mechanism select STS Issued Token Select the Configure button For Algorithm Suite select Basic128 bit For Key Size select 128 Select OK to close the configuration dialog the algo rithm suite value of the service must match the algorithm suite value of the STS NOTE If you have configured Unlimited Strength Encryption as described in Creating a Third Party STS page 91 you can leave the key size at 256 Otherwise you must set it to 128 EXAMPLE STS ISSUED TOKEN STS 117 8 Click OK to exit the WSIT Configuration editor A new file is added to the project To view the WSIT configuration file expand Web Pages WEB INF then double click the file wsit org me calculator Calculatorws xm1 9 Right click the CalculatorApplication node and select Run Project This step compiles the application and deploys it onto GlassFish A browser will open and display the WSDL file for the application 10 Follow the steps for creating and securing the Security Token Service as described in the next section Creating and Securing the STS STS To create and secure a Security Token Service for this example follow these steps 1 Create a new project for the STS by selecting File gt New Project Select Web then Web Application then Next Enter MySTSProject for the Project Name Click Finish Right click the MySTSProject node select New then click
93. deline A class can be mapped to a complexType with a simpleContent using Xm1Value annotation NET binds the Java property annotated with Xm1Value to a property with name value Example Class to comp1exType with simp1leContent Java code fragment public class InternationalPrice XmlValue public java math BigDecimal price XmlAttribute public String currency Schema fragment lt xs complexType name internationalPrice gt lt xs simpleContent gt lt xsS extension base xs decimal gt 172 DATA CONTRACTS xS attribute name currency type xs string gt lt xs extension gt lt xs simpleContent gt lt xs complexType gt NET auto generated code from schema public partial class internationalPrice private string currencyField private decimal valueField public string currency get return this currencyField set this currencyField value public decimal Value get return this valueField set this valueField value Open Content JAXB 2 0 supports the following annotations for defining open content Open content allows content not statically defined in XML schema to occur in an XML instance e XmlAnyElement which maps to xs any which binds to NET type Sys tem Xml XmlElement e XmlAnyAttribute which maps to xs anyAttribute which binds to NET type System Xml XmlAttribute Example Using XmlAnyE lement for open content
94. ding UTF 8 standalone yes gt lt bindings xmIns xsd http www w3 org 2001 XMLSchema xmIns wsdl http schemas xmlsoap org wsd1 wsdl Location http localhost 8080 wsit enabl ed fromjava addnumbers wsd1 xmIns http java sun com xml ns jaxws gt lt bindings node wsd1 definitions gt lt package name fromjava client gt lt bindings gt lt bindings gt 138 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS Creating a Client from WSDL To create a client from WSDL you must create the following files e Client Java File fromwsdl page 138 e Client Configuration File fromwsdl page 138 e build xml e build properties The build xml and build properties files are standard in any Ant build envi ronment Examples of these files are provided in the fromwsd1 sample directory Client ava File fromwsdl The client Java file defines the functionality of the web service client The same client java file is used with both samples wsit enabled fromjava and wsit enabled fromwsd1 For more information on this file see Client Java File fromjava page 136 Client Configuration File fromwsdl This is a sample custom client xm1 file The wsd1Location package name and jaxb package name xml tags are unique to each client and are highlighted in bold text lt xml version 1 0 encoding UTF 8 standalone yes gt lt bindings xmIns xsd http www w3 org 2001 XMLSchema xmIns jaxb http java sun
95. e Tomcat Apache Tomcat also has an autoDep1oy feature that is enabled by Tomcat s out of the box configuration settings If you are not sure whether the autoDep1oy is enabled check lt TOMCAT_HOME gt conf server xml for the value of autoDep1oy Assuming autoDeploy is enabled you simply copy your application s WAR file to the lt TOMCAT_HOME gt webapps directory The build xml file which accompanies this example has a deploy target for Tomcat To invoke that target run the following command in the top level direc tory of the respective examples either wsit enabled fromjava or wsit enabled fromwsd1 as follows You need to use the Duse tomcat true switch to make sure that the application is deployed to Tomcat and not to the default server which is GlassFish ant Duse tomcat true deploy Venfying Deployment A basic test to verify that the application has deployed properly is to use a web browser to retrieve the application s WSDL from its hosting web container The following URLs retrieve the WSDL from each of the two example services If you are running your web browser and web container on different machines you need to replace localhost with the name of the machine hosting your web ser vice Note Before testing make sure your web container is running e http localhost 8080 wsit enabled fromjava addnumbers wsd1 e http localhost 8080 wsit enabled fromwsd1 addnumbers wsd1 If the browser displays a page of XML t
96. e being lost in transit e Application messages are arriving at their destination out of order and ordered delivery is a requirement To help decide whether or not to use reliable messaging weigh the following advantages and disadvantages e Enabling reliable messaging ensures that messages are delivered exactly once from the source to the destination and if the ordered delivery option is enabled ensures that messages are delivered in order e Enabling reliable messaging causes a degradation of web service perfor mance especially if the ordered delivery option is enabled e Non reliable messaging clients cannot interoperate with web services that have reliable messaging enabled For instructions on how to use the Reliable Messaging technology see Chapter 5 6 INTRODUCTION Security Technology Until now web services have relied on transport based security such as SSL to provide point to point security WSIT implements WS Security so as to provide interoperable message content integrity and confidentiality even when messages pass through intermediary nodes before reaching their destination endpoint WS Security as provided by WSIT is in addition to existing transport level security which may still be used WSIT also enhances security by implementing WS Secure Conversation which enables a consumer and provider to establish a shared security context when a multiple message exchange sequence is first initiated Subsequent messages
97. e of an STS can be found in the section Creating and Securing the STS STS page 117 In this section you select a security mechanism for the STS The security configuration for the client side of this application is dependent upon the security mechanism selected for the STS and not on the security mechanism selected for the application The client trust store must contain the certificate of the STS which has the alias of wssip if you are using the updated GlassFish certificates Configuring SSLand Authonzed Users This chapter discusses configuring security for your web service and web service client using the WSIT security mechanisms Some of these mechanisms require some configuration outside of NetBeans IDE Depending upon which security mechanism you plan to use some of the following tasks will need to be com pleted e If you are using the GlassFish container and message security you must update the GlassFish keystore and truststore by importing v3 certificates The procedure for updating the certificates is described in Updating Glass Fish Certificates page 74 e If you are using a security mechanism that requires a user to enter a user name and password create authorized users for your container Steps for creating an authorized user for the GlassFish container are described in Adding Users to GlassFish page 72 CONFIGURING SSL FOR YOUR APPLICATIONS e To use a mechanism that uses secure transport SSL you must configure
98. e of an optional minOccurs 0 but not nillable element This in turn binds to NET type int This is more devel oper friendly However when marshalling JAXB will marshal a null value within the List lt Integer gt as a value that is absent from the XML instance Example Collection to a list of optional elements Java code fragment Xm1RootE 1ement name po public PurchaseOrder Xm1Element nillable false public List lt Integer gt items Schema fragment lt xs element name po type purchaseOrder gt lt xs complexType name purchaseOrder gt lt xsS sequence gt lt xs element name items type xs int minOccurs 0 maxOccurs unbounded gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema partial class purchaseOrder private int itemsField public int items get return this itemsField set this itemsField value List of values A collection such as List lt Integer gt can be mapped to a list of XML values i e a XML schema list simple type using annotation Xm1List NET maps list simple type to a NET System string WEB SERVICE START FROM JAVA 163 Example Collection to a list of values using Xm1List Java code fragment Xm1RootE1ement name po public PurchaseOrder XmlList public List lt Integer gt items Schema fragment lt xs element name po type purchaseOrder
99. e or starting from a WSDL file The following sections describe each approach e Creating a Web Service From Java page 126 e Creating a Web Service From WSDL page 129 Creating a Web Service From Java One way to create a web service application is to start by coding the endpoint in Java If you are developing your Java web service from scratch or have an exist ing Java class you wish to expose as a web service this is the most direct approach The Java API for XML Web Services JAX WS 2 0 JSR 224 relies heavily on the use of annotations as specified in A Metadata Facility for the Java Programming Language JSR 175 and Web Services Metadata for the Java Platform JSR 181 as well as additional annotations defined by the JAX WS 2 0 specification The web service is written as a normal Java class Then the class and its exposed methods are annotated with the web service annotations WebService and Web Method The following code snippet shows an example WebService public class AddNumbersImp 1 WebMethod action addNumbers public int addNumbers int numberl1 int number2 throws AddNumbersException CREATING A WEB SERVICE 127 if Cnumberl lt number2 lt Q throw new AddNumbersException Negative number cant be added Numbers number1 number2 return numberl number2 When developing a web service from scratch or based on an existing Java class WSIT features are enabled usin
100. e refer ence is created and you can continue creating the client b EXAMPLE SAML AUTHORIZATION OVER SSL SA 109 NOTE If you prefer to use localhost in place of the fully qualified hostname FQHN in this example you must follow the steps in Trans port Security SSL Workaround page 63 Name the application CalculatorClient since it s not a servlet Instead of creating a client servlet as is described in Creating a Client to Consume a WSIT Enabled Web Service page 29 we are just going to add the web service operation to the generated index jsp file to create a non JSR 109 client To do this a d If the index jsp file is not open in the right pane double click it to open it Drill down through the Web Service References node until you get to the add operation Drag the add operation to the line immediately following the following line lt h1 gt JSP Page lt h1 gt Edit the values for i and j if you d like Write a SAMLCallback handler for the client side to populate a SAML assertion into the client s request to the service A suggested method for creating the SAMLCal1backHandler is shown below woa meoenunaewm ee e Boa SS Right click on the CalculatorClient node Select New Java Package For Package Name enter xwss saml Click Finish Drill down from CalculatorClient Source Packages xwss saml Right click on xwss saml Select New gt File Folder Fr
101. e war targets in the wsit enabled fromwsd1 build xm1 file Deploying the Web Service to a Web Container As a convenience invoking the ant server command builds the web service s WAR file and immediately deploys it to the web container However in some sit uations such as after undeploying a web service it may be useful to deploy the web service without rebuilding it For both scenarios wsit enabled fromjava and fromwsd1 the resulting appli cation is deployed in the same manner The following sections describe how to deploy on the different web containers e Deploying to GlassFish page 133 e Deploying to Apache Tomcat page 134 Deploying to GlassFish For development purposes the easiest way to deploy is to use the autodeploy facility of the GlassFish application server To do so you simply copy your application s WAR file to the autodeploy directory for the domain to which you want to deploy If you are using the default domain domain1 which is set up by the GlassFish installation process the appropriate directory path would be lt AS_HOME gt domains domain1 autodep1oy 134 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS The build xml file which accompanies this example has a deploy target for GlassFish To invoke that target run the following command in the top level directory of the respective examples either wsit enabled fromjava or wsit enabled fromwsd as follows ant deploy Deploying to Apach
102. e web service s URL The snippet shown below illustrates how to enable the WSIT Reliable Messaging technology in a WSDL file lt wsp Policy wsu Id AddNumbers_policy gt lt wsp ExactlyOne gt lt wsp Al I gt lt wsrm RMAssertion gt lt wsrm InactivityTimeout Milliseconds 600000 gt lt wsrm AcknowledgementInterval Milliseconds 200 gt lt wsrm RMAssertion gt lt wsp Al1 gt lt wsp Exact1yOne gt lt wsp Policy gt BUILDING AND DEPLOYING THE WEB SERVICE 131 For a complete example of a WSDL file see the AddNumbers wsd1 in the from wsdl example Another benefit of AddNumbers wsd1 file is that it shows how a WSIT enabled WSDL is constructed Therefore you can use it as a reference when you create a WSDL file or modify an existing one Web Service Implementation File The following file AddNumbersImp1 java shows how to implement a web service interface package fromwsd 1 server import javax jws WebService import javax jws WebMethod WebService endpointInterface fromwsdl server AddNumbersPortType public class AddNumbersImp1 WebMethod action addNumbers public int addNumbers int numberl1 int number2 throws AddNumbersFault_Exception if Cnumberl lt number2 lt Q String message Negative number cannot be added String detail Numbers numberl number2 AddNumbersFault fault new AddNumbersFault fault setMessage message fault setFaultInfo detail throw n
103. e web service reference is created and you can continue creating the client Adding Users to GlassFish The following topics are covered e Adding Users to GlassFish Using Admin Console page 72 e Adding Users to GlassFish From Command Line page 73 Adding Users to GlassFish Using Admin Console To add users to GlassFish using the Admin Console follow these steps 1 Start GlassFish if you haven t already done so ADDING USERS TO GLASSFISH 73 2 Start the Admin Console if you haven t already done so You can start the Admin Console by starting a web browser and entering the URL http localhost 4848 asadmin If you changed the default Admin port during installation enter the correct port number in place of 4848 3 To log in to the Admin Console enter the user name and password of a user in the admin realm who belongs to the asadmin group The name and password entered during installation will work as will any users added to this realm and group subsequent to installation Expand the Configuration node in the Admin Console tree Expand the Security node in the Admin Console tree Expand the Realms node Select the file realm Click the Manage Users button Click New to add a new user to the realm O AON DN Enter the correct information into the User ID Password and Group s fields The example applications reference a user with the following attributes a User ID wsitUser b Group List ws
104. eans23 Who Should Use This Tutorial vii How to Use This Tutorial viii About the Examples viii Typographical Conventions ix Feedback ix Introduction i iii irises L What is WSIT 2 Bootstrapping and Configuration 3 Message Optimization Technology 4 Reliable Messaging Technology 5 Security Technology 6 How WSIT Relates to Windows Communication Foundation WCF 6 WSIT Specifications 7 Bootstrapping and Configuration Specifications 8 Message Optimization Specifications 10 Reliable Messaging Specifications 12 Security Specifications 13 How the WSIT Technologies Work 14 How Message Optimization Works 15 How Reliable Messaging Works 16 How Security Works 18 WSITExample Using Registering GlassFish with the IDE 23 Creating a Web Service 24 iii Chapter 3 Chapter 4 Chapter 5 Chapter 6 CONTENTS Configuring WSIT Features in the Web Service 26 Deploying and Testing a Web Service 28 Creating a Client to Consume a WSIT Enabled Web Service 29 Bootstrapping and Configuration 33 What is a Server Side Endpoint 33 Creating a Client from WSDL 34 Client From WSDL Examples 35 Message Optimization 00ce eee e eee td Creating a Web Service 38 Configuring Message Optimization in a Web Service 38 Deploying and Testing a Web Service 39 Creating a Client to Consume a WSIT enabled Web Service 39 Message Optimization and Secure Conversation 42 Using Reliable Messaging 000 0080000 43 Reliable Messaging
105. eate and deploy WSIT web services and clients The IDE provides a graphical user interface GUD and does many of the manual steps described in this chapter for you thus reducing the amount of cod ing and processing required For an example that creates builds and deploys a web service and a web service client using NetBeans IDE see Chapter 2 123 124 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS This chapter covers the following topics Environment Configuration Settings page 124 WSIT Configuration and WS Policy Assertions page 125 Creating a Web Service page 126 Building and Deploying the Web Service page 131 Creating a Web Service Client page 135 Building and Deploying a Client page 139 Running a Web Service Client page 139 Undeploying a Web Service page 139 Environment Configuration Settings Before you can build and run the samples in this tutorial you need to complete the following tasks Setting the Web Container Listener Port page 124 Setting the Web Container Home Directory page 125 Setting the Web Container Listener Port The Java code and configuration files for the examples used in this tutorial assume that the web container is listening on IP port 8080 Port 8080 is the default listener port for both GlassFish domainl and Tomcat If you have changed the port you must update the port number in the following files before building and running the examples wsit enabled fromjava e
106. eb service reference for which you want to configure security options Select Edit Web Service Attributes When the Web Service References Attributes Editor is opened select the WSIT Configuration tab to display the WSIT options Expand the Certificates section to specify the keystore and truststore infor mation if required by the service Depending on what is required for the selected mechanism you may spec ify the following information in the Certificates section 81 82 USING WSIT SECURITY e Keystore Location The directory and file name containing the certifi cate key to be used to authenticate the client By default the location is already set to the default GlassFish keystore lt AS_HOME gt domains domain1 config keystore jks Keystore Password The password for the keystore used by the client By default the password for the GlassFish keystore is already entered This password is changeit NOTE When specified this password is stored in a WSIT configuration file in clear text Setting the keystore password in the development envi ronment is fine however when you go into production remember to use the container s default CallbackHandler to obtain the keys from the keystore This eliminates the need for the keystore passwords to be supplied by the users You can also specify the passwords for keystores and truststores by specifying a Cal lbackHand1er class that implements the javax security aut
107. ed DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS REPRESENTATIONS AND WARRANTIES INCLUDING ANY IMPLIED WARRANTY OF MER CHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON INFRINGEMENT ARE DISCLAIMED EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID Copyright 2007 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 Etats Unis Tous droits r serv s Droits du gouvernement am ricain utlisateurs gouvernmentaux logiciel commercial Les utilisateurs gouvernmentaux sont soumis au contrat de licence standard de Sun Microsystems Inc ainsi qu aux dis positions en vigueur de la FAR Federal Acquisition Regulations et des suppl ments celles ci Cette distribution peut comprendre des composants d velopp s pardes tierces parties Sun Sun Microsystems le logo Sun Java JavaServer Pages Enterprise JavaBeans Java Naming and Directory Interface EJB JSP J2EE J2SE et le logo Java Coffee Cup sont des marques de fabrique ou des marques d pos es de Sun Microsystems Inc aux Etats Unis et dans d autres pays A moins qu autrement autoris le code de logiciel en tous les mat riaux techniques dans le pr sent arti cles y compris FAQs chantillons est fourni sous ce permis Les produits qui font l objet de ce manuel d entretien et les informations qu il contient sont r gis par la l gislation am ricaine en mati re de contr le des exp
108. ed nillable or not The following examples illustrate the corresponding bindings in the NET client WEB SERVICE START FROM JAVA 165 Example Map a field property to a nillable element Java code fragment public class PurchaseOrder Map a field to a nillable XML element javax xml bind annotation Xm1lElement nillable true public java math BigDecimal price Schema fragment lt xS complexType name purchaseOrder gt lt xsS Sequence gt lt xs element name price type xs decimal nillable true minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema public partial class purchaseOrder private System Nullable lt decimal gt priceField private bool priceFieldSpeci fied public decimal price get return this priceField set this priceField value public bool priceSpecified get return this priceFieldSpecified set this priceFieldSpecified value Example Map property field to a nillable required element Java code fragment public class PurchaseOrder Map a field to a nillable XML element 166 DATA CONTRACTS Xm1lElement nillable true required true public java math BigDecimal price Schema fragment lt xs complexType name purchaseOrder gt lt xsS Sequence gt lt xs element name price type xs decimal nillable true minOccurs 1 gt lt xs Sequence gt lt xs complexType
109. ed 5 O operations securing 85 ordered delivery 43 P password default 58 proxy lifetime 5 Q Quality of Service 5 R reliable messaging advantages and disadvantages 5 configuration options 43 description 5 messages being lost 5 network connections being dropped 5 ordered delivery 5 performance degradation 44 quality of service 5 secure conversation 45 sequence identifier 5 session management 5 when to use it 5 reliable messaging options enabled disabled 43 flow control 44 inactivity timeout 44 max buffer size 44 ordered delivery 43 S SAAJ 141 147 SAML callback handlers examples of 59 specifying 58 SAML tokens validating 85 SAML Validator field 85 secure conversation security context token 45 secure messaging performance 42 semantics 42 Secure Service 49 Secure Token Service STS configuring 90 security bindings configuring 48 51 81 95 configuring 48 configuration requirements client 55 service 53 derived session keys 6 examples 97 mutual certificates 100 SAML authorization 106 SAML sender vouches SV 111 transport security SSL 103 username authentication 97 mechanisms described 61 SSL configuring 68 transport layer advantages 62 disadvantages 62 web services configuring 48 51 81 95 WSIT configuring 48 WSIT Configuration client 50 Secure Service 49 Security Mechanism 49 Security Binding Configuration page 48 INDEX 195 51 81 95 security context token 45 securit
110. equence which consists of all of the request messages for that proxy Each mes sage contains a sequence header The header includes a sequence identifier that identifies the sequence and a unique message number that indicates the order of the message in the sequence The web service endpoint uses the sequence header information to group the messages and if the Ordered Delivery option is selected to process them in the proper order Additionally if secure conversa tion is enabled each message sequence is assigned its own security context token The security context token is used to sign the handshake messages that initialize communication between two web service endpoints and subsequent application messages Thus using the Reliable Messaging technology web service endpoints collabo rate to determine which messages in a particular application message sequence arrived at the destination endpoint and which messages require resending The reliable messaging protocol requires that the destination endpoint return mes sage receipt acknowledgements that include the sequence identifier and the mes sage number of each message received If the source determines that a message was not received by the destination it resends the message and requests an acknowledgement Once the source has sent all messages for a given sequence and their receipt has been acknowledged by the destination the source termi nates the sequence The web service destination e
111. es list select Empty Java File Click Next For Class Name enter Sam1CallbackHandler Click Finish The empty file displays in the IDE j o Bae Download the example file Sam1Cal1backHandler java from the fol lowing URL https xwss dev java net servlets ProjectDocu mentList folderID 6645 amp expandFo 1 der 6645 amp folderID 6645 Open the file in a text editor 5 o Modify the home variable to provide the hard coded path to your Glass Fish installation For example modify the line String home System getProperty C WSIT_HOME to String home home glassfish p Set the subject confirmation method to SV Sender Vouches For more information on this topic read Example SAML Callback Handlers page 59 q Copy the contents of this file into the Sam1CallbackHandler java window that is displaying in the IDE 4 Drill down from CalculatorClient Web Service References 5 Right click on CalculatorWSService select Edit Web Service Attributes EXAMPLE STS ISSUED TOKEN STS 115 6 Select the WSIT Configuration tab of the CalculatorWSService dialog 7 Provide the client s private key by pointing to an alias in the keystore To do this expand the Certificates node click the Load Aliases button for the keystore and select xws security client from the Alias list 8 Provide the server s certificate by pointing to an alias in the client trust store To do this from the Certificates node cl
112. etBeans IDE Specifying Aliases with the Updated Stores The configuration of the aliases for all containers Tomcat GlassFish and for all applications JSR 109 compliant and non JSR 109 compliant except for appli cations that use a Security Token Service STS mechanism is as shown in Table 6 3 Table 6 3 Keystore and Truststore Aliases Keystore Alias Truststore Alias Client Side xws security client xws security server Configuration Server Side y xws security server xws security client Configuration CONFIGURING THE KEYSTORE AND TRUSTSTORE 77 The configuration of the aliases for applications that use a Security Token Ser vice STS mechanism is as shown in Table 6 4 Table 6 4 Keystore and Truststore Aliases for STS Keystore Alias Truststore Alias Client Side xws security client xws security server Configuration STS xws security client wssi Configuration y p Configuring the Keystore and Truststore NetBeans IDE already knows the location of the default keystore file and its password but you need to specify which alias is to be used The following sec tions discuss configuring the keystore on the service and on the client Configuring the Keystore on a Service A keystore is a database of private keys and their associated X 509 certificate chains authenticating the corresponding public keys A key is a piece of informa tion that controls the operation of a cryptog
113. ew AddNumbersFault_Exception message fault return number1 number2 public void oneWwayInt int number System out println Service received number Building and Deploying the Web Service Once configured you can build and deploy a WSIT enabled web service in the same manner as you would build and deploy a standard JAX WS web service 132 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS The following topics describe how to perform this task e Building and Deploying a Web Service Created From Java page 132 e Building and Deploying a Web Service Created From WSDL page 133 e Deploying the Web Service to a Web Container page 133 e Verifying Deployment page 134 Building and Deploying a Web Service Created From Java To build and deploy the web service open a terminal window go to the lt INSTALL gt wsit enabled fromjava directory and type the following ant server This command calls the server target in build xml which builds and packages the application into a WAR file wsit enabled fromjava war and places it in the wsit enabled fromjava build war directory The ant server command also deploys the WAR file to the web container The ant command calls multiple tools to build and deploy the web service The JAX WS annotation processing tool apt processes the annotated source code and invokes the compiler itself resulting in the class files for each of the Java source files In the wsi
114. ey reach there final destination The optimization process is really quite simple To effect optimized message transmissions the sending endpoint checks the body of the SOAP message for XML encoded binary objects that exceed a predetermined size and encodes those objects for efficient transmission over the Internet SOAP MTOM paired with the XML binary Optimized Packaging XOP addresses the inefficiencies related to the transmission of binary data in SOAP documents Using MTOM and XOP XML messages are dissected in order to transmit binary files as MIME attachments in a way that is transparent to the application This transformation is restricted to base64 content in canonical form as defined in XSD Datatypes as specified in XML Schema Part 2 Datatypes Sec ond Edition W3C Recommendation 28 October 2004 Thus the WSIT technology achieves message optimization through an imple mentation of the MTOM and XOP specifications With the message optimization feature enabled small binary objects are sent in line in the SOAP body For large binary objects this becomes quite inefficient so the binary object is separated from the SOAP body encoded sent as an attachment to the SOAP message and decoded when it reaches its destination endpoint 16 INTRODUCTION How Reliable Messaging Works When reliable messaging is enabled messages are grouped into sequences which are defined by the client s proxies Each proxy corresponds to a message s
115. f v3 certificates The default GlassFish keystore and truststore do not contain v3 certificates at this time but should before FCS GlassFish instances installed using JDK 1 6 do have a v3 certificate but the certificate lacks a particular extension required for supporting some secure WSIT mechanisms In order to use message security mechanisms with GlassFish it is necessary to download keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores To update the GlassFish certificates follow these steps 1 Download the zip file that contains the certificates and the Ant scripts copyv3 zip by going to this URL https xwss dev java net servlets ProjectDocumentList folderID 6645 amp expand Folder 6645 amp folderID 6645 2 Unzip this file and change into its directory copyv3 3 Verify that an environment variable named AS_HOME is created and that it specifies the full path to the location of your GlassFish installation for example C Sun GlassFish NOTE Some releases of GlassFish may have different default passwords for the keystores If you are using a different version of GlassFish than the UPDATING GLASSFISH CERTIFICATES one recommended at wsit dev java net edit the file build xml and specify the correct default password in the AS_KEYSTORE_PASSWORD field From the copyv3 directory execute the Ant command that will copy the keystore and truststo
116. foset Figure 1 6 Web Services Security Specifications In addition to the Core XML specifications the security feature is implemented using the following specifications e Web Services Security This specification defines a standard set of SOAP extensions that can be used when building secure web services to imple ment message content integrity and confidentiality The implementation provides message content integrity and confidentiality even when commu nication traverses intermediate nodes thus overcoming a short coming of SSL The implementation can be used within a wide variety of security models including PKI Kerberos and SSL and provides support for multi ple security token formats multiple trust domains multiple signature for mats and multiple encryption technologies e Web Services Policy This specification provides a flexible and extensible grammar for expressing the capabilities requirements and general charac teristics of a web service It provides a framework and a model for the 14 INTRODUCTION expression of these properties as policies and is a building block for Web Services Security policy Web Services Trust This specification supports the following capabilities in a standardized way e Defines extensions to Web Services Security that provide methods for issuing renewing and validating security tokens used by Web services security e Establishes assesses the presence of and brokers trust relations
117. g a configuration file That file wsit lt pack age gt lt service gt xml is written in WSDL format An example configuration file can be found in the accompanying samples wsit enabled fromjava etc wsit fromjava server AddNumber sImp1 xm1 The settings in the wsit lt package gt lt service gt xm1 file are incorporated dynamically by the WSIT run time into the WSDL it generates for the web ser vice So when a client requests the web service s WSDL the run time embeds any publicly visible policy assertions contained in the wsit lt package gt lt ser vice gt xm1 file into the WSDL For the example wsit fromjava server Add NumbersImp1 xm1 in the sample discussed in this tutorial the Addressing and Reliable Messaging assertions are part of the WSDL as seen by the client Note The wsit lt package gt lt service gt xm1 file must be in the WEB INF sub direc tory of the application s WAR file when it is deployed to the web container Other wise the WSIT run time environment will not find it To create a web service from Java create the following files e These files define the web service and the WSIT configuration for the ser vice which are discussed in the sections below e Web Service Implementation Java File page 128 e wsit lt package gt lt service gt xml File page 129 e These files are standard files required for JAX WS Examples of these files are provided in the wsit enabled fromjava sample directory
118. g option as appropriate e Transactions Select an option from the Transactions list to specify a level at which transactions will be secured For this release transactions will only use SSL for security Transactions are discussed in Chapter 10 Using Atomic Transactions 8 Expand the Input Message section This section will be grayed out if Secure Service is not selected 9 Specify the following options as appropriate e Authentication Token Specifies which supporting token will be used to sign and or encrypt the specified message parts Options include Username X509 SAML Issued or None For further description of these options read Supporting Token Options page 89 88 USING WSIT SECURITY e Signed Specifies that the authentication token must be a signed sup porting token A signed supporting token is signed by the primary sig nature token and is part of primary signature e Endorsing Specifies that the authentication token must be endorsed With an endorsing supporting token the key represented by the token is used to endorse sign the primary message signature If both Signed and Endorsing are selected the authentication token must be a signed endorsing supporting token In this situation the token is signed by the primary signature The key represented by the token is used to endorse sign the primary message signature 10 For the Input Message and or Output Message click the Message Parts button to s
119. g over an SSL protected session the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data Security is live from the time it leaves the con sumer until it arrives at the provider or vice versa The problem is that it is not protected once it gets to its destination For protection of data after it reaches its destination use one of the security mechanisms that uses SSL and also secures data at the message level Digital certificates are necessary when running secure HTTP transport HTTPS using Secure Sockets Layer SSL The HTTPS service of most web servers will not run unless a digital certificate has been installed Digital certificates have already been created for GlassFish and the default certificates are sufficient for running this mechanism and are required when using Atomic Transactions see Chapter 10 However the message security mechanisms require a newer version of certificates than is available with GlassFish You can download valid keystore and truststore files for the client and server as described in Updating GlassFish Certificates page 74 To use this mechanism follow the steps in Configuring SSL For Your Applica tions page 69 See Also Example Transport Security SSL page 103 TRANSPORT SECURITY SSL Transport Sec unity SSL Workaround This note applies to cases where
120. ging is a Quality of Service QoS technology for building more reliable web services Reliability is measured by a system s ability to deliver messages from point A to point B without error The primary purpose of Reliable Messaging is to ensure the delivery of application messages to web service end points The reliable messaging technology ensures that messages in a given message sequence are delivered at least once and not more than once and optionally in the correct order When messages in a given sequence are lost in transit or delivered out of order this technology enables systems to recover from such failures If a message is lost in transit the sending system retransmits the message until its receipt is acknowledged by the receiving system If messages are received out of order the receiving system may re order the messages into the correct order The Reliable Messaging technology can also be used to implement session man agement A unique message sequence is created for each client side proxy and the lifetime of the sequence identifier coincides with the lifetime of the proxy Therefore each message sequence can be viewed as a session and can be used to implement session management You should consider using reliable messaging if the web service is experiencing the following types of problems e Communication failures are occurring that result in the network being unavailable or connections being dropped e Application messages ar
121. guring an example application are provided for several of the mechanisms Please see the following sections for a complete example of how to configure a web service and a web service client to use these security mecha nisms e Example Username Authentication with Symmetric Keys UA page 97 e Example Mutual Certificates Security MCS page 100 e Example Transport Security SSL page 103 e Example SAML Authorization over SSL SA page 106 e Example SAML Sender Vouches with Certificates SV page 111 e Example STS Issued Token STS page 115 Securing the Client All of the steps in Securing the Service page 48 need to be completed before you create your web service client The service s security policies are defined in its WSDL You specify this WSDL file when you create the client application so that the client is configured to work with the service s security mechanism through the web service reference URL when the client is built or refreshed SECURING THE CLIENT To use the IDE to configure security for a web service client perform the follow ing tasks 1 nA BW N Create a client for your web service If you need an example of how to do this see Creating a Client to Con sume a WSIT Enabled Web Service page 29 If you are creating a client for a mechanism that will use SSL specify the secure port for running the client when completing the New Web Service Client step To do this enter https
122. h as described in Adding Users to Glass Fish page 72 3 Client Configuration For configuring your system for SSL in order to work through the exam ples in this tutorial the same keystore and truststore files are used for both the client and the service This obviates the needs to set system properties 69 70 USING WSIT SECURITY to point to the client stores as both GlassFish and NetBeans are aware of these certificates and point to them by default In general for the client side of SSL you will not be using the same certif icates for the client and the service In that case you need to define the client certificate stores by setting the system properties Djavax net ssl trustStore Djavax net ss1l keyStore Djavax net ssl trustStorePassword and Djavax net ssl keyStorePassword in the application client con tainer You can specify the environment variables for keystore and truststore by setting the environment variable VMARGS through the shell environment or inside an Ant script or by passing them in when you start NetBeans IDE from the command line For example in the latter case lt NETBEANS_HOME gt bin netbeans exe J Djavax net ss1 trustStore lt AS_HOME gt domains domain1 config cacerts jks J Djavax net ss1 keyStore lt AS_HOME gt domains domainl config keystore jks jJ Djavax net ss1 trustStorePassword changeit J Djavax net ss1 keyStorePassword changeit Use the hard coded path to the keystore and tr
123. h callback CallbackHandler interface in the Keystore Password Truststore Password or Key Password fields Load Aliases Click this button to populate the Alias list with all of the certificates available in the selected keystore This option will only work if the keystore location and password are correct Keystore Alias Select the alias in the keystore Refer to the table in Specifying Aliases with the Updated Stores page 76 to determine which alias is appropriate for the selected security mechanism Key Password TIf the client key has been password protected enter the password for this key The GlassFish certificate key password is changeit Truststore Location The directory and file name of the client truststore containing the certificate of the server By default this field points to the default GlassFish truststore lt AS_HOME gt domains domain1 config cacerts jks Truststore Password The password for the truststore used by the client By default the password for the GlassFish truststore is already speci fied The password is changeit NOTE When specified this password is stored in a WSIT configuration file in clear text Setting the truststore password in the development environment is fine however when you go into production remember to use the container s default Cal backHand er to obtain the keys from the keystore This eliminates the need for the keystore passwords to be CONFIGURING THE KEYSTORE AND TR
124. he WSDL URL option 5 Cut and paste the URL of the web service that you want the client to con sume into the WSDL URL field For example here is the URL for the Cal culatorws web service http localhost 8080 CalculatorApplication CalculatorWSService wsd1 When JAX WS generates the web service it appends Service to the class name by default 6 Type org me calculator client in the Package field and click Finish The Projects window displays the new web service client as shown in Fig ure 2 3 ny Projects ax Files Runtime 2 0 a GQ Web Pages WEB INF B index jsp 5 Web Service References a Calculatorws Figure 2 3 Web Service Client 30 10 11 12 13 14 15 WSIT EXAMPLE USING A WEB CONTAINER AND NETBEANS Right click the CalculatorWSServletClient project node and choose New Servlet Name the servlet ClientServlet specify the package name for example org me calculator client and click Finish To make the servlet the entry point to your application right click the Cal culatorWSServletClient project node choose Properties click Run type ClientServlet in the Relative URL field and click OK If ClientServlet java is not already open in the Source Editor open it In the Source Editor remove the line that comments out the body of the processRequest method This is the start comment line that starts the sec tion that comments out the code TODO output
125. he fol lowing SAML Callbacks and Require ThumbPrint Reference assertions under an X 509 Token This may be addressed in a future milestone Authentication Credentials Select Static or Dynamic Default Username Default Password Enter the name of an authorized user and the password for this user This option is best used only in the development environment When the Default Username and Default Pass word are specified the username and password are stored in the wsit client xm1 file in clear text which presents a security risk Do not use this option for production e SAML Callback Handler To use a SAML Callback Handler you need to create one as there is no default References to example SAML Callback Handlers are provided in Example SAML Callback Handlers page 59 Anexample that uses a SAML Callback Handler can be found in Example SAML Authorization over SSL SA page 106 SUMMARY OF CLIENT SIDE CONFIGURATION REQUIREMENTS Example SAML Callback Handlers Creating a SAML Callback Handler is beyond the scope of this document how ever the following web pages may be helpful for this purpose e A client side configuration which includes a SAML Callback Handler can be viewed at the following URL https wsit dev java net source browse checkout wsit wsit test e2e testcases xwss sl1l1 resources wsit client xml e An example of a SAML Callback Handler can be viewed and or down loaded from the following URL https
126. he service side you select a security mechanism that includes STS in its title The STS itself is secured using a separate non STS security mechanism The security configuration of the client side of this application is dependent upon the security mechanism selected for the STS and not on the security mechanism selected for the application To specify an STS for the web service follow these steps 1 Right click the node for the web service you want to secure Select Edit Web Service Attributes Select Secure Service Select a Security Mechanism that specifies STS from the list Click Configure to specify the STS information Nn WN Enter the Issuer Address and or Issuer Metadata Address When the Issuer Address and the Metadata values are the same you only need to enter the Issuer Address For the example application the Issuer Address would be http localhost 8080 MySTSProject MySTSSer vice 7 Set the Algorithm Suite value so that the algorithm suite value of the ser vice matches the algorithm suite value of the STS Specifying an STS on the Client Side Once you ve determined whether the an STS is required to be configured on the client side see Summary of Client Side Configuration Requirements page 54 configure the client Secure Token Service options as follows 1 In the Projects window expand the node for the web services client 2 Expand the Web Service References node 3 Right click the
127. he web ser vice that includes an empty WebService class with annotation Webser vice 8 Right click within the body of the class and choose Web Service Add Operation 9 In the upper part of the Add Operation dialog box type add in Name and choose int from the Return Type drop down list 10 In the lower part of the Add Operation dialog box click Add and create a parameter of type int named 7 Click OK Click Add again and create a parameter of type int called j Click OK and close the Enter Method Parameter dialog box 26 WSIT EXAMPLE USING A WEB CONTAINER AND NETBEANS 11 Click OK at the bottom of the Add Operation dialog box 12 Notice that the add method has been added to the Source Editor WebMethod public int add WebParam name i int i WebParam name j int j TODO implement operation return Q 13 Change the add method to the following changes are in bold WebMethod action add public int add WebParam name i int i WebParam name j int j int k i j return k Note To ensure interoperability with Windows Communication Foundation WCF clients you must specify the action element of webMethod in your end point implementation classes WCF clients will incorrectly generate an empty string for the Action header if you do not specify the action element 14 Save the Calculatorws java file You have successfully coded the web service Configuring WSIT Features in
128. hese two data types support different range and precision java math BigDecimal supports arbitrary precision System decimal does 150 DATA CONTRACTS not For interoperability use only values within the range and precision of Sys tem decimal See System decimal Minvalue and System decimal Max value Any values outside of this range require a customized NET client Example BigDecimal usage Java code fragment public class RetBigDecimal private BigDecimal argQ public BigDecimal getArgQ return this argQ public void setArg BigDecimal argQ this argQ argQ Schema fragment lt xs complexType name retBigDecimal gt lt xsS Sequence gt lt xs element name argQ0 type xs decimal minOccurs 0 gt lt xs Sequence gt lt xs complexType gt NET auto generated code from schema public partial class retBigDecimal private decimal argQField private bool arg FieldSpeci fied public decimal argQ get return this argQField set this arg Field value public bool arg Specified get return this argQ FieldSpeci fied set this arg FieldSpecified value C code fragment System CultureInfo engCulture new System CultureInfo C en US retBigDecimal bd new retBigDecimal bd arg System decimal MinValue WEB SERVICE START FROM JAVA 151 retBigDecimal negBd new retBigDecimal negBd System decimal Parse 0 engCulture java ne
129. hips Web Services Secure Conversation This specification defines a standard ized way to provide better message level security and efficiency in multi ple message exchanges The WSIT implementation provides basic mechanisms on top of which secure messaging semantics can be defined for multiple message exchanges and allows for contexts to be established along with more efficient keys or new key material This approach increases the overall performance and security of the subsequent exchanges While the Web Services Security specification described above focuses on the message authentication model it does leave open ings for several forms of attacks The Secure Conversation authentication specification defines a standardized way to authenticate a series of mes sages thereby addressing the short comings of Web Services Security With the Web Services Security Conversation model the security context is defined as a new Web Services security token type that is obtained using a binding of Web Services Trust Web Services Security Policy This specification defines a standard set of patterns or sets of assertions that represent common ways to describe how messages are secured on a communications path The WSIT implementa tion allows flexibility in terms of tokens cryptography and mechanisms used including leveraging transport security but is specific enough to ensure interoperability based on assertion matching by web service clients and web
130. his lt security constraint gt lt display name gt Constraint1l lt display name gt lt web resource col lection gt lt web resource name gt CalcWebResource lt web resource name gt lt description gt lt url pattern gt lt url pattern gt lt http method gt POST lt http method gt 72 USING WSIT SECURITY lt web resource col lection gt lt user data constraint gt lt description gt lt transport guarantee gt CONFIDENTIAL lt transport guarantee gt lt user data constraint gt lt security constraint gt j When you run this project right click select Run Project the browser will ask you to accept the server certificate of slas Accept this certifi cate The WSDL displays in the browser 6 Creating a Client When creating your client application use the fully qualified hostname to specify the secure WSDL location use https lt fully_qualified_hostname gt 8181 CalculatorApp1lication Cal culatorWSService wsdl for example in place of http local host 8080 CalculatorApplication CalculatorwSService wsd1 In some cases you might get an error dialog telling you that the URL https lt fully_qualified_hostname gt 8181 CalculatorApplica tion CalculatorWSService wsd1 couldn t be downloaded However this is the correct URL and it does load when you run the service So when this error occurs repeat the steps that create the Web Service Client using the secure WSDL The second time th
131. his mechanism the SAML token is expected to carry some authorization information about an end user The sender of the token is actually vouching for the credentials in the SAML token To use this mechanism configure SSL on the server as described in Configuring SSL For Your Applications page 69 and on the clients side configure a SAML CallbackHandler as described in Example SAML Callback Handlers page 59 See Also Example SAML Authorization over SSL SA page 106 ENDORSING CERTIFICATE Endorsing Certificate This mechanism uses secure messages using symmetric key for integrity and confidentiality protection and uses an endorsing client certificate to augment the claims provided by the token associated with the message signature For this mechanism the client knows the service s certificate and requests need to be endorsed authorized by a special identity For example all requests to a vendor must be endorsed by a purchase manager so the certificate of the purchase man ager should be used to endorse or counter sign the original request SAML Sender Vouc hes with Certificates This mechanism protects messages with mutual certificates for integrity and con fidentiality and with a Sender Vouches SAML token for authorization The Sender Vouches method establishes the correspondence between a SOAP mes sage and the SAML assertions added to the SOAP message The attesting entity provides the confirmation evidence that will
132. ick the Load Aliases button for the Truststore and select xws security server 9 Expand the Username Authentication node In the SAML Callback Han dler field enter the name of the class written in step 3 above xwss saml Sam1Cal1lbackHand1 er 10 Click OK to close this dialog 11 In the tree drill down from the project to Source Packages META INF Double click on CalculatorWSService xml and verify that lines similar to the following are present where xwss sam Sam1Cal1lbackHand er is the SAML Callback Handler class for the client lt wsp Al1 gt lt wsaws UsingAddressing xmlns wsaws http www w3 org 2006 05 addressing wsd1 gt lt sc CallbackHandlerConfi guration wspp visibility private gt lt sc CallbackHandler name samlHandler classname xwss saml1 Sam1CallbackHandler gt lt sc CallbackHand1erConfiguration gt lt sc KeyStore wspp visibility private location lt GF_HOME gt domains domain1 config keystore jks storepass Cchangeit alias xws security client keypass changeit gt lt sc TrustStore wspp visibility private location lt GF_HOME gt domains domainl config cacerts jks storepass Cchangeit peeralias xws security server gt lt wsp Al1 gt 12 Compile and run this application by right clicking the CalculatorClient node and selecting Run Project Example STS Issued Token STS The topics covered in this section include the following e Securing the Example Service Applicatio
133. ined in the truststore file The Location and Store Password fields must be specified correctly for this option to work e Alias Specifies the peer alias of the certificate in the truststore that is to be used when the client needs to send encrypted data Refer to the table in Specifying Aliases with the Updated Stores page 76 to deter mine which alias is appropriate for the selected security mechanism A truststore contains trusted other party certificates and certificates of Certificate Authorities CA A peer alias is the alias of the other party peer that the sending party needs to use to encrypt the request 6 Click OK to close the dialog Configuring the Keystore and Truststore ona Client On the client side a keystore and truststore file must be configured for some of the security mechanisms Refer to the table in Summary of Client Side Configu ration Requirements page 54 for information on which mechanisms require the configuration of keystores and truststores If the mechanism configured for the service requires the configuration of keystores and truststores follow these steps 1 Check the table in Summary of Client Side Configuration Requirements page 54 to see if a keystore needs to be configured for the client for the selected security mechanism If so continue 2 In the Projects window expand the node for the web service client Expand the Web Service References node Right click the node for the w
134. ion This specification defines a framework for pro viding protocols that coordinate the actions of distributed applications This framework is used by Web Services Atomic Transactions The imple mentation of this specification enables the following capabilities e Enables an application service to create the context needed to propagate an activity to other services and to register for coordination protocols e Enables existing transaction processing workflow and other coordina tion systems to hide their proprietary protocols and to operate in a het erogeneous environment WSIT SPECIFICATIONS 13 e Defines the structure of context and the requirements so that context can be propagated between cooperating services e Web Services Atomic Transactions This specification defines a standard ized way to support two phase commit semantics such that either all oper ations invoked within an atomic transaction succeed or are all rolled back Implementations of this specification require the implementation of the Web Services Coordination specification Security Specifications Figure 1 6 shows the specifications implemented to secure communication between two web service endpoints and across intermediate endpoints Web Services Web Services Web Services Security Security Secure Conversation Trust Standards Web Services Security Policy Supporting Web Services Web Services Standards Policy Addressing Core XML Standards In
135. ionDataObject ExtensionData get return this extensionDataField set this extensionDataField value public string uuid get return this uuidField set this uuidField value C code fragment reportUid tmpU new reportUidQ System Guid guid new System Guid 06b7857a 05d8 4c14 b7fa 822e2aa6053f tmpU uuid guid ToStringQ 160 DATA CONTRACTS Type Variable A typed variable maps to xs anyType NET maps xs anyType to Sys tem Object Example Using a typed variable Java class public class Shape lt T gt private T xshape public Shape public ShapeC T f xshape f lt xs complexType name shape gt lt XxS sequence gt lt xs element name xshape type xs anyType minOccurs 0 gt lt xs sequence gt lt xs complexType gt C code generated by svcutil public partial class shape private object xshapeField public object xshape get return this xshapeField set this xshapeField value Collections Java collections types java util Collection and its subtypes array List and parameterized collection types e g List lt Integer gt can be mapped to XML schema in different ways and can be serialized in different ways The fol lowing examples show NET bindings WEB SERVICE START FROM JAVA 161 List of nillable elements By default a collection type such as List lt Integer gt ma
136. it c New Password changeit d Confirm New Password changeit 10 Click OK to add this user to the list of users in the realm 11 Click Logout when you have completed this task Adding Users to GlassFish Fom Command Line To add users to GlassFish from the command line make sure GlassFish is run ning then enter the following command lt AS_HOME gt asadmin create file user groups wsit wsitUser Enter changeit for the password when prompted 74 USING WSIT SECURITY Configuring Keystores and Truststores This section describes configuring keystores and truststores Security mecha nisms that use certificates require keystore and truststore files for deployment e For GlassFish default keystore and truststore files come bundled however WSIT security mechanisms for message security require X 509 version 3 certificates GlassFish contains version certificates therefore to enable the WSIT applications to run on GlassFish you will need to follow the instructions in Updating GlassFish Certificates page 74 e For Tomcat keystore and truststore files do not come bundled with this container so they must be provided You can download valid keystore and truststore files for the client and server from https xwss dev java net The following sections discuss how to specify and configure the keystore trust store and validators Updating GlassFish Certificates The WSIT message security mechanisms require the use o
137. ith the following exception a In the step where you are directed to cut and paste the URL of the web service that you want the client to consume into the WSDL URL field enter https lt ful1ly qual i fied hostname gt 8181 CalculatorAp plication CalculatorWSService wsd1 changes indicated in bold to indicate that this client should reference the web service using the secure port The first time you access this service accept the certificate slas when you are prompted This is the server certificate popping up to confirm its identity to the client In some cases you might get an error dialog telling you that the URL https lt fully qualified hostname gt 8181 CalculatorApp1i cation CalculatorWSService wsd1 couldn t be downloaded How ever this the correct URL and it does load when you run the service So when this error occurs repeat the steps that create the Web Service Client using the secure WSDL The second time the web service refer ence is created and you can continue creating the client NOTE If you prefer to use localhost in place of the fully qualified hostname FQHN in this example you must follow the steps in Trans port Security SSL Workaround page 63 b Continue creating the client following the remainder of the instructions in Creating a Client to Consume a WSIT Enabled Web Service page 29 105 106 USING WSIT SECURITY NOTE Whenever you make changes on the service refresh the client so tha
138. ke method replace the return nu11 line with the follow ing return statement return super invoke source e Add the following method after the invoke method protected MessageContext getMessageContext MessageContext msgCtx context getMessageContextQ return msgCtx 12 Back in the Projects window expand the MySTSProject node then expand the Web Services node Right click on the MySTSSer vice IMySTSService_Port node and select Edit Web Service Attributes to configure the STS 13 Select Secure Service if it s not already selected 14 Verify that the Security Mechanism of Username Authentication with Symmetric Keys is selected 15 Select the Configure button For Algorithm Suite verify that Basic128 bit is selected so that it matches the value selected for the service For the Key Size verify that 128 is selected Select OK to close the configuration dialog 16 Select Act as Secure Token Service STS Click OK to close the Select STS Service Provider dialog EXAMPLE STS ISSUED TOKEN STS 17 Click the Keystore button to provide your keystore with the alias identify ing the service certificate and private key To do this click the Load Aliases button and then select wssip Click OK to close the dialog 18 Click OK to close the WSIT Configuration dialog A new file is added to the project To view the WSIT configuration file expand Web Pages gt WEB INF wsdl MySTS then double click the file MySTSService wsd1 Thi
139. kens You may wish to configure security at the operation level for example in the situation where only one operation requires a UsernameToken to be passed and the rest of the operations do not require this or in the situation where only one operation needs to be endorsed by a special token and the others do not Input Message and Output Message Security mechanisms at this level are used to specify what is being pro tected and the level of protection required In this section you can specify parts of a message that require integrity protection digital signature and or confidentiality encryption When you do this the specified part of the message outside of security headers requires signature and or encryption For example a message producer might submit an order that contains an orderID header The producer signs and or encrypts the orderID header the SOAP message header and the body of the request the SOAP message body Parts that can be signed and or encrypted include the body the header the local name of the SOAP header and the namespace of the SOAP header You can also specify arbitrary elements in the message that require integ rity protection and or confidentiality Because of the mutability of some SOAP headers a message producer may decide not to sign and or encrypt the SOAP message header or body as a whole but instead sign and or encrypt elements within the header and body Elements that can be signed 85 86
140. l The wsimport tool then generates the corresponding Java source code for the interface described by the WSDL The Java compiler javac is then called to compile the source into class files The programming code uses the gen erated classes to access the web service The following sections describe how to create a web service client e Creating a Client from Java page 136 e Creating a Client from WSDL page 138 136 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS Creating a Client from J ava To create a client from Java you must create the following files e Client Java File fromjava page 136 e Client Configuration File fromjava page 137 e build xml e build properties The build xml and build properties files are standard in any Ant build envi ronment Examples of these files are provided in the wsit enabled fromjava sample directory Client ava File fromjava The client Java file defines the functionality of the web service client The fol lowing code shows the AddNumbersClient java file that is provided in the sam ple package fromjava client import com sun xml ws Closeable import java rmi RemoteException public class AddNumbersClient public static void main String args AddNumbersImp1 port null try port new AddNumbersImp1Service getAddNumbersImp1PortQ int numberl 10 int number2 20 System out printf Invoking addNumbers d d n number1 number2 int resul
141. laneType Order 4 public transportType Item get return this itemField set this itemField value public partial class planeType public partial class autoType WEB SERVICE START FROM JAVA 169 Class A Java class can be mapped to different XML schema type and or an XML ele ment The following guidelines apply to the usage of annotations at the class level XmiType Anonymous type Guideline Prefer mapping class to named XML schema type rather than an anonymous type for a better NET type binding The Xm1Type annotation is used to customize the mapping of a Java class to an anonymous type NET binds an anonymous type to a NET class one per refer ence to the anonymous type Thus each Java class mapped to an anonymous type can generate multiple classes on the NET client Example Mapping a Java class to an anonymous type using Xm1Type Java code fragment public class PurchaseOrder public java util List lt Item gt item Xm1TypeCname public class Item public String productName Schema fragment lt xS complexType name purchaseOrder gt lt xsS Sequence gt lt xs element name item gt lt xs complexType gt lt xsS sequence gt lt xs element name productName type xs string gt lt xs Sequence gt 170 DATA CONTRACTS lt xs complexType gt lt xs element gt lt xs Sequence gt lt xs complexType gt C
142. lasses WCF clients will incorrectly generate an empty string for the Action header if you do not specify the action element CREATING A WEB SERVICE 129 wsit lt package gt lt service gt xml File This file is the WSIT configuration file It defines which WSIT technologies are enabled in the web service The snippet shown below illustrates how to enable the WSIT reliable messaging technology in a wsit lt package gt lt service gt xml file lt wsp Policy wsu Id AddNumbers_policy gt lt wsp Exact1yOne gt lt wsp Al1 gt lt wsaw UsingAddressing gt lt wsrm RMAssertion gt lt wsrm InactivityTimeout Milliseconds 600000 gt lt wsrm AcknowledgementiInterval Milliseconds 200 gt lt wsrm RMAssertion gt lt wsp Al1 gt lt wsp Exact1yOne gt lt wsp Policy gt For a complete example of a wsit lt package gt lt service gt xm file see the wsit enabled fromjava example You can use the wsit lt package gt lt ser vice gt xml file provided in the example as a reference for creating your own wsit lt package gt lt service gt xm file Creating a Web Service From WSDL Typically you start from WSDL to build your web service if you want to imple ment a web service that is already defined either by a standard or an existing instance of the service In either case the WSDL already exists The JAX WS wsimport tool processes the existing WSDL document either from a local copy on disk or by retrieving it from a net
143. lback Mechanism User Handler STS Issued Endorsing Token e Keystore lIf this column indicates YES configure the keystore to point to the alias for the client certificate For the GlassFish keystores the key store file is keystore jks and the alias is xws security client assum ing that you ve updated the GlassFish default certificate stores as described in Updating GlassFish Certificates page 74 e Truststore If this column indicates YES configure the truststore that contains the certificate and trusted roots of the server For the GlassFish keystores the file is cacerts jks and the alias is xws security server assuming that you ve updated the GlassFish default certificate stores as described in Updating GlassFish Certificates page 74 When using an STS mechanism the client specifies the truststore and cer tificate alias for the STS not the service For the GlassFish stores the file is cacerts jks and the alias is wssip e Default User When this column indicates YES you must configure either a default username and password a UsernameCallbackHandler or leave these options blank and specify a user at runtime More information on these options can be found at Configuring Username Authentication on the Client page 57 e SAML Callback Handler When this column indicates YES you must specify a SAML Callback Handler Examples of SAML Callback Han dlers are described in Example SAML Callback H
144. le 9 1 Furthermore JAXB 2 0 maps these XML schema types to Java types that are natural to Java developer However this results in a map ping that is not one to one For example e xs int gt int e xs unsignedShort gt int The lack of a one to one mapping means that when XML Schema types shown in Table 9 1 are used in an xsi type construct they won t be preserved by default across an unmarshal followed by marshal operation For example C web method public Object retObject Object objvalue Java web method generated from WCF service WSDL public Object retObject Object objvalue 180 DATA CONTRACTS The following illustrates why xsi type is not preserved across an unmarshal marshal operation e A value of type uint is marshalled by WCF serialization mechanism as lt objvalue xsi type xs unsignedShort gt JAXB 2 0 unmarshaller unmarshals the value as an instance of int and assigns it to parameter objvalue e The objvalue is marshalled back by JAXB 2 0 marshaller with an xXSi type of xs int lt objvalue xsi type xs int gt One way to preserve and roundtrip the xsi type is to use the mapSimpleType Def customization The customization makes the mapping of XML Schema Part 2 datatypes one to one by generating additional Java classes Thus xs unsignedShort will be bound to its own class rather than int as shown Java class to which xs unsignedShort is bound public class UnsignedShort
145. lient This protocol is a boot strap mechanism for communication When the type of metadata desired is clearly known for example WS Policy a client request may indicate that only that type should be returned CLIENT FROM WSDL EXAMPLES 35 Client From WSDL Examples The following sections found in other chapters of this tutorial explain how to create a client from a WSDL file using the example files in the tutorial bundle e Creating a Client to Consume a WSIT Enabled Web Service page 29 shows how to create a client from WSDL using a web container and the NetBeans IDE e Creating a Client from WSDL page 138 shows how to create a client from WSDL using only a web container 36 BOOTSTRAPPING AND CONFIGURATION A Message Optmization Tiss chapter provides instructions on how to configure message optimization in web service providers and clients Note Because of the special encoding decoding requirements for message optimi zation if a service uses message optimization then a client of that service must sup port message optimization Most web services stacks do support message optimization In the rare case when you think that a legacy client which does not support optimization will access your service do not use message optimization In general however it is a safe and good practice to use message optimization This chapter covers the following topics e Creating a Web Service page 38 e Configuring Mes
146. lightly different XML schema representations Therefore NET bindings will vary accordingly Example A Java primitive type and its corresponding wrapper class Java code fragment public class StockItem public Double wholeSalePrice public double retailPrice Schema fragment lt xs complexType name stockItem gt lt xsS Sequence gt lt xs element name wholeSalePrice type xs double WEB SERVICE START FROM JAVA 149 minOccurs 0 gt lt xs element name retailPrice type xs double gt lt xs Sequence gt lt xs complexType gt NET C auto generated code from schema public partial class stockItem private double wholeSalePrice private bool wholeSalePriceFieldSpeci fied private double retailPrice public double wholeSalePrice get return this wholeSalePrice set this wholeSalePrice value public bool wholeSalePriceSpecified get return this wholeSalePriceFieldSpecified set this wholeSalePriceFieldSpecified value public double retailPrice get return this retailPrice set this retailPrice value C code fragment stockItem s new stockItem s wholeSalePrice Double parse 198 92 s wholeSalePriceSpecified true s retailPrice Double parse 300 25 BigDecimal Guideline Limit decimal values to the range and precision of NET s Sys tem decimal java math BigDecimal maps to xs decimal NET maps xs decimal to Sys tem decimal T
147. list 119 120 USING WSIT SECURITY 5 Provide the service s certificate by pointing to an alias in the client trust store To do this from the Certificates node click the Load Aliases button for the truststore and select xws security server from the Alias list 6 Expand the Security Token Service node to provide details for the STS to be used When the Endpoint and the Metadata values are the same you only need to enter the Endpoint value For the Endpoint field enter the fol lowing value http localhost 8080 MySTSProject MySTSService 7 Click OK to close this dialog 8 The service requires a token to be issued from the STS at http local host 8080 MySTSProject MySTSService with WSDL file http localhost 8080 MySTSProject MySTSService wsdl To do this fol low these steps a Right click the CalculatorWSServletClient node and select New Web Service Client The New Web Service Client window appears b Select the WSDL URL option c Cut and paste the URL of the web service that you want the client to consume into the WSDL URL field For example here is the URL for the MySTS web service http localhost 8080 MySTSProject MySTSService wsd1 d Type org me calculator client sts in the Package field and click Finish The Projects window displays the new web service client 9 Drill down from CalculatorWSServletClient Web Service References 10 Right click MySTSService select Edit Web Service Attributes
148. lt fully_qualified_hostname gt 8181 lt rest_of_url gt in the WSDL URL field of the New Web Service Client wizard For the example this is the way to specify the secure URL for CalculatorWS web service https lt fully_qualified_hostname gt 8181 CalculatorApplica tion CalculatorWSService wsdl NOTE If you prefer to use localhost in place of the fully qualified hostname when specifying the URL for the service WSDL you must fol low the workaround described in Transport Security SSL Workaround page 63 In the Projects window expand the client node Expand the Web Service References node Right click the node for the web service reference you want to secure Select Edit Web Service Attributes When the Web Service References Attributes Editor is opened select the WSIT tab to display the WSIT options see Figure 6 2 CalculatorwsServi E xj WSDL Customization i Transport Certificates Username Authentication Secure Token Service Cancel Help Figure 6 2 Web Service References Attributes Editor Page for Web Service Clients 51 USING WSIT SECURITY 6 Refer to Table 6 2 for a summary of what options are required on the client side The configuration requirements for the client are dependent upon which security mechanism is specified on the server side 7 Click OK to save your changes This information is saved in a WSDL file under Source Packag
149. ma annotation parame ters e elementFormDefault using Xm1Schema elementFormDefault O e attributeFormDefault using Xm1Schema attributeFormDefault e targetNamespace using Xm1Schema namespace e Associate namespace prefixes with the XML namespaces using the Xm1Schema ns annotation These XML namespace attributes are bound to NET serialization attributes for example Xm1Serializer attributes 176 DATA CONTRACTS Not Recommended Annotations Any JAXB 2 0 annotation can be used but the following are not recommended The javax xm l bind annotation Xm1ElementDecl annotation is used to provide complete XML schema support The Xm1ID and Xm1IDREF annotations are used for XML object graph serialization which is not well supported Web Service Start fom WSDL The following guidelines apply when designing a Java web service starting from a WSDL 1 If the WSDL was generated by DataContractSerializer enable JAXB 2 0 customizations described in Customizations for WCF Service WSDL page 177 The rationale for the JAXB 2 0 customizations is described in the same section If the WSDL is a result of contract first approach verify that the WSDL can be processed by either the DataContractSerializer or Xm1Serial izer mechanisms The purpose of this step is to ensure that the WSDL uses only the set of XML schema features supported by JAXB 2 0 or NET serialization mechanisms JAXB 2 0 was designed to support all the
150. method This is the start comment line that starts the sec tion that comments out the code TODO output your page here Delete the end comment line that ends the section of commented out code i4 Add some empty lines after the following line out println lt h1 gt Servlet ClientServlet at request getContextPath lt hl gt Right click in one of the empty lines that you added Choose Web Service Client Resources Call Web Service Operation The Select Operation to Invoke dialog box appears Browse to the Add operation and click OK The processRequest method looks as follows the added code is in bold below CREATING A CLIENT TO CONSUME A WSIT ENABLED WEB SERVICE 41 protected void processRequest HttpServletRequest request HttpServletResponse response throws ServletException IOException response setContentType text html charset UTF 8 PrintWriter out response getWriterQ out printinC lt htm1 gt out printIn lt head gt out printin lt title gt Servlet ClientServlet lt title gt out printIn lt head gt out printIn lt body gt out printIn lt hl gt Servlet ClientServlet at request getContextPath lt hl gt try Call Web Service Operation org me calculator client CalculatorWS port service getCalculatorWSPort TODO initialize WS operation arguments here int i 0 int j 0 TODO process result here int result port add i j system out print
151. mple Username Authentication with Symmetric Keys UA 97 Example Mutual Certificates Security MCS 100 Example Transport Security SSL 103 Example SAML Authorization over SSL SA 106 Example SAML Sender Vouches with Certificates SV 111 Example STS Issued Token STS 115 Example Other STS Examples 121 Further Information 121 WSITExample Using a Web Container Without NetBeans123 Environment Configuration Settings 124 Setting the Web Container Listener Port 124 Setting the Web Container Home Directory 125 WSIT Configuration and WS Policy Assertions 125 Creating a Web Service 126 Creating a Web Service From Java 126 Creating a Web Service From WSDL 129 Building and Deploying the Web Service 131 Building and Deploying a Web Service Created From Java 132 vi Chapter 8 Chapter 9 Chapter 10 CONTENTS Building and Deploying a Web Service Created From WSDL 133 Deploying the Web Service to a Web Container 133 Verifying Deployment 134 Creating a Web Service Client 135 Creating a Client from Java 136 Creating a Client from WSDL 138 Building and Deploying a Client 139 Running a Web Service Client 139 Undeploying a Web Service 139 Accessing WSIT Services Using WCF Clients 141 Creating a WCF Client 141 Prerequisites to Creating the WCF Client 142 The Client Class 142 Building and Running the Client 143 Data Contacts cece tt 47 Web Service Start from Java 147 DataTypes 148 Fields Properties 164
152. n STS page 116 e Creating and Securing the STS STS page 117 116 USING WSIT SECURITY Securing the Example Web Service Client Application STS page 119 Securing the Example Service Application STS The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing security to both the web service and to the web service client For this example the security mechanism of STS Issued Token page 66 is used to secure the application The steps are similar to the ones described in Example Username Authentication with Symmetric Keys UA page 97 with the addi tion of creating and securing an STS To add security to the service part of the example follow these steps 1 2 Create a user on GlassFish if you haven t already done so see Adding Users to GlassFish page 72 Create the CalculatorApplication example by following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet Expand CalculatorApplication Web Services then right click the node for the web service CalculatorWS and select Edit Web Service Attributes 4 Unselect the Reliable Messaging option if it is selecte
153. nd this only during development in your client code you can set the default host name verifier to a custom host name verifier which does a custom check An example is given below It is sometimes necessary to include this in the static block of your main Java class as shown below to set this verifier before any connections are made to the server static WORKAROUND TO BE REMOVED javax net ssl HttpsURLConnection setDefaultHostnameVeri fier new javax net ssl HostnameVerifierQ 64 USING WSIT SECURITY public boolean verify String hostname javax net ssl SSLSession sslSession if Chostname equalsC mytargethostname return true return false H Please remember to remove this once you install valid certificates on the server Message Authentication over SSL The Message Authentication over SSL mechanism attaches a cryptographically secured identity or authentication token with the message and use SSL for confi dentiality protection By default a Username Supporting Token will be used for message authentica tion To use an X 509 Supporting Token instead click the Configure button and select X509 Under this scenario you will need to configure your system for using SSL as described in Configuring SSL For Your Applications page 69 SAML Authorization over SSL The SAML Authorization over SSL mechanism attaches an authorization token with the message and uses SSL for confidentiality protection In t
154. ndpoint in turn sends the application messages along to the application If ordered delivery is configured optional the destina tion endpoint reconstructs a complete stream of messages for each sequence in the exact order in which the messages were sent and sends them along to the des tination application Thus through the use of the reliable messaging protocol the destination endpoint is able to provide the following delivery assurances to the web service application e Each message is delivered to the destination application at least once e Each message is delivered to the destination application at most once e Sequences of messages are grouped by sequence identifiers and delivered to the destination application in the order defined by the message numbers How THE WSIT TECHNOLOGIES WORK 17 Figure 1 7 shows a simplified view of client and web service application mes sage exchanges when the Reliable Messaging protocol is not used Web Service Client Web Service Endpoint JAX WS Application Messages JAX WS Client Server Runtime Runtime Figure 1 7 Application Message Exchange Without Reliable Messaging When the Reliable Messaging protocol is not used application messages flow over the HTTP connection with no delivery assurances If messages are lost in transit or delivered out of order the communicating endpoints have no way of knowing Figure 1 8 shows a simplified view of client and web service application mes s
155. node for the web service reference for which you want to configure security options SPECIFYING AN STS ON THE CLIENT SIDE 95 4 Select Edit Web Service Attributes When the Web Service References Attributes Editor is opened select the WSIT tab to display the WSIT options 5 Expand the Secure Token Service section to specify the information required by the service The following options are available for configura tion Endpoint The endpoint of the STS WSDL Location The location of the WSDL for the STS Metadata The metadata address for the STS Service Name The service name of the STS Port Name The port name of the STS Namespace The namespace for the service in the WSDL The Endpoint field is a mandatory field Depending on how you plan to configure the STS you can provide either Metadata information or infor mation regarding the WSDL Location Service Name Port Name and Namespace The following section contain a few example STS configura tions When the options are configured along the lines of STS Example 2 Endpoint with WSDL Location Service Name Port Name and Namespace page 96 the dialog looks like this 96 USING WSIT SECURITY calculatorwsService A WSDL Customization WSIT Configuration Transport Certificates Username Authentication Secure Token Service Endpoint jic svc Scenario_5_IssuedTokenForCertificate_MutualCertificate11 WSDL
156. ns ns1 http www w3 0rg 2005 05 xmlmime gt lt xs sequence gt lt xs complexType gt Using the XmlMimeType annotation doesn t change NET auto generated code public partial class claim object System Runtime Serialization IExtensibleDataObject private byte photoField 18 aa other gernerated code public byte photo 156 DATA CONTRACTS get return this photoField set this photoField value This code is unchanged by the different schema C code fragment try claim tmpC new claim System I0 FileStream f new System 10 FileStream C icons circleIcon gif System I0 FileMode Open int cnt Cint f Length tmpC photo new byte cnt int rCnt f Read tmpC photo 0 cnt catch Exception e Console WriteLine e ToStringQ XMLGregonanCalendar Guideline Use java xml datatype XMLGregorianCalendar instead of java util Date and java util Calendar XMLGregorianCalendar supports the following XML schema calendar types xsidate xs time xs dateTime xs gYearMonth xs gMonthDay xs gYear xs gMonth and xs gDay It is statically mapped to xs anySimpleType the common schema type from which all the XML schema calendar types are der vived NET maps xs anySimpleType to System string java util Date and java util Calendar map to xs dateTime but don t provide as complete XML support as XMLGregorianCalendar does Guideline Use annotation
157. oad Aliases button and select xws security server Click OK to close the dialog For this example the Truststore information that you need is specified by default so there is no need to change these settings EXAMPLE SAML SENDER VOUCHES WITH CERTIFICATES SV 9 Click OK to exit the WSIT Configuration editor A new file is added to the project To view the WSIT configuration file expand Web Pages gt WEB INF then double click the file wsit org me calculator CalculatorWS xm1 This file contains the sc Key Store and sc Truststore elements 10 Right click the CalculatorApplication node and select Run Project Accept the slas certificate if you are prompted to A browser will open and display the WSDL file for the application 11 Verify that the WSDL file contains the TransportBinding and Signed SupportingTokens element which in turn contains a Sam1Token element 12 Follow the steps to secure the client application as described in the next section Securing the Example Web Service Client Application SV This section demonstrates adding security to the web service client that refer ences the web service created in the previous section This web service is secured using the security mechanism described in SAML Sender Vouches with Certificates page 65 To add security to the client that references this web service complete the fol lowing steps 1 For this example we are using a non JSR 109 compliant client To do thi
158. om the Categories list select Java Classes From the File Types list select Empty Java File Click Next For Class Name enter Sam1CallbackHandler Click Finish The empty file displays in the IDE Download the example file Sam1Cal1backHandler java from the fol lowing URL https xwss dev java net servlets ProjectDocu mentList folderID 6645 amp expandFo 1 der 6645 amp fo 1 der ID 6645 110 NYDN Ff USING WSIT SECURITY n Open the file in a text editor o Modify the home variable to provide the hard coded path to your Glass Fish installation For example modify the line String home System getPropertyC WSIT_HOME to String home home glassfish p Copy the contents of this file into the Sam1CallbackHandler java window that is displaying in the IDE Drill down from CalculatorClient Web Service References Right click on CalculatorWSService select Edit Web Service Attributes Select the WSIT Configuration tab of the CalculatorWSService dialog Provide the client s private key by pointing to an alias in the keystore To do this expand the Certificates node click the Load Aliases button for the keystore and select xws security client from the Alias list NOTE If you are using a certificate other than the updated GlassFish cer tificates described in Updating GlassFish Certificates page 74 or are otherwise using a different alias for the client s private key alias correct
159. on another platform may result in less than devel oper friendly bindings This chapter discusses some of the common databinding differences between the two systems and recommends ways to address them Web Service Start from Java This section provides guidelines for designing a XML schema exported by a Java web service designed starting from Java JAXB 2 0 provides a rich set of annotations and types for mapping Java classes to different XML Schema con 147 148 DATA CONTRACTS structs The guidelines provide guidance on using JAXB 2 0 annotations and types so that developer friendly bindings may be generated by XML serialization mechanisms svcutil on WCF client Not all JAXB 2 0 annotations are included here not all are relevant from an interoperability standpoint For example the annotation Xm1lAccessorType pro vides control over default serialization of fields and properties in a Java class but otherwise has no effect on the on the wire XML representation or the XML schema generated from a Java class Select JAXB 2 0 annotations are therefore not included here in the guidance The guidance includes several examples which use the following conventions e prefix xs is used to represent XML Schema namespace e JAXB 2 0 annotations are defined in javax xm bind annotation pack age but for brevity the package name has been omitted DataTypes Primitives and Wrappers Guideline Java primitive and wrapper classes map to s
160. ontainer and NetBeans NOTE When creating an application using the wizards in NetBeans and running on GlassFish the Java EE Version defaults to Java EE 5 This results in an application compliant with JSR 109 Implementing Enter prise Web Services which can be read at http jcp org en jsr detail id 109 If you select a value other than the default for example J2EE 1 4 the application that is created is not JSR 109 compliant which means that the application is not JAX WS but is JAX RPC In the Projects window expand the Web Services node Right click the node for the web service you want to secure 4 Select Edit Web Service Attributes When the Web Service Attributes Editor is opened the WSIT Configura tion options display see Figure 6 1 SECURING THE SERVICE Calculatorws WSIT Configuration a CalculatorWSPortBinding I Optimize Transfer Of Binary Data MTOM I Reliable Message Delivery E Deliver Messages In Exact Order Advanced M Secure Service Security Mechanism MSEE E 141 a k Ben Configure Username authentication with symmetric keys for integrity and confidentiality protection Keystore Truststore Validators optional I Act As Secure Token Service STS Configure I Allow TCP Transport I Disable Fast Infoset 02 add Operation add Input Message Output Message Figure 6 1 Web Service Attributes Editor Page
161. onversation see Chapter 6 46 USING RELIABLE MESSAGING 6 Using WSIT Sec unty Tiss chapter describes how to use NetBeans Integrated Development Envi ronment the IDE to configure security for web services and web service clients using WSIT This release of WSIT makes securing web services even easier by including a set of preconfigured security mechanisms that can be applied to a web service or a web service operation simply by selecting it from a list You can use advanced configuration options to customize the security mechanism to the needs of your application This chapter covers the following topics e Configuring Security Using NetBeans IDE page 48 e Summary of Configuration Requirements page 52 e Security Mechanisms page 61 e Configuring SSL and Authorized Users page 68 e Configuring Keystores and Truststores page 74 e Securing an Operation page 85 e Configuring A Secure Token Service STS page 90 e Example Applications page 97 47 48 USING WSIT SECURITY Configuring Secunty Using NetBeans IDE This section contains the following topics e Securing the Service page 48 e Securing the Client page 50 Securing the Service To use the IDE to configure security for a web service and or a web service oper ation perform the following tasks 1 Create or open your web service If you need an example of how to create a web service refer to Chapter 2 WSIT Example Using a Web C
162. ortations et peuvent tre soumis au droit d autres pays dans le domaine des exportations et importations Les utilisations finales ou utilisateurs finaux pour des armes nucl aires des missiles des armes biologiques et chimiques ou du nucl aire maritime directe ment ou indirectement sont strictement interdites Les exportations ou r exportations vers des pays sous embargo des Etats Unis ou vers des entit s figurant sur les listes d exclusion d exportation am ricaines y compris mais de mani re non exclusive la liste de personnes qui font objet d un ordre de ne pas partic iper d une fa on directe ou indirecte aux exportations des produits ou des services qui sont r gi par la l gislation am ricaine en mati re de contr le des exportations U S Commerce Department s Table of Denial Orders et la liste de ressortissants sp cifiquement d sign s U S Treasury Department of Spe cially Designated Nationals and Blocked Persons sont rigoureusement interdites LA DOCUMENTATION EST FOURNIE EN L ETAT ET TOUTES AUTRES CONDITIONS DEC LARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE A L APTITUDE A UNE UTILISATION PARTICULIERE OU A L ABSENCE DE CONTREFA ON Chapter 1 Chapter 2 Contents About This Tutorial 0 00s VI a Web Container and NetB
163. ot provide defaults or leave all of these options blank and spec ify the username and password dynamically at runtime When using any of these options you must create an authorized user on GlassFish using the Admin Con sole as described in Adding Users to GlassFish page 72 Once you ve created an authorized user and determined how your application needs to specify the user configure the Username Authentication options as fol lows 1 In the Projects window expand the node for the web service client 2 Expand the Web Service References node 3 Right click the node for the web service reference for which you want to configure security options 4 Select Edit Web Service Attributes 5 Select the WSIT tab to display the WSIT options 6 Expand the Username Authentication section to specify the user name and password information as required by the service The dialog displays as follows 57 USING WSIT SECURITY ek CalculatorwSService me xi ation WSDL Customization Transport Certificates Username Authentication Authentication Credentials Static z Default Username l Default Password l SAML Callback Handler Browse Secure Token Service E Cancel Help Figure 6 3 WSIT Configuration Client Username Authentication 7 The following options are available NOTE Currently the GlassFish Cal1lbackHandler cannot handle t
164. pecify which parts of the message need to be encrypted signed and or required See the following section for more information on the options in the Message Parts dialog The Message Parts dialogue displays It should look like Figure 6 8 xl message Part Son enerypt Requre __Addeody L Add Header Add XPath i Remove From Addressing FaultTo Addressing ReplyTo Addressing MessagelD Addressing RelatesTo Addressing Action Addressing AckRequested RM Sequence cknowledgement RM Sequence RM WWIII gIIgga 5 AAA AA AAA Cancel Figure 6 8 Web Service Attributes Editor Page Operation Level 11 Click in a checkbox to the right of the message part or element that you would like to sign encrypt or require e Select Sign to specify the parts or elements of a message that require integrity protection digital signature e Select Encrypt to specify the parts or elements of a message that require confidentiality encryption e Select Require to specify the set of parts and or elements that a message must contain SUPPORTING TOKEN OPTIONS 12 Click Add Body to add a row for the message body This will only be nec essary if the row has been removed 13 Click Add Header to add a row for either a specific SOAP header part or for all SOAP header parts This will only be necessary if the SOAP header row in question has been deleted The header parts that are
165. perability effort to develop Java clients and service providers that interoperate with Microsoft NET 3 0 clients and service providers The tutorial consists of the following chapters This chapter the introduction introduces WSIT highlights the features of each WSIT technology describes the standards that WSIT implements for each technology and provides high level descriptions of how each tech nology works Chapter 2 provides instructions for creating deploying and testing Web service providers and clients using NetBeans IDE Chapter 3 describes how to create a WSIT client from a Web Service Description Language WSDL file Chapter 4 describes how to configure web service providers and clients to use message optimization Chapter 5 describes how to configure web service providers and clients to use reliable messaging Chapter 6 describes how to use the NetBeans IDE to configure web service providers and clients to use web services security Chapter 7 provides code examples and instructions for creating deploying and testing web service providers and clients using either of the supported web containers 2 INTRODUCTION e Chapter 8 describes how to build and run a Microsoft Windows Commu nication Foundation WCF client that accesses the addnumbers service described in Chapter 7 e Chapter 9 describes the best practices for production and consumption of data contracts for interoperability between WCF web services and Java
166. pleServiceClient client with the appropriate instance domain2 of the GlassFish server a Select File then Open Project 10 BUILDING DEPLOYING AND RUNNING THE BASICWSTX EXAMPLE 191 Browse to the lt wsit tutorial home gt examples wstx basicWSTX directory select the SampleServiceClient project and select Open Project Folder In the Projects tab right click SampleServiceClient select Properties then select the Run category Use the Server pulldown to point to domain2 e Click OK Create web service references for the client two web service clients a simpleServlet and a CMT EJB client and generate the WSDL for both a In the Projects tab right click SampleServiceClient select New then select Web Service Client Click Browse next to the Project field The Browse Web Services dialog is displayed Open SampleService war select Simple then click OK In the Package field enter wstx sample client then click Finish e Right click SampleServiceClient select New then select Web Service g h Client Click Browse next to the Project field The Browse Web Services dialog is displayed Open SampleService ejb select Simple ASCMTE Jb then click OK In the Package field enter wstx sample ejbclient then click Finish If transaction attributes for the servlet see Step 7 or CMT EJB web ser vice have changed those services must be deployed and client web ser vice referen
167. ps to a XML schema construct that is a repeating unbounded occurrence of an optional and nillable element NET binds the XML schema construct to System Nullable lt int gt The element is optional and nillable However when marshalling JAXB mar shaller will always marshal a null value using xsi nil Example Collection to a list of nillable elements Java code fragment Xm1RootE1ement name po public PurchaseOrder public List lt Integer gt items Schema fragment lt xs element name po type purchaseOrder gt lt xS complexType name purchaseOrder gt lt xsS Sequence gt lt xs element name items type xs int nillable true minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs complexType gt JAXB XML serialization lt po gt lt items gt 1 lt items gt lt items gt 2 lt items gt lt items gt 3 lt items gt lt po gt lt po gt lt items gt 1 lt items gt lt items xsi inil true gt lt items gt 3 lt items gt lt po gt NET auto generated code from schema partial class purchaseOrder private System Nullable lt int gt itemsField public System Nullable lt int gt items get return this itemsField set this itemsField value 162 DATA CONTRACTS List of optional elements This is the same as above except that a collection type such as List lt Integer gt maps to a repeating unbounded occurrenc
168. quires that data be transmitted so as to prevent other entities from observing the contents of the transmission h The IDE looks like this E NetBeans IDE 5 5 1 CalculatorApplication le x File Edit View Navigate Source Refactor Buld Run CVS Tools Window Help b e e ajya sarees Tropas a x EE Runtime Ci x Ebi B CalculatorApplication Security XML f _Constre Gal Web Pages ES WEB INF Login Configuration M E wsdl G sun web xml Security Roles C3 Webs weit org me calculator Calculatorw lt Role Name Description index jsp Add Eat Remove 5 3 Web Services L N E _ S Calculatorws I Security Constraints Add Security Constraint CA Configuration Files G3 Server Resources Constraint1 Remove amp Source Packages iz Test Packages HFA Lihrariac Display Name Constraint gt a Web Resource Collection Navigator web xml ax version 1 0 encoding UTF 8 Name URL Pattern HTTP Method Description gt web app xmins xsi htip 3 0rg 2 valcWebResource a POST Add Edit Remove T Enable Authentication Constraint Description Role Name s Edit T Enable User Data Constraint Description Traneport Guar E gt a Filters Tene Syl Figure 6 4 Deployment Descriptor page i Click the XML tab to display the additions to web xm1 The security constraint looks like t
169. raphic algorithm For example in encryption a key specifies the particular transformation of plaintext into cipher text or vice versa during decryption Keys are used in digital signatures for authentication To configure a keystore on a service perform the following steps 1 Check the table in Summary of Service Side Configuration Requirements page 52 to see if a keystore needs to be configured for the selected secu rity mechanism If so continue 2 Right click the web service and select Edit Web Service Attributes The Web Service Attributes editor is displayed 3 Enable Secure Service then select a security mechanism 4 Check the tables in Summary of Service Side Configuration Requirements page 52 to see what keystore configuration if any is required for that mechanism 78 USING WSIT SECURITY 5 Click the Keystore button The following dialog displays Keystore Configuration ma xi Location sh domains domain1 config keystore jks Browse Keystore Password Pens Key Password Figure 6 5 Keystore Configuration dialog 6 Depending on what is required for the selected mechanism you may spec ify the following information in the Keystore Configuration dialog Location Use the Browse button to specify the location and name of the keystore By default this field specifies the GlassFish keystore file lt AS_HOME gt domains domain1l config keystore jks Keystore Password Specifies
170. rate the C proxy class and contracts for accessing the web service 2 Create a client program that uses the generated files to make calls to the addnumbers web service 141 142 ACCESSING WSIT SERVICES USING WCF CLIENTS Prerequisites to Creating the WCF Client You must have the following software installed to create the WCF client e Microsoft Windows Software Development Kit SDK for July Commu nity Technology Preview e Microsoft NET Framework 3 0 RTM e the csclient enabled fromjava zip example bundle which you can download from https wsit dev java net source browse check out wsit wsit docs howto csclient enabled fromjava zip You must also deploy the addnumbers service described in Chapter 7 You can download the service from https wsit dev java net source browse checkout wsit wsit docs howto wsit enabled fromjava zip The Client Class The client class uses a generated proxy class AddNumbersImp1 to access the web service The port instance variable stores a reference to the proxy class port new AddNumbersImp1ClientC AddNumbersImp1Port Then the web service operation addNumbers is called on port int result port addNumbers number1 number2 The following is the full Client cs class using System class Client static void Main String args AddNumbersImp1Client port null try port new AddNumbersImplClient AddNumbersImplPort int number1 10 int number2 20 Console Write
171. re files to the appropriate location and import the appropriate certificates into the GlassFish keystore and truststore This Ant command is simply lt AS_HOME gt lib ant bin ant The command window will echo back the certificates that are being added to the keystore and truststore files and should look something like this echo WARNING currently we add non CA certs to GF trust store this will not be required in later releases when we WSIT starts supporting CertStore s java Added Key Entry xws security server java Added Key Entry xws security client java Added Trusted Entry xwss certificate authority java Added Key Entry wssip java Added Trusted Entry xws security client java Added Trusted Entry xws security server java Added Trusted Entry wssip echo Adding JVM Option for https outbound alias this will take atleast One Minute If you d like to verify that the updates were successful follow these steps a Change to the directory containing the GlassFish keystore and truststore files lt AS_HOME gt domains domain1 config b Verify that the v3 certificate has been imported into the GlassFish trust store To do this run the following keytool command lt JDK_HOME gt bin keytool list keystore cacerts jks alias wssip storepass changeit If the certificates are successfully updated your response will look something like this wssip Aug 20 2007 trustedCertEntry Certificate fingerprint
172. re usually faster than public key cryptography For this mechanism the client does not possess any certificate key of his own but instead sends its username password for authentication The client shares a secret key with the server The shared symmetric key is generated at runtime and encrypted using the service s certificate The client must specify the alias in the truststore by identifying the server s certificate alias See Also Example Username Authentication with Symmetric Keys UA page 97 62 USING WSIT SECURITY Mutual Certificates Sec unty The Mutual Certificates Security mechanism adds security via authentication and message protection that ensures integrity and confidentiality When using mutual certificates a keystore and truststore file must be configured for both the client and server sides of the application See Also Example Mutual Certificates Security MCS page 100 Transport Sec unty SSL The Transport Security mechanism protects your application during transport using SSL for authentication and confidentiality Transport layer security is pro vided by the transport mechanisms used to transmit information over the wire between clients and providers thus transport layer security relies on secure HTTP transport HTTPS using Secure Sockets Layer SSL Transport security is a point to point security mechanism that can be used for authentication mes sage integrity and confidentiality When runnin
173. repass Cchangeit alias xws security server keypass changeit gt lt sc TrustStore wspp visibility private location C Sun glassfish domains domainl config cacerts jks storepass changeit peeralias xws security server gt lt wsp Al1 gt 9 Compile and run this application by right clicking on the Calculator WSServletClient node and selecting Run Project Example Transport Sec unty SSL This section includes the following topics e Securing the Example Service Application SSL page 103 e Securing the Example Web Service Client Application SSL page 105 Securing the Example Service Application SSL The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing transport security to both the web service and to the web service client For this example the security mechanism of Transport Security SSL page 62 is used to secure the application To add security to the service part of the exam ple follow these steps 1 Create the CalculatorApplication example by following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet 104 USING WSIT SECURITY 2 Expand Calcula
174. ric key Symmetric key cryptography relies on a shared secret and is usually faster than public key cryptography Pub lic key cryptography relies on a key that is made public to all and is pri marily used for encryption but can be used for verifying signatures 18 Click OK to close the Select STS Service Provider dialog 19 Click OK to close the STS Configuration dialog 20 Click the Keystore button to configure the keystore If you are using the updated GlassFish stores these are the settings Location Defaults to the location and name of the keystore lt AS_HOME gt domains domain1 config keystore jks Store Password Enter or accept changeit Load Aliases Click the Load Aliases button Alias Select wssip Click OK to close the dialog 21 Right click the STS Project select Properties Select the Run category and enter the following in the Relative URL field lt your_STS gt Service wsdl 22 Run the Project right click the Project and select Run Project 23 To view the STS WSDL append lt your_STS gt Service to the URL of the deployed application in the browser For the example application Exam ple STS Issued Token STS page 115 you would view the STS WSDL 93 94 USING WSIT SECURITY by browsing to http localhost 8080 MySTSProject MySTSService wsdl Specifying an STS on the Service Side This section discusses how to specify a Security Token Service that can be refer enced by the service On t
175. s create the client application up to the step where you create the Servlet step 7 as of this writing by following the steps described in Creating a Client to Consume a WSIT Enabled Web Service page 29 with one exception name the application CalculatorClient since it s not a servlet 2 Instead of creating a client servlet as is described in Creating a Client to Consume a WSIT Enabled Web Service page 29 we are just going to add the web service operation to the generated index jsp file to create a non JSR 109 client To do this a If the index jsp file is not open in the right pane double click it to open it b Drill down through the Web Service References node until you get to the add operation c Drag the add operation to the line immediately following the following line 113 114 USING WSIT SECURITY lt h1 gt JSP Page lt h1 gt d Edit the values for i and j if you d like 3 Write a SAMLCallback handler for the client side to populate a SAML assertion into the client s request to the service A suggested method for creating the SAMLCal1backHandler is shown below Right click on the CalculatorClient node Select New Java Package For Package Name enter xwss saml Click Finish Drill down from CalculatorClient Source Packages xwss saml Right click on xwss saml Select New File Folder From the Categories list select Java Classes soe meoenunaecr From the File Typ
176. s specifying 76 annotations WebService 24 128 application messages being lost 5 Application Server adding users to 72 73 authentication credentials 58 B binary objects encoding 4 bootstrapping and configuration 3 process steps 3 C Certificate Validator field 85 certificates digital 62 v3 74 validating 85 Client Service Trust Requirements page 48 51 81 95 Client Service WSS Requirements page 48 51 81 95 Index clients web service securing 48 client side proxy 5 D derived session keys 6 E Edit Web Service Attributes 48 94 endpoints descriptions 33 references 33 server side 33 examples required software viii F flow control 44 I inactivity timeout 44 J Java file 193 194 INDEX annotations 24 38 128 skeleton 25 JAX WS defined 1 K keystore aliases 76 configuring 77 Keystore Configuration options 77 80 84 86 Keystore Configuration page 48 51 81 95 keystores alias 78 93 configuring 48 50 51 74 77 80 81 84 86 95 location 78 93 M Message Elements Parts to Sign and En crypt 48 51 81 95 message optimization binary objects 4 description 4 network performance 4 secure conversation 42 messages encrypting elements 48 51 81 95 encrypting parts 48 51 81 95 securing 85 signing elements 48 51 81 95 signing parts 48 51 81 95 MetadataExchangeRequest 3 multiple message exchange sequence 6 N network connections being dropp
177. s implemented using the following specifications e WSDL The Web Services Description Language WSDL specification was previously implemented in JAX WS WSDL is a standardized XML format for describing network services The description includes the name of the service the location of the service and ways to communicate with the service that is what transport to use WSDL descriptions can be stored in service registries published on the Internet or both e Web Services Policy This specification provides a flexible and extensible grammar for expressing the capabilities requirements and general charac teristics of a web service It provides the mechanisms needed to enable web services applications to specify policy information in a standardized way However this specification does not provide a protocol that consti tutes a negotiation or message exchange solution for web Services Rather it specifies a building block that is used in conjunction with the WS Meta data Exchange protocol When applied in the web services model policy is used to convey conditions on interactions between two web service end points Typically the provider of a web service exposes a policy to convey conditions under which it provides the service A requester might use the policy to decide whether or not to use the service e Web Services Metadata Exchange This specification defines a protocol to enable a consumer to obtain a web service s metadata that i
178. s its WSDL and policies It can be thought of as a bootstrap mechanism for communi cation 10 INTRODUCTION Message Optimization Specific ations Message optimization is the process of transmitting web services messages in the most efficient manner It is achieved in web services communication by encoding messages prior to transmission and then de encoding them when they reach their final destination Figure 1 4 shows the specifications that were implemented to optimize commu nication between two web service endpoints SOAP MTOM Optimization Web Services Standards Secure Conversation Supporting Standard Core Standards Previously implemented in JAX Web Services Figure 1 4 Message Optimization Specifications In addition to the Core XML specifications optimization was implemented using the following specifications e SOAP JAX Web Services currently supports the SOAP wire protocol With SOAP implementations client requests and web service responses are most often transmitted as Simple Object Access Protocol SOAP mes sages over HTTP to enable a completely interoperable exchange between clients and web services all running on different platforms and at various locations on the Internet HTTP is a familiar request and response standard for sending messages over the Internet and SOAP is an XML based pro tocol that follows the HTTP request and response model In SOAP 1 1 the SOAP portion of a transported mess
179. s file contains the sc KeyStore element 19 Right click the MySTSProject tab select Properties Select the Run cate gory and enter the following in the Relative URL field MySTSSer vice wsdl 20 Run the Project right click the project and select Run Project The STS WSDL displays in the browser 21 Follow the steps to secure the client application as described in the next section Securing the Example Web Service Client Application STS This section demonstrates adding security to the CalculatorApplication s web service client which was secured using the security mechanism described in STS Issued Token page 66 To add security to the client complete the following steps 1 Create the client application by following the steps described in Creating a Client to Consume a WSIT Enabled Web Service page 29 NOTE Whenever you make changes on the service refresh the client so that the client will pick up the change To refresh the client right click the node for the Web Service Reference for the client and select Refresh Cli ent 2 Drill down from CalculatorWSServletClient Web Service References 3 Right click on CalculatorWSService select Edit Web Service Attributes Select the WSIT Configuration tab 4 Provide the client s private key by pointing to an alias in the keystore To do this expand the Certificates node click the Load Aliases button for the keystore and select xws security client from the Alias
180. s is to share data among applica tions over the Internet The data shared can vary in format and include large binary payloads such as documents images music files and so on When large binary objects are encoded into XML format for inclusion in SOAP messages even larger files are produced When a web service processes and transmits these large files over the network the performance of the web service application and the network are negatively affected In the worst case scenario the effects are as follows e The performance of the web service application degrades to a point that it is no longer useful e The network gets bogged down with more traffic than the allotted band width can handle One way to deal with this problem is to encode the binary objects so as to opti mize both the SOAP application processing time and the bandwidth required to transmit the SOAP message over the network In short XML needs to be opti mized for web services This is the exactly what the Message Optimization tech nology does It ensures that web services messages are transmitted over the Internet in the most efficient manner Sun recommends that you use message optimization if your web service client or web service endpoint will be required to process binary encoded XML docu ments larger than 1KB For instructions on how to use the Message Optimization technology see Chap ter 4 WHAT IS WSIT 5 Reliable Messaging Technology Reliable Messa
181. s issued by a designated STS An endorsing token is used to sign the message signature In this mechanism message integrity and confidentiality are protected using ephemeral keys encrypted for the service Ephemeral keys use an algorithm where the exchange key value is purged from the cryptographic service provider CSP when the key handle is destroyed The service requires messages to be endorsed by a SAML token issued by a designated STS 67 68 USING WSIT SECURITY Service providers and consumers are in potentially different managed environ ments For this mechanism the service requires that secure communications be endorsed by a trusted STS The service does not trust the client directly but instead trusts tokens issued by a designated STS In other words the STS is tak ing on the role of a second service with which the client has to securely authenti cate For this mechanism authentication of the client is achieved in this way e The client authenticates with the STS and obtains the necessary token with credentials e The client s request is signed and encrypted using ephemeral key K e The server s response is signed and encrypted using the same K e The primary signature of the request is endorsed using the issued token To use this mechanism for the web service you simply select this option as your security mechanism However you must have a Security Token Service that can be referenced by the service An exampl
182. sage Optimization in a Web Service page 38 e Deploying and Testing a Web Service page 39 e Creating a Client to Consume a WSIT enabled Web Service page 39 e Message Optimization and Secure Conversation page 42 37 38 MESSAGE OPTIMIZATION Creating a Web Service The starting point for developing a web service to use the WSIT technologies is a Java class file annotated with the javax jws WebService annotation For detailed instructions for how to use NetBeans IDE to create a web service see Creating a Web Service page 24 Configuring Message Optimization ina Web Service To use the IDE to configure a web service for message optimization perform the following steps 1 In the IDE Projects window expand the Web Services node right click the CalculatorWS node and choose Edit Web Service Attributes as shown in Figure 4 1 The Web Service Attributes editor appears Projects i x Files Runtime 5 CalculatorApplication H O Web Pages GQ Web Services a add OPen GQ Configuration F iw Server Resourc Add Operation GQ Source Package H Q Test Packages Test Web Service i ad Libraries Edit Web Service Attributes 6 Test Libraries Configure Handlers Delete Delete Properties Figure 4 1 Selecting the Edit Web Services Attributes Option 2 Select the Optimize Transfer of Binary Data MTOM check box as shown in Figure 4 2 and click Ok Calculatorws WSIT Configuration
183. sed to secure the application The steps are similar to the ones described in Example Username Authentication with Symmetric Keys UA page 97 with the addition of the writing of a client side SAML callback handler to populate the client s request with a SAML assertion To add security to the service part of the example follow these steps 1 If you haven t already completed these steps complete them now a Update the GlassFish keystore and truststore files as described in Updat ing GlassFish Certificates page 74 b Create a user on GlassFish as described in Adding Users to GlassFish page 72 Create the CalculatorApplication example by following the steps described in the following sections of Chapter 2 WSIT Example Using a Web Container and NetBeans a Creating a Web Service page 24 b Skip the section on adding Reliable Messaging c Deploying and Testing a Web Service page 28 first two steps only do not run the project yet Expand CalculatorApplication Web Services then right click the node for the web service CalculatorWS and select Edit Web Service Attributes 4 Unselect the Reliable Messaging option if it is selected Select Secure Service From the drop down list for Security Mechanism select SAML Sender Vouches with Certificates Click the Keystore button to provide your keystore with the alias identify ing the service certificate and private key To do this click the L
184. services providers How the WSIT technologies Work The following sections provide a high level description of how the messaage optimization reliable messaging and security technologies work How THE WSIT TECHNOLOGIES WORK 15 How Message Optimization Works Message optimization ensures that web services messages are transmitted over the Internet in the most efficient manner Because XML is a textual format binary files must be represented using character sequences before they can be embedded in an XML document A popular encoding that permits this embed ding is known as base64 encoding which corresponds to the XML Schema data type xsd base64Binary In a web services toolkit that supports a binding frame work a value of this type must be encoded before transmission and decoded before binding The encoding and decoding process is expensive and the costs increase linearly as the size of the binary object increases Message optimization enables web service endpoints to identify large binary message payloads remove the message payloads from the body of the SOAP message encode the message payloads using an efficient encoding mechanism effectively reducing the size of the payloads re insert the message payloads into the SOAP message as attachments the file is linked to the SOAP message body by means of an Include tag Thus message optimization is achieved by encoding binary objects prior to transmission and then de encoding them when th
185. t port addNumbers number1 number2 System out printf The result of adding d and d is d n n numberl1 number2 result numberl 10 System out printf Invoking addNumbers d d n number1 number2 result port addNumbers number1 number2 System out printf The result of adding d and d is d n CREATING A WEB SERVICE CLIENT 137 numberl1 number2 result catch AddNumbersException_Exception ex System out printf Caught AddNumbersException_Exception s n ex getFaultInfo getDetail finally CCCloseable port closeQ This file specifies two positive integers that are to be added by the web service passes the integers to the web service and gets the results from the web service via the port addNumbers method and prints the results to the screen It then specifies a negative number to be added gets the results which should be an exception and prints the results the exception to the screen Client Configuration Fille fromjava The client configuration file defines the URL of the web service WSDL file It is used by the web container wsimport tool to access and consume the WSDL and to build the stubs that are used to communicate with the web service The custom client xm1 file provided in the wsit enabled fromjava sample is shown below The wsd1lLocation and the package name xml tags are unique to each client and are highlighted in bold text lt xml version 1 0 enco
186. t includes application programming interfaces APIs for building secure reliable transacted web services that interoperate with non Microsoft platforms In a joint effort Sun Microsystems and Microsoft are testing WSIT against WCF to ensure that Sun web service clients consumers and web services producers do in fact interoperate with WCF web services applications and vice versa The testing will ensure that the following interoperability goals are realized e WSIT web services clients can access and consume WCF web services e WCF web services clients can access and consume WSIT web services Sun is building WSIT on the Java platform and Microsoft is building WCF on the NET 3 0 platform The sections that follow describe the web services speci fications implemented by Sun Microsystems in Web Services Interoperability Technologies WSIT and provide high level descriptions of how each WSIT technology works Note Because WSIT based clients and services are interoperable you can gain the benefits of WSIT without using WCF WSIT Spec if ations The specifications for bootstrapping and configuration message optimization reliable messaging and security technologies are discussed in the following sec tions e Bootstrapping and Configuration Specifications page 8 e Message Optimization Specifications page 10 e Reliable Messaging Specifications page 12 e Security Specifications page 13 WSIT 1 0 implements the following
187. t URI Guideline Use the Xm1SchemaType annotation for a strongly typed binding to a NET client generated with the DataContractSerializer java net URI maps to xs string NET maps xs string to System string Annotation Xm1SchemaType can be used to define a more strongly typed bind ing to a NET client generated with the DataContractSerializer Xm1Sche maType can be used to map java net URI to xs anyURI NET s DataContractSerializer and Xm1Serializer bind xs anyURI differently e DataContractSerializer binds xs anyURI to NET type System Uri e XmlSerializer binds xs anyURI to NET type System string Thus the above technique only works if the WSDL is processed using DataCon tractSerializer Example Xm1SchemaType and DataContractSerializer Java code fragment public class PurchaseOrder Xm1 SchemaType name anyURI public java net URI uri Schema fragment lt xS complexType name purchaseOrder gt lt xS Sequence gt lt xs element name uri type xs anyURI minOccurs 0 gt lt xsS sequence gt lt xs complexType gt NET auto generated code from schema Using svcutil exe serializer DataContractSerializer lt wsdl file gt public partial class purchaseOrder object System Runtime Serialization IExtensibleDataObject private System Uri uriField JJ iaaa other gernerated code public System Uri uri 152 DATA CONTRACTS get return this uriField
188. t enabled fromjava example the ant target build server java in build xml handles this portion of the process Next the indi vidual class files are bundled together along with the web service s supporting configuration files into the application s WAR file It is this file that is deployed to the web container by the deploy target During execution of the server target you will see a warning message The message refers to Annotation types without processors The warning is expected and does not indicate an abnormal situation The text is included here for reference bui 1ld server java apt warning Annotation types without processors javax xml bind annotation Xm1RootElement javax xml bind annotation XmlAccessor Type javax xml bind annotation XmlType javax xml bind annotation XmlElement apt 1 warning BUILDING AND DEPLOYING THE WEB SERVICE 133 Building and Deploying a Web Service Created From WSDL To build and deploy the web service open a terminal window go to the lt INSTALL gt wsit enabled fromjava directory and type the following ant server This command calls wsimport which takes the WSDL description and gener ates a corresponding Java interface and other supporting classes Then the Java compiler is called to compile both the user s code and the generated code Finally the class files are bundled together into the WAR file To see the details of how this is done see the build server wsd1 and creat
189. t the client will pick up the change To refresh the client right click the node for the Web Service Reference for the client and select Refresh Cli ent 2 Compile and run this application by right clicking on the Calculator WSServletClient node and selecting Run Project Example SAML Authonzation over SSL SA The section includes the following topics e Securing the Example Service Application SA page 106 e Securing the Example Web Service Client Application SA page 108 Securing the Example Service Application SA The following example application starts with the example provided in Chapter 2 WSIT Example Using a Web Container and NetBeans and demonstrates add ing security to both the web service and to the web service client For this example the security mechanism of SAML Authorization over SSL page 64 is used to secure the application The steps are similar to the ones described in Example Username Authentication with Symmetric Keys UA page 97 with the addition of the writing of a client side SAML callback han dler to populate the client s request with a SAML assertion To add security to the service part of the example follow these steps 1 If you haven t already completed these steps complete them now a Update the GlassFish keystore and truststore files as described in Updat ing GlassFish Certificates page 74 b Create a user on GlassFish as described in Adding Users to GlassFish page 72
190. tc wsit fromjava server AddNumber sImp1 xml wsit enabled fromjava etc custom schema xm wsit enabled fromjava etc custom client xm wsit enabled fromjava etc bui ld properties wsit enabled fromwsdl etc custom client xml wsit enabled fromwsd1 etc build properties WSIT CONFIGURATION AND WS POLICY ASSERTIONS 125 Setting the Web Container Home Directory Before building and deploying the web service and its client the home directory of the web container must be set as an environment variable When you are running from the command line you should set the appropriate environment variable to the web container s top level installation directory This way you will not have to manually set the environment variable each time you open a new command window For GlassFish the AS_HOME environment variable should be set to the top level directory of GlassFish for example on Windows C Sun glassfish For Apache Tomcat set the CATALINA_HOME environment variable to the Tomcat top level directory WSIT Configuration and WS Policy Assertions WSIT features are enabled and configured using a mechanism defined by the Web Services Policy Framework WS Policy specification A web service expresses its requirements and capabilities via policies embedded in the service s WSDL description A web service consumer or client verifies that it can handle the expressed requirements and optionally uses server capabilities advertised in policies
191. ted GlassFish certificates See Also Example STS Issued Token STS page 115 STS Issued Token with Service Certificate This security mechanism is similar to the one discussed in STS Issued Token page 66 with the difference being that in addition to the service requiring the client to authenticate using a SAML token issued by a designated STS confiden tiality protection is achieved using a service certificate A service certificate is used by a client to authenticate the service and provide message protection For GlassFish a default certificate of slas is installed To use this mechanism for the web service you simply select this option as your security mechanism However you must have a Security Token Service that can be referenced by the service An example of an STS can be found in the section Creating and Securing the STS STS page 117 In this section you select a security mechanism for the STS The security configuration for the client side of this application is dependent upon the security mechanism selected for the STS and not on the security mechanism selected for the application The client trust store must contain the certificate of the STS which has the alias of wssip if you are using the updated GlassFish certificates STS Issued Endorsing Token This security mechanism is similar to the one discussed in STS Issued Token page 66 with the difference being that the client authenticates using a SAML token that i
192. that implements the protocol defined in the WS Trust speci fication you can find a link to this specification at https wsit dev java net This protocol defines message formats and message exchange patterns for issuing renewing canceling and validating security tokens Service providers and consumers are in potentially different managed environ ments but use a single STS to establish a chain of trust The service does not trust the client directly but instead trusts tokens issued by a designated STS In other words the STS is taking on the role of a second service with which the client has to securely authenticate The issued tokens contain a key which is encrypted for the server and which is used for deriving new keys for signing and encrypting To use this mechanism for the web service you simply select this option as your security mechanism However you must have a Security Token Service that can STS ISSUED TOKEN WITH SERVICE CERTIFICATE be referenced by the service An example of an STS can be found in the section Creating and Securing the STS STS page 117 In this section you select a security mechanism for the STS The security configuration for the client side of this application is dependent upon the security mechanism selected for the STS and not on the security mechanism selected for the application The client trust store must contain the certificate of the STS which has the alias of wssip if you are using the upda
193. the Web Service Now that you have coded a web service you can configure the web service to use WSIT technologies This section only describes how to configure the WSIT Reliable Messaging technology For a discussion of reliable messaging see Chapter 5 To see how to secure the web service see Chapter 6 To configure a web service to use the WSIT Reliable Messaging technology per form the following steps 1 In the Projects window expand the Web Services node under the Calcula torApplication node right click the CalculatorWS node and choose Edit Web Service Attributes as shown in Figure 2 1 CONFIGURING WSIT FEATURES IN THE WEB SERVICE Projects x Files Runtime 5 CalculatorApplication H Web Pages GQ Web Services a Calculator Wye add OPen H E Configuration F Server Resourc Add Operation GQ Source Package H Test Packages Test Web Service Configure Handlers Delete Properties Figure 2 1 Accessing the Edit Web Service Attributes The Web Service Attributes Editor appears Delete H Libraries Edit Web Service Attributes H E Test Libraries 27 2 Select the Reliable Message Delivery check box as shown in Figure 2 2 and click OK CalculatorWS WSIT Configuration CalculatorWSPortBinding C Optimize Transfer Of Binary Data MTOM Deliver Messages In Exact Order Figure 2 2 Reliable Messaging Configuration Window This setting
194. the password for the keystore file If you are running under GlassFish GlassFish s password is already entered If you have changed the keystore s password from the default you must specify the correct value in this field Load Aliases Click the Load Aliases button to populate the Alias field with the aliases contained in the keystore file The Location and Store Password fields must be specified correctly for this option to work Alias Specifies the alias of the certificate in the specified keystore to be used for authentication Refer to the table in Specifying Aliases with the Updated Stores page 76 to determine which alias to choose for the selected security mechanism Key Password Specifies the password of the key within the keystore For this sample leave this blank For this field the default assumes the key password is the same as the store password so you only need to specify this field when the key password is different NOTE The Key Password field enables you to specify a password for the keystore used by the application When specified this password is stored in a WSIT configuration file in clear text which is a security risk Setting the keystore password in the development environment is fine however when you go into production remember to use the container s Callback Handler to obtain the keys from the keystore This eliminates the need for CONFIGURING THE KEYSTORE AND TRUSTSTORE the keystore passwords
195. the private key alias in the line in the SAMLCallbackHandler java file that looks like this String client_priv_key_alias xws security client NOTE If you are using different keystore truststore files than those described in Updating GlassFish Certificates page 74 edit the following code in the SAMLCal1backHand1er java file accordingly this keyStoreURL home fileSeparator domains fileSeparator fileSeparator config domain1 fileSeparator keystore jks this keyStoreType JKS this keyStorePassword changeit this trustStoreURL home fileSeparator domains fileSeparator domainl fileSeparator config fileSeparator cacerts jks this trustStoreType JKS this trustStorePassword changeit Provide the server s certificate by pointing to an alias in the client trust store To do this from the Certificates node click the Load Aliases button for the Truststore and select xws security server EXAMPLE SAML SENDER VOUCHES WITH CERTIFICATES SV 111 9 Expand the Username Authentication node In the SAML Callback Han dler field enter the name of the class written in step 3 above xwss saml1 Sam1CallbackHand er 10 Click OK to close this dialog 11 In the tree drill down from the project to Source Packages META INF Double click on CalculatorWSService xml and verify that lines similar to the following are present where xwss sam Sam1Cal1lbackHand er is the S
196. tin lt body gt out printin lt html1 gt out close 16 Change the value for int i and int j to other numbers such as 3 and 4 17 Add a line that prints out an exception if an exception is thrown The try 18 catch block is follows new and changed lines from this step and the pre vious step are highlighted in bold text try Call Web Service Operation org me calculator client CalculatorWS port service getCalculatorWSPort TODO initialize WS operation arguments here int i 3 int j 4 TODO process result here int result port add i j out printin lt p gt Result result catch Exception ex out printin lt p gt Exception ex If Reliable Messaging is enabled the client needs to close the port when done or the server log will be overwhelmed with messages To close the port first add the following line to the import statements at the top of the file import com sun xml ws Closeable Then add the line in bold at the end of the try block as shown below try Call Web Service Operation org me calculator client CalculatorWS port service getCalculatorWSPort TODO initialize WS operation arguments here int i 3 int j 4 TODO initialize WS operation arguments here int i 3 int j 4 TODO process result here int result port add i j 32 WSIT EXAMPLE USING A WEB CONTAINER AND NETBEANS out printInC lt p gt Result res
197. to be supplied by the users You can also specify the passwords for keystores and truststores by specifying a Callback Han dler class that implements the javax security auth callback Cal1 backHandler interface in the Key Password or Store Password fields When creating JSR 109 compliant application GlassFish will only use the default CallbackHandlers and Validators and you cannot override the location of the keystore and truststore files Any attempt to override the default location will be ignored You do however need to specify the keystore and truststore locations in these dialogs in order to specify the alias When creating non JSR 109 compliant application you can specify the passwords for keystores and truststores by specifying a Cal lbackHandler class that implements the javax security auth callback Callback Handler interface in the Key Password or Store Password fields 7 Click OK to close the dialog Configuring the Truststore on a Service A truststore is a database of trusted entities and their associated X 509 certificate chains authenticating the corresponding public keys The truststore contains the Certificate Authority CA certificates and the certifi cate s of the other party to which this entity intends to send encrypted confi dential data This file must contain the public key certificates of the CA and the client s public key certificate Any kind of encryption without WS SecureCon versation will generally
198. torApplication Web Services then right click the node for the web service CalculatorWS and select Edit Web Service Attributes 3 Unselect Reliable Messaging if it is selected 4 Select Secure Service 5 From the drop down list for Security Mechanism select Transport Secu rity SSL 6 Click OK to close the WSIT Configuration dialog A new file is added to the project To view the WSIT configuration file expand Web Pages WEB INF then double click the file wsit org me calculator Calculatorws xml NOTE For Transport Security the keystore and truststore files are config ured outside of the NetBeans UI in GlassFish The keystore and truststore files for basic SSL come pre configured with GlassFish so there are no additional steps required for this configuration To require the service to use the HTTPS protocol you have to specify the security requirements in the service s application deployment descriptor which is web xml for a web service implemented as a servlet To specify the security information follow these steps From your web service application expand Web Pages gt WEB INF Double click web xm1 to open it in the editor Select the Security tab On the Security Constraints line click Add Security Constraint Under Web Resource Collection click Add Enter a Name for the Resource CalcWebResource Enter the URL Pat tern to be protected Select which HTTP Methods to protect for
199. tore Password Specifies the password for the truststore If you are using GlassFish the value of changeit is already entered If you have changed the value of the truststore password you must enter the new value in this field NOTE The Store Password field enables you to specify a password for the truststore used by the application When specified this password is stored in a WSIT configuration file in clear text which is a security risk Setting the truststore password in the development environment is fine however when you go into production remember to use the container s Callback Handler to obtain the keys from the truststore This eliminates the need for the truststore passwords to be supplied by the users You can also specify the passwords for keystores and truststores by specify ing a CallbackHandler class that implements the javax secu rity auth callback CallbackHandler interface in the Key Password or Store Password fields When creating JSR 109 compliant application GlassFish will only use the default CallbackHandlers and Validators and you cannot override the location of the keystore and truststore files Any attempt to override the default location will be ignored You do however need to specify the keystore and truststore locations in these dialogs in order to specify the alias CONFIGURING THE KEYSTORE AND TRUSTSTORE e Load Aliases Click the Load Aliases button to populate the Alias field with the aliases conta
200. ult CC Closeable port closeQ catch Exception ex out printIn lt p gt Exception ex 19 Right click the project node and choose Run Project The server starts if it was not running already the application is built deployed and run The browser opens and displays the calculation result You have successfully created and deployed a WSIT enabled client that can access a WSIT enabled web service 3 Bootstrapping and Configuration Tiss chapter explains how to retrieve information that is used to access and consume a WSIT enabled web service and provides pointers to examples that demonstrate how to bootstrap and configure WSIT enabled clients from Web Services Description Language WSDL files The following topics are covered in this chapter e What is a Server Side Endpoint page 33 e Creating a Client from WSDL page 34 e Client From WSDL Examples page 35 Whatis a Server Side Endpoint Web services expose one or more endpoints to which messages can be sent A web service endpoint is an entity processor or resource that can be referenced and to which web services messages can be addressed Endpoint references con vey the information needed to address a web service endpoint Clients need to know this information before they can access a service Typically web services package endpoint descriptions and use a WSDL file to share these descriptions with clients Clients use the web service endpoint
201. umbers wsd1 144 ACCESSING WSIT SERVICES USING WCF CLIENTS Building the AddNumbers Client The example bundle s build bat file first generates the proxy class and configu ration file for the client then compiles the proxy class configuration file and Client cs client class into the Client exe executable file To run build bat do the following 1 Atacommand prompt navigate the location where you extracted the exam ple bundle 2 If necessary customize the build bat file as described in Customizing the build bat File below 3 Enter the following command build bat Customizing the build bat File To customize the build bat file for your environment do the following 1 Open build bat in a text editor 2 On the first line enter the full path to the svcutil exe tool By default it is installed at C Program Files Microsoft SDKs Windows v6 Q Bin 3 On the first line change the WSDL location URL if you did not deploy the addnumbers service to the local machine or if the service was deployed to a different port than the default 8080 port number For example the follow ing line sets the host name to testmachine example com and the port number to 8081 svcutil config Client exe config http testmachine example com 8081 wsit enabled fromjava addnumbers wsdl 4 On line 2 change the location of the csc exe C compiler and the Sys tem ServiceModel and System Runtime Serialization support DLLs if you installed the N
202. upon the security mechanism selected for the STS and not on the security mech anism selected for the application e SSL To use a mechanism that uses secure transport SSL you must con figure the system to point to the client and server keystore and truststore files Steps for doing this are described in Configuring SSL For Your Applications page 69 e User in Glassfish To use a mechanism that requires a user database for authentication you can add a user to the file realm of GlassFish Instruc tions for doing this can be found at Adding Users to GlassFish page 72 Summary of Client Side Configuration Requirements Table 6 2 summarizes the options that need to be configured for each of the security mechanisms on the client side Each of the columns is briefly discussed after the table SUMMARY OF CLIENT SIDE CONFIGURATION REQUIREMENTS Table 6 2 Summary of Client Side Configuration Requirements SAML Default Callback Mechanism User Handler Username Auth w Sym metric Keys Mutual Certs Transport Sec Message Auth over SSL User name Token Message Auth over SSL X 509 Token SAML Auth over SSL Endorsing Cert SAML Sender Vouches with Cert SAML Holder of Key STS Issued Token STS Issued Token with Service Cert USING WSIT SECURITY Table 6 2 Summary of Client Side Configuration Requirements Continued SAML Default Cal
203. uststore files not variables For the SSL mechanism The browser will prompt you to accept the server alias slas On the client side for the Transport Security SSL mechanism you must either use the fully qualified hostname in the URL for the service WSDL when you are creating the web sercie client or else you must follow the steps in Transport Security SSL Workaround page 63 Service Configuration To require the service to use the HTTPS protocol you have to specify the security requirements in the service s application deployment descriptor This file is ejb jar xm1 for a web service that is implemented as an EJB endpoint and web xml for a web service implemented as a servlet To specify the security information follow these steps a From your web service application expand Web Pages gt WEB INF b Double click web xm1 or ejb jar xm1 to open it in the editor c Select the Security tab d On the Security Constraints line click Add Security Constraint CONFIGURING SSL FOR YOUR APPLICATIONS 71 e Under Web Resource Collection click Add f Enter a Name for the Resource for example CalcWebResource and enter the URL Pattern to be protected for example Select which HTTP Methods to protect for example POST Click OK to close this dialog g Check the Enable User Data Constraint box Select CONFIDENTIAL for the Transport Guarantee to specify that the application uses SSL because the application re
204. valent to authenticate that identity When using a username token the user must be configured on GlassFish For information on configuring users on Glass Fish read Adding Users to GlassFish page 72 89 USING WSIT SECURITY e X 509 Certificate An X 509 certificate specifies a binding between a public key and a set of attributes that includes at least a subject name issuer name serial num ber and validity interval An X 509 certificate may be used to validate a public key that may be used to authenticate a SOAP message or to iden tify the public key with a SOAP message that has been encrypted When this option is selected you must specify a truststore For information on specifying a truststore read Configuring the Truststore on a Service page 79 e Issued Token An issued token is a token issued by a trusted Secure Token Service STS The service does not trust the client directly but instead trusts tokens issued by a designated STS In other words the STS is taking on the role of a second service with which the client has to securely authenti cate The issued tokens contain a key which is encrypted for the server and which is used for deriving new keys for signing and encrypting e SAML Token A SAML Token uses Security Assertion Markup Language SAML assertions as security tokens Configuring A Secure Token Service STS A Secure Token Service STS is a Web service that issues security tokens That is it m
205. versions of these specifications e Bootstrapping e WS MetadataExchange v1 1 e Reliable Messaging e WS ReliableMessaging v1 0 INTRODUCTION e WS ReliableMessaging Policy v1 0 e Atomic Transactions e WS AtomicTransaction v1 0 e WS Coordination v1 0 e Security e WS Security v1 1 e WS SecurityPolicy v1 1 e WS Trust v1 0 e WS SecureConversation v1 0 e Policy e WS Policy v1 2 e WS PolicyAttachment v1 2 The same versions of these specifications are also implemented in WCF in NET 3 0 Sun will update to the standard versions of these specifications in a future release of WSIT Those versions will coincide with the versions used in WCF in NET 3 5 Bootstapping and Configuration Spec if ations Bootstrapping and configuring involves a client getting a web service URL per haps via service registry and obtaining the information needed to build a web services client that is capable of accessing and consuming a web service over the Internet This information is usually obtained from a WSDL file Figure 1 2 WSIT SPECIFICATIONS 9 shows the specifications that were implemented to support bootstrapping and configuration Web Services Metadata Exchange Bootstrapping and Configuration Standards Core XML XML Standards Infoset Schema Previously implemented in JAX Web Services Figure 1 3 Bootstrapping and Configuration Specifications In addition to the Core XML specifications bootstrapping and configuration wa
206. viding basic mechanisms on top of which secure messaging semantics can be defined for multiple message exchanges This feature allows for contexts to be established so that potentially more efficient keys or new key material can be exchanged The result is that the overall performance of subsequent message exchanges is improved For more information on how to use Secure Conversation see Chapter 6 5 Using Reliable Messaging Tas chapter explains how to configure reliable messaging in web service pro viders and clients This chapter covers the following topics e Reliable Messaging Options page 43 e Creating Web Service Providers and Clients that use Reliable Messaging page 45 e Using Secure Conversation With Reliable Messaging page 45 Reliable Messaging Options Table 5 1 describes the reliable messaging configuration options Table 5 1 Endpoint Reliable Messaging Configuration Options Option Deer Reliable Messaging Specifies whether reliable messaging is enabled 43 44 USING RELIABLE MESSAGING Table 5 1 Endpoint Reliable Messaging Configuration Options Ordered Delivery Specifies whether the Reliable Messaging protocol ensures that the application messages for a given message sequence are delivered to the endpoint application in the order indicated by the message numbers This option increases the time to process application message sequences and may result in the degradation of web service
207. web service The web service endpoint specifies the security requirements to the client as assertions see Figure 1 9 Client Accesses Endpoint Web i Services Endpoint supplies WS Security Policy Assertions Figure 1 9 Security Policy Exchange The security policy model uses the policy specified in the WSDL file for associ ating policy assertions with web service communication As a result whenever possible the security policy assertions do not use parameters or attributes This enables first level QName based assertion matching to be done at the frame work level without security domain specific knowledge The first level matching provides a narrowed set of policy alternatives that are shared by the client and web service endpoint when they attempt to establish a secure communication path Note A QName is a qualified name as specified by XML Schema Part2 Datatypes specification Namespaces in XML Namespaces in XML Errata A qualified name is made up of a namespace URI a local part and a prefix How THE WSIT TECHNOLOGIES WORK 19 The benefit of representing security requirements as assertions is that QName matching is sufficient to find common security alternatives and that many aspects of security can be factored out and re used For example it may be common that the security mechanism is constant for a web service endpoint but that the mes sage parts that are protected or secured may vary by message action The
208. web service clients or Java web services and WCF web service clients e Chapter 10 describes Atomic Transactions What is WSIT Sun is working closely with Microsoft to ensure interoperability of web services enterprise technologies such as message optimization reliable messaging and security The initial release of WSIT is a product of this joint effort WSIT is an implementation of a number of open web services specifications to support enterprise features In addition to message optimization reliable messaging and security WSIT includes a bootstrapping and configuration technology Figure 1 1 shows the underlying services that were implemented for each technology XML Narres pace XML Infoset XML Scherra WS ReliableMessaging Lr ETE L o e WS Addressing d WSDL WS SecurityPolicy WS Policy j q WS Security d usude WS Sec ureConversation Figure 1 1 WSIT Web Services Features WHAT Is WSIT 3 Starting with the core XML support currently built into the Java platform WSIT uses or extends existing features and adds new support for interoperable web ser vices See the following sections for an overview of each feature e Bootstrapping and Configuration page 3 e Message Optimization Technology page 4 e Reliable Messaging Technology page 5 e Security Technology page 6 Bootstapping and Configuration Bootstrapping and configuration consists of using a URL to access a web ser
209. work address or URL For an example of using a web browser to access a service s WSDL see Verifying Deployment page 134 When developing a web service starting from an existing WSDL the process is actually simpler than starting from Java This is because the policy assertions needed to enable various WSIT technologies are already embedded in the WSDL file An example WSDL file is included in the fromwsd1 sample pro vided with this tutorial at lt INSTALL gt wsit enabled fromwsd1 etc AddNumbers wsd1 130 WSIT EXAMPLE USING A WEB CONTAINER WITHOUT NETBEANS To Create a web service from WSDL create the following source files e WSDL File page 130 e Web Service Implementation File page 131 e custom server xm e web xml e sun jaxws xm e build xml e build properties The following files are standard files required for JAX WS Examples of these files are provided in the fromwsd1 sample directory e custom server xml e sun jaxws xm e web xml The build xml and build properties files are standard in any Ant build envi ronment Examples of these files are provided in the respective samples directo ries The sample files provided in this tutorial define a web service that takes two inte gers adds them and returns the result If one of the integers is negative an exception is returned WSDL File You can create a WSDL file by hand or retrieve it from an existing web service by simply pointing a web browser at th
210. y mechanism 49 94 security policy description 6 security technology description 6 sequence identifier 5 lifetime of 5 service registries 9 34 services securing 48 session management implementing 5 shared security context 6 SOAP messages 34 SOAP with Attachments API for Java See SAAJ specifications bootstrapping and configuration 9 message optimization 10 reliable messaging 11 SOAP 10 SOAP MTOM 11 Web Services Addressing 11 Web Services Atomic Transactions 13 Web Services Coordination 12 Web Services Metadata Exchange 9 34 Web Services Policy 9 13 Web Services Reliable Messaging 12 Web Services Secure Conversation 11 14 Web Services Security 13 Web Services Security Policy 14 Web Services Trust 14 WSDL 9 SSL configuring 50 68 STS configuring 50 90 196 INDEX supporting token options 89 T Timestamp Validator field timestamps validating 84 tokens supporting options 89 trust configuring 48 51 81 95 Truststore Configuration page 79 truststores configuring 50 74 79 location 80 peer alias 81 typographical conventions ix U username default 58 validating 84 username authentication configuring client 57 Username Validator field 84 users adding to Application Server 72 73 creating 72 V validating password 84 SAML tokens 85 token timestamps 84 username 84 validators configuring 84 W WCE 6 platform 7 Web services 7 Web service creating 25 creating and deploying 24 38 128
211. y tested the deployed a WSIT enabled web service Notice that the WSDL file includes the following WSIT tags lt wsp UsingPolicy gt lt wsp Policy wsu Id CalculatorwWSPortBindingPolicy gt lt wsp Exact1yOne gt lt wsp Al1 gt lt ns1 RMAssertion gt lt ns2 UsingAddressing gt lt wsp Al1 gt lt wsp Exact1lyOne gt lt wsp Policy gt You have now successfully tested the deployment of a WSIT enabled web ser vice CREATING A CLIENT TO CONSUME A WSIT ENABLED WEB SERVICE 29 Creating a Clientto Consume a WSIF Enabled Web Service Now that you have built and tested a web service that uses WSIT technologies you can create a client that accesses and consumes that web service The client will use the web service s WSDL to create the functionality necessary to satisfy the interoperability requirements of the web service To create a client to access and consume the web service perform the following steps 1 Choose File New Project select Web Application from the Web category and click Next 2 Name the project for example CalculatorWSServletClient and click Fin ish 3 Right click the CalculatorWSServletClient node and select New Web Service Client The New Web Service Client window appears Note NetBeans submenus are dynamic so the Web Service Client option may not appear If you do not see the Web Service Client option select New File Folder Webservices Web Service Client 4 Select t
212. you can change the following configuration options e Issuer Specify an identifier for the issuer for the issued token This value can be any string that uniquely identifies the STS for example MySTS e Contract Implementation Class Specify the actual implementation class for the WSTrustContract interface that will handle token issu ance validation etc Default value is com sun xml ws trust impl IssueSam TokenContractImp1 for issuing SAML assertions or click Browse to browse to another contract implementation class CREATING A THIRD PARTY STS Life Time of Issued Tokens The life span of the token issued by the STS Default value is 300 000 ms Encrypt Issued Key Select this option if the issued key should be encrypted using the service certificate Default is true Encrypt Issued Token Select this option if the issued token should be encrypted using the service certificate Default is false 17 Optionally to add one or more Service Providers that have a trust relation ship with the STS click the Add button and specify the following config uration options Provider Endpoint URI The endpoint URI of the service provider Certificate Alias The alias of the certificate of the service provider in the keystore Token Type tThe type of token the service provider requires for example urn oasis names tc SAML1 assertion Key Type the type of key the service provider requires The choices are public key or symmet
213. your page here Delete the end comment line that ends the section of commented out code Add some empty lines after the following line out println lt h1 gt Servlet ClientServlet at request getContextPath lt h1 gt Right click in one of the empty lines that you added Choose Web Service Client Resources gt Call Web Service Operation The Select Operation to Invoke dialog box appears Browse to the Add operation and click OK The processRequest method is as follows with bold indicating code added by the IDE protected void processRequest HttpServletRequest request HttpServletResponse response throws ServletException IOException response setContentTypeC text html charset UTF 8 PrintWriter out response getWriter out printinC lt html gt out printIn lt head gt out printInC lt title gt Servlet ClientServlet lt title gt out printin lt head gt out printinC lt body gt out printinC lt hli gt Servlet ClientServlet at request getContextPath O lt hl gt try Call Web Service Operation org me calculator client CalculatorWS port service getCalculatorWSPort TODO initialize WS operation arguments here int i 0 int j 0 CREATING A CLIENT TO CONSUME A WSIT ENABLED WEB SERVICE 31 TODO process result here int result port add i j out printinC Result result catch Exception ex TODO handle custom exceptions here out prin

Web Service

Contents

Download Pdf Manuals

Related Search

Related Contents