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, which contains the latest security configuration information.

Example: Username Authentication with Symmetric Keys (UA)

The section includes the following topics:

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 adding security to both the web service and to the web service client.

For this example, the security mechanism of Username Authentication with Symmetric Keys 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:
    1. Update the GlassFish keystore and truststore files as described in Updating GlassFish Certificates.
    2. Create a user on GlassFish as described in Adding Users to GlassFish.
  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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)
  3. Expand CalculatorApplicationRight ArrowWeb 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.
  5. In the CalculatorWSPortBinding section, select Secure Service.
  6. From the drop-down list for Security Mechanism, select Username Authentication with Symmetric Keys.
  7. Click the Keystore button to provide your keystore with the alias identifying the service certificate. To do this, click the Load Aliases button and select xws-security-server. Click OK to close.
  8. Click OK to close the WSIT Configuration dialog.

    9. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore element.

    An example of this file can be viewed in the tutorial by clicking this link: Service-Side WSIT Configuration Files.

  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 following elements: SymmetricBinding and UsernameToken.
  11. 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 references the web service created in the previous section. This web service is secured using the security mechanism described in Username Authentication with Symmetric Keys. 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 following steps:

  1. Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.

    2. 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 Client.

  2. Expand the node for the web service client application, CalculatorWSServletClient.
  3. Expand the node for Web Service References.
  4. Right-click on CalculatorWSService, select Edit Web Service Attributes.
  5. Select the WSIT Configuration tab of the CalculatorWSService dialog.
  6. For this testing environment, provide a default username and password. To do this,
    1. Expand the Username Authentication node.
    2. 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, the user name is wsitUser and the password is changeit.

      3. NOTE: In a production environment, you should configure a Username Handler and a Password Handler class to eliminate the security risk associated with the default username and password options.

  7. Provide the server's certificate by pointing to an alias in the client truststore. To do this, select the Certificates node, click the Load Aliases button for the Truststore, and select xws-security-server from the Truststore Alias list.
  8. Click OK to close this dialog.
  9. In the tree, drill down from the project to Source PackagesRight ArrowMETA-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present:

    10. <wsp:All>
      <wsaws:UsingAddressing xmlns:wsaws=
        "http://www.w3.org/2006/05/addressing/wsdl"/>
      <sc:CallbackHandlerConfiguration
          wspp:visibility="private">
        <sc:CallbackHandler default="wsitUser"
          name="usernameHandler"/>
        <sc:CallbackHandler default="changeit"
          name="passwordHandler"/>
      </sc:CallbackHandlerConfiguration>
      <sc:TrustStore wspp:visibility="private" location=
        "home\glassfish\domains\domain1\config\cacerts.jks"
        storepass="changeit" peeralias="xws-security-server"/>
    </wsp:All>

    An example of this file can be viewed in the tutorial by clicking this link: Client-Side WSIT Configuration Files.

  10. Right-click on the CalculatorWSServletClient node and select Run Project.

Example: Mutual Certificates Security (MCS)

The section includes the following topics:

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 adding security to both the web service and to the web service client.

For this example, the security mechanism of Mutual Certificates Security 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:
    1. Update the GlassFish keystore and truststore files as described in Updating GlassFish Certificates.
  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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)
  3. Expand CalculatorApplicationRight ArrowWeb 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.
  5. Select Secure Service.
  6. From the drop-down list for Security Mechanism, select Mutual Certificates 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.

    9. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore 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.
  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 references the web service created in the previous section. This web service is secured using the security mechanism described in Mutual Certificates Security.

