Example: SAML Authorization over SSL (SA)

Securing the Example Service Application (SA)

The following example application starts with the example provided in Chapter 5, 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. Optionally, before starting GlassFish, turn on the GlassFish HTTP dump options to verify that security is working as you expect. To do this, open the file <GLASSFISH_HOME>/domains/domain1/config/domain.xml and add the following lines to the jvm-options section:
    <jvm-options>-Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true</jvm-options>
    <jvm-options>-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true
    </jvm-options>
  2. Create the CalculatorApplication example by following the steps described in Chapter 5, WSIT Example Using a Web Container and NetBeans. Ignore the section that discusses adding Reliable Messaging.
  3. Update the GlassFish keystore and truststore files, if you haven't already done so. Instructions are described in Updating GlassFish Certificates.
  4. Create a user on GlassFish if you haven't already done so. Instructions for creating a user using the Admin Console are provided in Adding Users to GlassFish. Write down the name and password you create.
  5. Expand CalculatorApplicationRight ArrowWeb Services, then right-click the node for the web service, Calculator, and select Edit Web Service Attributes.
  6. Unselect the Reliable Messaging option if it is selected.
  7. In the CalculatorPortBinding section, select Secure Service.
  8. From the drop-down list for Security Mechanism, select SAML Authorization over SSL.
  9. Click the Keystore button to provide your keystore with the alias identifying the service certificate and private key. To do this, set the following options in the Keystore dialog:
    • Location--By default, the location and name of the keystore that stores the keys used by the web service is hard-coded into this field. If you are using GlassFish and have followed the steps in Updating GlassFish Certificates, this file is <GLASSFISH_HOME>/domains/domain1/config/keystore.jks.
    • Store Password--Specifies the password for the keystore file. The value for the default keystore is already entered, changeit.
    • 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 key in the specified keystore to be used for authentication. Select xws-security-server.
    • Click OK to close the dialog.
  10. Click the Truststore button to provide your truststore with the alias identifying the client certificate. To do this, verify the following options in the Truststore dialog:
    • Location--The location and name of the server truststore that stores the keys used by the web service is entered by default: <GLASSFISH_HOME>/domains/domain1/config/cacerts.jks.
    • Store Password--The password for the truststore file is entered by default: changeit.
    • You do not need to specify a truststore alias, so click OK to close the dialog.
  11. Click OK to exit the WSIT editor.
  12. Set up SSL as described in Configuring SSL For Your Applications
  13. 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.
  14. Verify that the WSDL file contains the TransportBinding and SignedSupportingTokens element, which in turn contains a SamlToken element.
  15. Expand the Web PagesRight ArrowWEB-INF elements of the application in the tree. Double-click the wsit-org.me.calculator.Calculator.xml file to open it in the editor. Verify that the sc:KeyStore and sc:TrustStore elements are present.
  16. 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. The SAML scenarios do not currently work with JSR-109-compliant clients, so, for this example, you have to create 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 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://localhost:8181/CalculatorApplication/CalculatorService?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.
    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 pointer to a sample implementation of a SAMLCallback handler can be found at Example SAML Callback Handlers.

    4. The SAMLCallback handler class may be placed in the client package. 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 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 the file.
    17. Paste into the SamlCallbackHandler.java window that is displaying in the IDE.
  4. Drill down from CalculatorClientRight ArrowWeb Service References.
  5. Right-click on CalculatorService, select Edit Web Service Attributes.
  6. Select the WSIT tab of the CalculatorService dialog.
  7. Provide the client's private key by pointing to an alias in the keystore. To do this,
    1. Expand the Certificates node.
    2. The Keystore Location field already specifies the location of the client keystore, <GLASSFISH_HOME>/domains/domain1/config/keystore.jks.
    3. The Keystore Password field already specifies the password for the client keystore, changeit.
    4. Click the Load Aliases button.
    5. Select xws-security-client from the Alias list.

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 + "domain1" +
   fileSeparator + "config" + 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";

  1. Provide the server's certificate by pointing to an alias in the client truststore. To do this, select the Certificates node,
    1. The Truststore Location field already specifies the location of the client truststore, <GLASSFISH_HOME>/domains/domain1/config/cacerts.jks.
    2. The Truststore Password field already contains the password for the client truststore, changeit.
    3. Click the Load Aliases button.
    4. Select xws-security-server from the Alias list.
  2. Expand the Username Authentication node.
  3. In the SAML Callback Handler field, enter the name of the class written in step 2 above, xwss.saml.SamlCallbackHandler.
  4. Click OK to close this dialog.
  5. In the tree, drill down from the project to Source PackagesRight ArrowMETA-INF. Double-click on CalculatorService.wsdl, and verify that lines similar to the following are present, and where xwss.saml.SamlCallbackHandler is the SAML Callback Handler class for the client:
    6.   <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>
  6. Compile and run this application by right-clicking the CalculatorClient node and selecting Run Project.

If you turned on the GlassFish HTTP dump options, you can view the server log at <GLASSFISH_HOME>/domains/domain1/logs/server.log to see verify that security was implemented as you expected.