The WSIT Tutorial For Web Services Interoperability Technologies Version 1.0 FCS September 18, 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 supplements 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, samples) 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 prohibited 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, ÉtatsUnis 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 dispositions 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 États-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 (articles 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 exportations 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 États-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 dun ordre de ne pas partic- iper, dune 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’ÉTAT" 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 Contents About This Tutorial ix Who Should Use This Tutorial How to Use This Tutorial About the Examples Typographical Conventions Feedback ix x x xi xi Chapter 1: Introduction What is WSIT? Bootstrapping and Configuration Message Optimization Technology Reliable Messaging Technology Security Technology How WSIT Relates to Windows Communication Foundation (WCF) WSIT Specifications Bootstrapping and Configuration Specifications 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 Chapter 2: WSIT Example Using a Web Container and NetBeans23 Registering GlassFish with the IDE Creating a Web Service 23 24 iii iv CONTENTS Configuring WSIT Features in the Web Service Deploying and Testing a Web Service Creating a Client to Consume a WSIT-Enabled Web Service 26 28 29 Chapter 3: Bootstrapping and Configuration 33 What is a Server-Side Endpoint? Creating a Client from WSDL Client From WSDL Examples 33 34 35 Chapter 4: Message Optimization 37 Creating a Web Service Configuring Message Optimization in a Web Service Deploying and Testing a Web Service Creating a Client to Consume a WSIT-enabled Web Service Message Optimization and Secure Conversation 38 38 39 39 42 Chapter 5: Using Reliable Messaging 43 Reliable Messaging Options 43 Creating Web Service Providers and Clients that use Reliable Messaging 45 Using Secure Conversation With Reliable Messaging 45 Chapter 6: Using WSIT Security 47 Configuring Security Using NetBeans IDE Securing the Service Securing the Client Summary of Configuration Requirements Summary of Service-Side Configuration Requirements Summary of Client-Side Configuration Requirements Security Mechanisms Username Authentication with Symmetric Keys Mutual Certificates Security Transport Security (SSL) Message Authentication over SSL SAML Authorization over SSL Endorsing Certificate SAML Sender Vouches with Certificates SAML Holder of Key 48 48 51 52 53 55 62 62 63 63 65 65 66 66 67 v CONTENTS STS Issued Token 67 STS Issued Token with Service Certificate 68 STS Issued Endorsing Token 68 Configuring SSL and Authorized Users 69 Configuring SSL For Your Applications 70 Adding Users to GlassFish 73 Configuring Keystores and Truststores 75 Updating GlassFish Certificates 75 Specifying Aliases with the Updated Stores 77 Configuring the Keystore and Truststore 78 Configuring Validators 85 Securing an Operation 86 Specifying Security at the Operation, Input Message, or Output Message Level 87 Supporting Token Options 90 Configuring A Secure Token Service (STS) 91 Creating a Third-Party STS 92 Specifying an STS on the Service Side 95 Specifying an STS on the Client Side 95 Example Applications 98 Example: Username Authentication with Symmetric Keys (UA) 98 Example: Mutual Certificates Security (MCS) 101 Example: Transport Security (SSL) 104 Example: SAML Authorization over SSL (SA) 107 Example: SAML Sender Vouches with Certificates (SV) 112 Example: STS Issued Token (STS) 116 Example: Other STS Examples 122 Further Information 122 Chapter 7: Further Detail on WSIT Security Features 123 Issues Addressed Using Security Mechanisms Understanding WSIT Configuration Files Service-Side WSIT Configuration Files Client-Side WSIT Configuration Files Security Mechanism Configuration Options 123 125 125 130 133 Chapter 8: WSIT Example Using a Web Container Without NetBeans139 Environment Configuration Settings 140 vi CONTENTS Setting the Web Container Listener Port Setting the Web Container Home Directory WSIT Configuration and WS-Policy Assertions Creating a Web Service Creating a Web Service From Java Creating a Web Service From WSDL Building and Deploying the Web Service Building and Deploying a Web Service Created From Java Building and Deploying a Web Service Created From WSDL Deploying the Web Service to a Web Container Verifying Deployment Creating a Web Service Client Creating a Client from Java Creating a Client from WSDL Building and Deploying a Client Running a Web Service Client Undeploying a Web Service 140 141 141 142 142 145 147 148 149 149 150 151 152 154 155 155 155 Chapter 9: Accessing WSIT Services Using WCF Clients 157 Creating a WCF Client Prerequisites to Creating the WCF Client The Client Class Building and Running the Client 157 158 158 159 Chapter 10: Data Contracts 163 Web Service - Start from Java DataTypes Fields/Properties Class Open Content Enum Type Package Web Service - Start from WSDL Java Client Customizations for WCF Service WSDL generateElementProperty Developing a Microsoft NET Client BP 1.1 Conformance BP 1.1 R2211 163 164 180 185 188 190 191 192 192 193 193 197 198 198 vii CONTENTS Chapter 11: Using Atomic Transactions 199 About the basicWSTX Example Building, Deploying and Running the basicWSTX Example 199 203 Index 209 viii CONTENTS About This Tutorial THIS 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, WSSecureConversation, 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 Tutorial 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 ix x ABOUT THIS TUTORIAL How to Use This Tutorial This tutorial addresses the following technology areas: • • • • • • • • Bootstrapping and Configuration Message Optimization Reliable Messaging (WS-RM) Web Services Security 1.1 (WS-Security) Web Services Trust (WS-Trust) Web Services Secure Conversation (WS-Secure Conversation) Data Contracts 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: • The latest Java SE 5.0 (Update 12) or JDK 6.0 (Update 2) with which the WSIT version 1.0 FCS software has been extensively tested • GlassFish version Build 58g, 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 • WSIT distribution (version 1.0 FCS) • Netbeans IDE 5.5.1 FCS • WSIT plug-in modules, Version 2.41, for Netbeans IDE 5.5.1 See the WSIT Installation Instructions, located at https://wsitfor instructions about downloading and installing all the required software docs.dev.java.net/releases/1-0-FCS/install.html , ... https:/ /wsit. dev.java.net/source/browse/*check- out* /wsit/ wsit/ docs/howto /wsit- enabled-fromwsdl.zip • https:/ /wsit. dev.java.net/source/browse/*check- out* /wsit/ wsit/docs/ howto/csclient-enabled-fromjava.zip • https:/ /wsit- docs.dev.java.net/releases/ 1-0 -FCS/wsittuto-... v1.0 • Atomic Transactions • WS-AtomicTransaction v1.0 • WS-Coordination v1.0 • Security • WS-Security v1.1 • WS-SecurityPolicy v1.1 • WS-Trust v1.0 • WS-SecureConversation v1.0 • Policy • WS-Policy... TUTORIAL Introduction This tutorial describes how to use the Web Services Interoperability Technolo- gies (WSIT) —a product of Sun Microsystems web services interoperability effort to develop Java clients