To add security to the client that references this web service, complete the following steps:

  1. Create the client application following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.

    2. 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 Client.

  2. Expand the node for the web service client, CalculatorWSServletClient.
  3. Expand the node for Web Service References.
  4. Right-click on CalculatorWSService, select Edit Web Service Attributes.
  5. Select the WSIT Configuration tab of the CalculatorWSService dialog.
  6. Provide the client's private key by pointing to an alias in the keystore. To do this,
    1. Expand the Certificates node.
    2. Click the Load Aliases button for the keystore.
    3. Select xws-security-client from the Alias list.
  7. Provide the server's certificate by pointing to an alias in the client truststore. To do this, from the Certificates node,
    1. Click the Load Aliases button for the truststore.
    2. Select xws-security-server from the Alias list.
    3. Click OK to close this dialog.
  8. In the tree, drill down from the project to Source PackagesRight ArrowMETA-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present:

    9. <wsp:All>
      <wsaws:UsingAddressing xmlns:wsaws=
        "http://www.w3.org/2006/05/addressing/wsdl"/>
      <sc:KeyStore wspp:visibility="private" location=
        "C:\Sun\glassfish\domains\domain1\config\keystore.jks"
        storepass="changeit" alias="xws-security-server"
        keypass="changeit"/>
      <sc:TrustStore wspp:visibility="private" location=
        "C:\Sun\glassfish\domains\domain1\config\cacerts.jks"
        storepass="changeit"
        peeralias="xws-security-server"/>
    </wsp:All>

  9. Compile and run this application by right-clicking on the CalculatorWSServletClient node and selecting Run Project.

Example: Transport Security (SSL)

This section includes the following topics:

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 adding transport security to both the web service and to the web service client.

