Advanced Web Service Interoperability

Advanced Web Service Interoperability, also referred to as Web Service "Quality of Service", encompasses components that enable interoperability between Java web services and .Net web services.

Contents

Content on this page applies to NetBeans IDE 6.9-7.1

To follow this tutorial, you need the following software and resources.

Software or Resource Version Required
NetBeans IDE Java EE download bundle
Java Development Kit (JDK) version 6 or version 7
Java EE-compliant web or application server GlassFish Server Open Source Edition 3.1.x, or Oracle WebLogic Server 11g or 12c

The GlassFish server can be installed, optionally, with the Java EE distribution of NetBeans IDE. Alternatively, you can visit the the GlassFish server downloads page or the Apache Tomcat downloads page.

Important: Java EE 6 projects require GlassFish Server 3.1.x, or Oracle WebLogic Server 12c.

Introduction

Components relating to advanced web services interoperability fall into four main categories:

"Quality of service" is configured in the Web Service Attributes Editor, which is accessed in the Projects window, from the node representing the web service or client. In this tutorial, you are introduced to two web service samples that are distributed with the IDE. The first is unsecured, the second is secured. The differences between the two are discussed and you are shown how to configure security for your own web services and clients.

For a full and complete guide to topics relating to 'Quality of Service', see The WSIT Tutorial.

Getting to Know the Calculator Sample

The goal of this exercise is to get to know the Calculator sample that is bundled with the IDE. In contrast to the next sample, this sample is not secured, as you will see when you examine the web service.

Exploring the Sample

First you get the sample from the New Project wizard, then you examine and deploy it.

  1. Choose File > New Project (Ctrl-Shift-N on Linux and Windows, ⌘-Shift-N on MacOS). In the Samples category, select the Web Services node and then the Calculator sample, as shown below:
    New Project wizard showing calculator sample
  2. Click Next. Leave all the defaults unchanged and click Finish. Two projects are created, as shown below. The first, named CalculatorApp, provides a web service named CalculatorWS that exposes an operation named 'add'. The second, named CalculatorClientApp, provides a client, named CalculatorWSService, that invokes the web service's 'add' operation.

    An error icon is shown for the CalculatorClientApp service because the IDE cannot find the WSDL for the CalculatorWS service. After you deploy CalculatorApp, clean and build CalculatorClientApp and this problem is resolved.


    Projects window displaying the web service and the client
  3. Double-click the CalculatorWS web service, so that it opens in the Visual Designer, which is one of several tools that the IDE provides for web service development:
    CalculatorWS service in Design GUI (Visual Designer) tab

    Note: In the Visual Designer's Quality of Service section above, no options are enabled. As a result, the Quality of Service components have not been applied to this particular web service. In the next part, you will look at a web service that does have a Quality of Service component enabled.

For a full tutorial on web services in the IDE, see Getting Started with JAX-WS Web Services.

Deploying and Testing the Calculator Sample

  1. Right-click the CalculatorApp project and choose Run.

    The server starts, if it was not running already. Then the web service is deployed. The browser starts up and you see the following:
    CalculatorWS information window in browser

  2. Click on the WSDL link in the browser and now you should see the WSDL file that defines the web service:

    Note: If the WSDL does not display, check the URL in the browser's location bar. It should point to http://localhost:your_port_number/CalculatorApp/CalculatorWSService?WSDL.


    Calculator WS WSDL in browser
  3. You can use the IDE to test the web service. The IDE then automatically provides a client for your web service, without you even needing to create one. As shown below, right-click the CalculatorWS node within the Web Services node and choose Test Web Service:
    Calculator WS node context menu showing Test Web Service option
  4. The test application appears, where you can enter values for each of the fields defined in the web service, as shown below. When you click the button, which is labeled after the name of the operation, you will see the result of invoking the operation.
    Calculator WS Tester in browser
  5. Examine the CalculatorClientApp project in the Projects window. If there are error icons for ClientServlet.java, right-click the project node and select Clean and Build. The errors appeared because the CalculatorWS service had not been deployed. Now that it is deployed, the IDE can parse its WSDL and the ClientServlet compiles.
  6. Right-click the CalculatorClientApp project node and select Run. The client is a servlet, which provides this user interface in the browser:
    Calculator Service client in browser
  7. Click Get Result, and then the result is retrieved from the web service and displayed in the client:
    Calculator Service client in browser showing results

Although you now have a functioning web service, with a client that correctly retrieves results, you have not made use of the Quality of Service components at all. In the next section, you will see how to do so.

Getting to Know the Secured Calculator Sample

The goal of this exercise is to examine how a secured web service is set up, and how a client interacts with it.

Exploring the Sample

