To Secure the Example Web Service Client Application (SA) (The WSIT Tutorial)

The WSIT Tutorial

To Secure 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.

This example uses 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, type 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.).

Instead of creating a client servlet as is described in Creating a Client to Consume a WSIT-Enabled Web Service, just add the web service operation to the generated index.jsp file to create a non-JSR-109 client. To do this, perform these steps:
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.

Write a SAMLCallback handler for the client side to populate a SAML assertion into the client’s request to the service.

To create the SAMLCallbackHandler, follow these steps:
1. Right-click the CalculatorClient node.
2. Select New->Java Package.
3. For Package Name, type xwss.saml and click Finish.
4. Drill down from CalculatorClient->Source Packages->xwss.saml.
5. Right-click xwss.saml and select New->File/Folder.
6. From the Categories list, select Java Classes.
7. From the File Types list, select Empty Java File and click Next.
8. For Class Name, type SamlCallbackHandler and click Finish.
  
  The empty file appears in the IDE.
9. Download the example file SamlCallbackHandler.java from the following URL:
  
  https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645[amp ]expandFolder=6645[amp ]folderID=6645
10. Open the file in a text editor.
11. Modify the home variable to provide the hard-coded path to your GlassFish installation.
  
  For example, modify the line:
```
        String home = System.getProperty("WSIT_HOME");
```
  to
```
        String home = "/home/glassfish";
```
12. Copy the contents of this file into the SamlCallbackHandler.java window that is displaying in the IDE.

Drill down from CalculatorClient->Web Service References.

Right-click CalculatorWSService and 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 certificates described in To Update 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";
```
If you are using different keystore/truststore files than those described in To Update 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";
```

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.

Expand the Username Authentication node. In the SAML Callback Handler field, type the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler.

Click OK to close this dialog.

In the tree, drill down from the project to Source Packages->META-INF. Double-click 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:

<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="as-install\domains\domain1\config\keystore.jks"
    storepass="changeit" alias="xws-security-client" keypass="changeit"/>
  <sc:TrustStore wspp:visibility="private" 
    location="as-install\domains\domain1\config\cacerts.jks"
    storepass="changeit" peeralias="xws-security-server"/>
</wsp:All>

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