For this example, the security mechanism of Transport Security (SSL) is used to secure the application. To add security to the service part of the example, 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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)
  2. Expand CalculatorApplicationRight ArrowWeb 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 Security (SSL).
  6. Click OK to close the WSIT Configuration dialog.

    7. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml.

    NOTE: For Transport Security, the keystore and truststore files are configured 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.

  7. 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:
    1. From your web service application expand Web PagesRight ArrowWEB-INF.
    2. Double-click web.xml to open it in the editor.
    3. Select the Security tab.
    4. On the Security Constraints line, click Add Security Constraint.
    5. Under Web Resource Collection, click Add.
    6. Enter a Name for the Resource, CalcWebResource. Enter the URL Pattern to be protected, /*. Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
    7. Check the Enable User Data Constraint box. Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL.
    8. Click the XML tab to view the resulting deployment descriptor additions.
  8. Right-click the CalculatorApplication node and select Run Project. If the server presents its certificate, s1as, accept this certificate. A browser will open and display the WSDL file for the application.
  9. Follow the steps to secure the client application as described in the next section.

Securing the Example Web Service Client Application (SSL)

This section demonstrates adding security to the web service client that references the web service created in the previous section. This web service is secured using the security mechanism described in Transport Security (SSL).

To add security to the client that references this web service, 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, 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 Service, with the following exception:
    1. 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://<fully-qualified-hostname>:8181/CalculatorApplication/CalculatorWSService?wsdl (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 (s1as) 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://<fully-qualified-hostname>:8181/CalculatorApplication/CalculatorWSService?wsdl couldn't be downloaded. However, 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 reference 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 Transport Security (SSL) Workaround.
    2. Continue creating the client following the remainder of the instructions in Creating a Client to Consume a WSIT-Enabled Web Service.

      3. 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 Client.

  2. Compile and run this application by right-clicking on the CalculatorWSServletClient node and selecting Run Project.

Example: SAML Authorization over SSL (SA)

The section includes the following topics:

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 adding security to both the web service and to the web service client.

For this example, the security mechanism of SAML Authorization over SSL is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), 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:
    1. Update the GlassFish keystore and truststore files as described in Updating GlassFish Certificates.
    2. Create a user on GlassFish as described in Adding Users to GlassFish.
  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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)
  3. Expand CalculatorApplicationRight ArrowWeb 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 Authorization over SSL.
  7. Click the Keystore button to provide your keystore with the alias identifying 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.

    10. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore and sc:Truststore elements.

  10. To require the service to use SSL, 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:
    1. From your web service application expand Web PagesRight ArrowWEB-INF.
    2. Double-click web.xml to open it in the editor.
    3. Select the Security tab.
    4. On the Security Constraints line, click Add Security Constraint.
    5. Under Web Resource Collection, click Add.
    6. Enter a Name for the Resource, CalcWebResource. Enter the URL Pattern to be protected, /*. Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
    7. Check the Enable User Data Constraint box. Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL.
    8. Click the XML tab to view the resulting deployment descriptor additions.
  11. Right-click the CalculatorApplication node and select Run Project. Accept the s1as 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 SignedSupportingTokens element, which in turn contains a SamlToken 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 references the web service created in the previous section. This web service is secured using the security mechanism described in SAML Authorization over SSL.

To add security to the client that references this web service, complete the following 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 Creating a Client to Consume a WSIT-Enabled Web Service, with the following exceptions:
    1. 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://<fully-qualified-hostname>:8181/CalculatorApplication/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 (s1as) 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://<fully-qualified-hostname>:8181/CalculatorApplication/CalculatorWSService?wsdl couldn't be downloaded. However, 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 reference 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 Transport Security (SSL) Workaround.
    2. 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, 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,
    1. If the index.jsp file is not open in the right pane, double-click it to open it.
    2. Drill down through the Web Service References node until you get to the add operation.
    3. Drag the add operation to the line immediately following the following line:
      <h1>JSP Page</h1>
    4. 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 SAMLCallbackHandler is shown below:
    1. Right-click on the CalculatorClient node.
    2. Select NewRight ArrowJava Package.
    3. For Package Name, enter xwss.saml.
    4. Click Finish.
    5. Drill down from CalculatorClientRight ArrowSource PackagesRight Arrowxwss.saml.
    6. Right-click on xwss.saml. Select NewRight ArrowFile/Folder.
    7. From the Categories list, select Java Classes.
    8. From the File Types list, select Empty Java File.
    9. Click Next.
    10. For Class Name, enter SamlCallbackHandler.
    11. Click Finish.
    12. The empty file displays in the IDE.
    13. Download the example file SamlCallbackHandler.java from the following URL:
      https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
    14. Open the file in a text editor.
    15. Modify the home variable to provide the hard-coded path to your GlassFish installation. For example, modify the line:

      16.     String home = System.getProperty("WSIT_HOME");

      to

          String home = "/home/glassfish";

    16. Copy the contents of this file into the SamlCallbackHandler.java window that is displaying in the IDE.
  4. Drill down from CalculatorClientRight ArrowWeb Service References.
  5. Right-click on CalculatorWSService, select Edit Web Service Attributes.
  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. NOTE: If you are using a certificate other than the updated GlassFish certificates described in Updating GlassFish Certificates, or are otherwise using a different alias for the client's private key alias, correct 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, edit the following code in the SAMLCallbackHandler.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 + "domain1" + fileSeparator + "config" +
    fileSeparator + "cacerts.jks";
    this.trustStoreType = "JKS";
    this.trustStorePassword = "changeit";

  8. Provide the server's certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button for the Truststore and select xws-security-server.
  9. Expand the Username Authentication node. In the SAML Callback Handler field, enter the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler.
  10. Click OK to close this dialog.
  11. In the tree, drill down from the project to Source PackagesRight ArrowMETA-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present, where xwss.saml.SamlCallbackHandler is the SAML Callback Handler class for the client:

    12. <wsp:All>
      <wsaws:UsingAddressing xmlns:wsaws=
        "http://www.w3.org/2006/05/addressing/wsdl"/>
      <sc:CallbackHandlerConfiguration
        wspp:visibility="private">
        <sc:CallbackHandler name="samlHandler"
          classname="xwss.saml.SamlCallbackHandler"/>
      </sc:CallbackHandlerConfiguration>
      <sc:KeyStore wspp:visibility="private" location=
        "<GF_HOME>\domains\domain1\config\keystore.jks"
        storepass="changeit" alias="xws-security-client"
        keypass="changeit"/>
      <sc:TrustStore wspp:visibility="private" location=
        "<GF_HOME>\domains\domain1\config\cacerts.jks"
        storepass="changeit"
        peeralias="xws-security-server"/>
    </wsp:All>

  12. Compile and run this application by right-clicking the CalculatorClient node and selecting Run Project.

Example: SAML Sender Vouches with Certificates (SV)

The topics covered in this section include the following:

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 adding security to both the web service and to the web service client.

For this example, the security mechanism of SAML Sender Vouches with Certificates is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), 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:
    1. Update the GlassFish keystore and truststore files as described in Updating GlassFish Certificates.
    2. Create a user on GlassFish as described in Adding Users to GlassFish.
  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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)
  3. Expand CalculatorApplicationRight ArrowWeb 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 Sender Vouches with Certificates.
  7. Click the Keystore button to provide your keystore with the alias identifying 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.

    10. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore and sc:Truststore elements.

  10. Right-click the CalculatorApplication node and select Run Project. Accept the s1as 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 SignedSupportingTokens element, which in turn contains a SamlToken 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 references the web service created in the previous section. This web service is secured using the security mechanism described in SAML Sender Vouches with Certificates.

To add security to the client that references this web service, complete the following steps:

  1. For this example, we are using a non-JSR-109-compliant 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 Service, 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, 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,
    1. If the index.jsp file is not open in the right pane, double-click it to open it.
    2. Drill down through the Web Service References node until you get to the add operation.
    3. Drag the add operation to the line immediately following the following line:

      4.   <h1>JSP Page</h1>

    4. 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 SAMLCallbackHandler is shown below:
    1. Right-click on the CalculatorClient node.
    2. Select NewRight ArrowJava Package.
    3. For Package Name, enter xwss.saml.
    4. Click Finish.
    5. Drill down from CalculatorClientRight ArrowSource PackagesRight Arrowxwss.saml.
    6. Right-click on xwss.saml. Select NewRight ArrowFile/Folder.
    7. From the Categories list, select Java Classes.
    8. From the File Types list, select Empty Java File.
    9. Click Next.
    10. For Class Name, enter SamlCallbackHandler.
    11. Click Finish.
    12. The empty file displays in the IDE.
    13. Download the example file SamlCallbackHandler.java from the following URL:
      https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
    14. Open the file in a text editor.
    15. Modify the home variable to provide the hard-coded path to your GlassFish installation. For example, modify the line:

      16.     String home = System.getProperty("WSIT_HOME");

      to

          String home = "/home/glassfish";

    16. Set the subject confirmation method to SV (Sender Vouches). For more information on this topic, read Example SAML Callback Handlers.
    17. Copy the contents of this file into the SamlCallbackHandler.java window that is displaying in the IDE.
  4. Drill down from CalculatorClientRight ArrowWeb Service References.
  5. Right-click on CalculatorWSService, select Edit Web Service Attributes.
  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 truststore. To do this, from the Certificates node, click the Load Aliases button for the Truststore and select xws-security-server.
  9. Expand the Username Authentication node. In the SAML Callback Handler field, enter the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler.
  10. Click OK to close this dialog.
  11. In the tree, drill down from the project to Source PackagesRight ArrowMETA-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present, where xwss.saml.SamlCallbackHandler is the SAML Callback Handler class for the client:

    12. <wsp:All>
      <wsaws:UsingAddressing xmlns:wsaws=
        "http://www.w3.org/2006/05/addressing/wsdl"/>
      <sc:CallbackHandlerConfiguration
        wspp:visibility="private">
        <sc:CallbackHandler name="samlHandler"
          classname="xwss.saml.SamlCallbackHandler"/>
      </sc:CallbackHandlerConfiguration>
      <sc:KeyStore wspp:visibility="private" location=
        "<GF_HOME>\domains\domain1\config\keystore.jks"
        storepass="changeit" alias="xws-security-client"
        keypass="changeit"/>
      <sc:TrustStore wspp:visibility="private" location=
        "<GF_HOME>\domains\domain1\config\cacerts.jks"
        storepass="changeit"
        peeralias="xws-security-server"/>
    </wsp:All>

  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:

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 adding security to both the web service and to the web service client.

For this example, the security mechanism of STS Issued Token is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), with the addition of creating and securing an STS.

To add security to the service part of the example, follow these steps:

  1. Create a user on GlassFish if you haven't already done so. (see Adding Users to GlassFish).
  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.
    1. Creating a Web Service
    2. Skip the section on adding Reliable Messaging.
    3. Deploying and Testing a Web Service (first two steps only, do not run the project yet).
  3. Expand CalculatorApplicationRight ArrowWeb 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 STS Issued Token.
  7. Select the Configure button. For Algorithm Suite, select Basic128 bit. For Key Size, select 128. Select OK to close the configuration dialog (the algorithm suite value of the service must match the algorithm suite value of the STS.)

    8. NOTE: If you have configured Unlimited Strength Encryption as described in Creating a Third-Party STS, you can leave the key size at 256. Otherwise, you must set it to 128.

  8. Click OK to exit the WSIT Configuration editor.

    9. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml.

  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 FileRight ArrowNew Project.
  2. Select Web, then Web Application, then Next.
  3. Enter MySTSProject for the Project Name. Click Finish.
  4. Right-click the MySTSProject node, select New, then click File/Folder at the top.
  5. Select Web Services from the Categories list.
  6. Select Secure Token Service (STS) from the File Type(s) list.
  7. Click Next.
  8. Enter the name MySTS for the Web Service Class Name.
  9. Select org.me.my.sts from the Package list.
  10. Click Finish.

    11. 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 displays in the right pane.

  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:
    1. Add these import statements to the list of imports:

      2.   import com.sun.xml.ws.security.trust.sts.BaseSTSImpl;
        import javax.annotation.Resource;
        import javax.xml.ws.Provider;
        import javax.xml.ws.Service;
        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;

    2. Add the following Resource annotation after the line
      public class MySTS implements javax.xml.ws.Provider<Source> {:

      3.   @Resource protected WebServiceContext context;

    3. Change the following line of code:

      4.   public class MySTS implements
          javax.xml.ws.Provider<Source>

      to:

        public class MySTS extends BaseSTSImpl implements
          javax.xml.ws.Provider<Source>

    4. For the invoke method, replace the return null line with the following return statement:

      5.   return super.invoke(source);

    5. Add the following method after the invoke method:

      6.   protected MessageContext getMessageContext() {
          MessageContext msgCtx = context.getMessageContext();
          return msgCtx;
        }

  12. Back in the Projects window, expand the MySTSProject node, then expand the Web Services node. Right-click on the MySTSService[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.
  17. Click the Keystore button to provide your keystore with the alias identifying 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.

    19. A new file is added to the project. To view the WSIT configuration file, expand Web PagesRight ArrowWEB-INFRight ArrowwsdlRight ArrowMySTS, then double-click the file MySTSService.wsdl. This file contains the sc:KeyStore element.

  19. Right-click the MySTSProject tab, select Properties. Select the Run category, and enter the following in the Relative URL field: /MySTSService?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.

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.

    2. 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 Client.

  2. Drill down from CalculatorWSServletClientRight ArrowWeb 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 list.
  5. Provide the service's certificate by pointing to an alias in the client truststore. 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 following 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://localhost:8080/MySTSProject/MySTSService, with WSDL file http://localhost:8080/MySTSProject/MySTSService?wsdl. To do this, follow these steps:
    1. Right-click the CalculatorWSServletClient node and select NewRight ArrowWeb Service Client. The New Web Service Client window appears.
    2. Select the WSDL URL option.
    3. 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:

      4.   http://localhost:8080/MySTSProject/MySTSService?wsdl

    4. 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 CalculatorWSServletClientRight ArrowWeb Service References.
  10. Right-click MySTSService, select Edit Web Service Attributes.
  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, 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 CalculatorWSServletClient project and selecting Run Project.

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/