First you get the sample from the New Project wizard and then you examine how its quality of service is configured.

  1. Choose File > New Project (Ctrl-Shift-N on Linux and Windows, ⌘-Shift-N on MacOS). In the Samples category, select the Web Services node. Select the second sample, named Secure Calculator, and click Next.
    New Project wizard showing the Secure Calculator sample
  2. Click Finish. Two projects are created and are displayed in the Projects window, as shown below. The first, named SecureCalculatorApp, provides a web service named CalculatorWS that exposes an operation named 'add'. The second, named SecureCalculatorClientApp, provides a client, named CalculatorWSService, that invokes the web service's 'add' operation:

    An error icon is shown for the SecureCalculatorClientApp service because the IDE cannot find the WSDL for the SecureCalculatorWS service. After you deploy SecureCalculatorApp, clean and build SecureCalculatorClientApp and this problem is resolved.


    Projects window displaying secure client web service references
  3. In the Web Services node, double-click the CalculatorWS web service so that it opens in the Visual Designer, as shown below. In the Quality of Service section, notice that the Secure Service option has been selected, while the other two options are unselected.

    Warning for NetBeans 7.0.x users: Due to a bug, the Secure Calculator Sample is not actually secure. Select the Secure Service option yourself and select the security mechanism described below.

    Calculator WS service in design GUI tab

    The Quality of Service section in the Visual Designer specifies which of the quality of service components is enabled for the current web service.

  4. Click Advanced. The Web Service Attributes Editor opens. Notice that the Secure Service section is selected, as shown below:
    Quality of Service page in WS Attributes Editor

    In the Secure Service section, you can see that the following have been selected:

    • Version Compatibility. .NET 3.0/Metro 1.0 or .NET 3.5/Metro 1.3. Select the latest version that matches the version of Metro or .NET you have installed.

      To enable the version compatibility drop down list, add the latest version of Metro to your project's classpath. To add the latest Metro library, right-click the project's node in the Projects window, open the project's Properties, go to the Libraries category, and browse for and add the latest Metro library.

    • Security Mechanism. Specifies the approach used for securing the web service. Here, Username Authentication with Symmetric Keys is selected. 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 are 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. The other security mechanisms are explained later in this tutorial.

    • Use Development Defaults. Select this option to import certificates into the GlassFish server keystore and truststore, so that they can be used immediately for development. Because the default certificates are not in an appropriate format to be used in this context, this import is done for you, so that you do not need to do this manually yourself. In addition to importing certificats, a default user is created in the "file" realm, with username "wsitUser". In a production environment, you will probably want to provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
  5. Expand the Input Message and Output Message sections. In each, the Message Parts button is now enabled, because of the security mechanism that is selected in the previous screenshot:
    Quality of Service page with Message Parts button enabled

    Note: If you choose certain other security mechanisms, as discussed below, you will be able to select the Authentication Token drop-down and the two checkboxes shown in the Input Message section above. The Security Mechanism drop-down shows the following security mechanisms:

    Security Mechanism drop-down

    Instead of the Username Authentication with Symmetric Keys mechanism, which was discussed earlier, the following security mechanisms can be chosen:

    • Mutual Certificates Security. 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.
    • Transport Security (SSL). The Transport Security mechanism protects your application during transport using SSL for authentication and confidentiality. Transport-layer security is provided 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, message integrity, and confidentiality. When running 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 consumer 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 the GlassFish server, and the default certificates are sufficient for running this mechanism, and are required when using Atomic Transactions. However, the message security mechanisms require a newer version of certificates than is available with the GlassFish server. You can download valid keystore and truststore files for the client and server as described in Updating the GlassFish server Certificates.

    • 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 confidentiality protection.
    • SAML Authorization over SSL. The SAML Authorization over SSL mechanism attaches an authorization token with the message and uses SSL for confidentiality protection. In this 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.
    • 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 manager should be used to endorse (or counter sign) the original request.
    • SAML Sender Vouches with Certificates. This mechanism protects messages with mutual certificates for integrity and confidentiality and with a Sender Vouches SAML token for authorization. The Sender Vouches method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message. The attesting entity provides the confirmation evidence that will be used to establish the correspondence between the subject of the SAML subject statements (in SAML assertions) 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 message content against modification by another party.

      For this mechanism, the SAML token is included as part of the message signature as an authorization token and is sent only to the recipient. The message payload 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.

    • SAML Holder of Key. This mechanism protects messages with a 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 confirmation method of the subject statements of the SAML assertion referenced for key info for the signature.

      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 client 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 assertion.

  6. Click the Message Parts button, in either the Input Message section or the Output Message section, and notice that you can set security options for a variety of parts of a web service, as shown below:
    Message Parts dialog

    Click in a checkbox to the right of the message part or element that you would like to sign, encrypt or require.

    • Select Sign to specify the parts or elements of a message that require integrity protection (digital signature).
    • Select Encrypt to specify the parts or elements of a message that require confidentiality (encryption).
    • Select Require to specify the set of parts and/or elements that a message must contain.
  7. Now you will look at how the web service client's quality of service is configured. In the SecureCalculatorClientApp, expand the Web Service References node, right-click the CalculatorWSService node, and choose Edit Web Service Attributes. You should now see the following:
    Web service client quality of service dialog

    The "Use Development Defaults" option results in the IDE importing certificates into the GlassFish server keystore and truststore, so that they can be used immediately for development. Because the default certificates are not in an appropriate format to be used in this context, this import is done for you, so that you do not need to do this manually yourself. In addition to importing certificats, a default user is created in the "file" realm, with username "wsitUser". In a production environment, you will probably want to provide your own certificates and user settings, however, in a development environment you may find these defaults useful.

Deploying and Testing the Secured Calculator Sample

  1. Right-click the web service project node and choose Run. As in the previous section, the web service is deployed.
  2. Right-click the web service client project node and choose Run. You should now see the following:
    Secure web service client in browser
  3. Type two numbers, click Get Result, and then you should see the following, indicating that the client has been successfully authenticated:
    Secure web service client in browser showing results

If you get an error message that authentication failed due to an invalid user/password pair, there is either a problem with the default user created by the IDE or there are mismatched credentials set on the client. In this case, you need to create the user/password pair manually. For instructions, please see the WSIT documentation on client security.

Send Feedback on This Tutorial

See Also

For more information about using NetBeans IDE to develop Web Services, see the following resources:

To send comments and suggestions, get support, and keep informed about the latest developments on the NetBeans IDE Java EE development features, join the nbj2ee@netbeans.org mailing list.