LAB: Securing Web Services Communications with the Java Application Platform SDK

Open standards have gained momentum among enterprises as a mechanism for allowing their internal and external applications to cross network boundaries and communicate with those applications of their partners, customers and suppliers. XML, SOAP, and HTTPS are some of the technologies used to develop these interoperable web services, enabling open, flexible, and adaptive interfaces. This innate openness, though, creates security risks. Without proper protections, a web service can expose vulnerabilities that may lead to dire consequences. Thus, enabling the integrity, confidentiality, and security of web services and their communications is critical for both the enterprises and their consumers.

In order to secure communications between web services, the web service provider (WSP) needs to be configured to enforce message-level security. Similarly, the web service client (WSC) needs to be configured to supply message-level security. The following graphic represents a sample SOAP request with message-level security enabled. The WSC provides the SOAP body (containing the request) within the <env:Body> tag. The WSC's authentication provider inserts a security header in the <wsse:Security> tag, inserts a SAML token in the <saml:Assertion> tag and, signs the message in the <ds:Signature> tag. Once enabled, the request is sent on to the WSP.


SOAP Request Message

The WSP's authentication provider receives the request and verifies the signature and security token before forwarding the request on to the WSP. The web service then processes the request and returns a response. The WSP's authentication provider inserts the appropriate security header in the <wsse:Security> tag and a signature in the <ds:Signature> tag after which the response is returned back to the WSC. Upon receiving the response, the WSC's authentication provider verifies the signature before forwarding it back to the WSC. The following graphic represents a sample SOAP response from a WSP.


SOAP Response Message

The Java™ Application Platform SDK with Tools application bundle can be used to enable message-level security, without changes to the application itself, by modifying the deployment descriptor file of the service's web container. Because the application bundle installs (among other applications) Sun Java System Application Server, these instructions document how to do this by modifying its deployment descriptor file, sun-web.xml. Additionally, the instructions:

Prerequisites

This lab assumes basic knowledge of, or programming experience with, the following:


Software Needed

Before beginning:


Variable Used

 AS_HOME refers to the top level directory of the Java Application Platform SDK with Tools installation.


The Lab

The Web Services Security lab can be downloaded for use after installing the Java Application Platform SDK with Tools application bundle. It demonstrates how to use Sun Java System Access Manager, NetBeans IDE 5.5 and the Java Application Platform SDK to secure communications between the client and server of a sample Stock Quote Service. In the lab, a Stock Quote Service client requests a stock price from a Stock Quote Service provider; in response, the Stock Quote Service provider returns a quote based on the following:

Three Netbeans projects are provided in the download. (A Netbeans project is a grouping of Java source files and associated information including, but not limited to, what belongs in the classpath and how to build the source.) The StockClient project serves as a WSC. It presents a graphical user interface within a web browser that will configure the request and send it to the Stock Quote Service provider. ClientServlet.java is the implementation of the Stock Quote Service client. The following methods implement the functionality:

The StockServer project serves as the WSP. It receives a request from the WSC, generates the appropriate response, and returns it to the WSC. The following files define aspects of the WSP:

The third Netbeans project is the StandAloneStockClient project. This project builds a standalone WSC that does the following:

See Exercise 5: Secure a Stand-Alone Web Service Client for more information on this project.

Expected duration of the lab: 90 minutes


Exercises



Exercise 0: Install and Verify Configuration of the Java Application Platform SDK with Tools

Installation instructions for the Java Application Platform SDK with Tools can be found on the Sun Developer Network (SDN) web site. The bundle installs the following components:

After installation, verify that the SDK, Application Server, and Access Manager are correctly configured with the following procedure.

  1. To start Application Server, run the following command:

      AS_HOME/bin/asadmin start-domain domain1

  2. Access the default Application Server home page by typing the following URL into a browser:

      http://localhost:8080/

  3. Access the Application Server Administration Console by typing the following URL into a browser:br> 

      http://localhost:4848/

  4. Login to the Application Server Administration Console using the default admin and adminadmin as the username and password, respectively.

  5. Click Web Applications in the Common Tasks frame to confirm that Access Manager was installed and deployed with the URI /amserver

  6. Click Launch in the Web Applications frame to display the login page for Access Manager.

  7. Login to the Access Manager Console using the default amadmin and admin123 as the user name and password, respectively.



The following text and screen captures will familiarize you with the Access Manager Console. It provides an interface to configure identities as well as the standard security mechanisms used to authenticate web service requests. (Access Manager provides other features such as policy management for access control, federation, and single-sign-on but these features are not covered in this lab. See the Sun Java System Access Manager product page for more information.)



Using the Access Manager console screen capture displayed above as a guide, click on a configured realm. Click on the Data Stores tab to display that realm's identity data stores. The screen capture below illustrates that the sample realm uses a flat file repository to store identity data. Other types of data stores (such as Sun Java System Directory Server, or Microsoft Active Directory) can be added, or existing ones can be modified or removed.



Now, click on the Subjects tab to display the screen below. Subjects provides the interface for, among other things, managing identities (users) and security provider agents. By default, Users is displayed. As shown, two users have been created:

Additional user entries can be added and existing user entries can be modified or removed.



Lastly, click on the Agents tab to display the screen below. Agents lists the security providers (or agents) that can be used to secure a web service. As previously discussed, the WSC must add security credentials to the SOAP headers in its requests. These credentials will then be validated by the WSP before the request is processed. However, adding security credentials must be accomplished in a standard manner so that inter-operability between multiple vendors is possible. The agents listed below are those supported by Access Manager. Clicking on a specific agent provides its configuration attributes (key values, trusted certificates, etc.). Brief explanations of the supported agents follow the screen capture.



Brief explanations of the supported agents:

Exercise 1: Load the Stock Quote Web Service Provider and Client Projects in Netbeans

The following procedures guide you in creating the WSP and WSC using two of the projects included in the Web Services Security download.

To load the StockServer project:

  1. Open the Netbeans IDE's console.

  2. Choose File > Open Project

  3. From the Open Project dialog, navigate to the nbprojects directory in the unzipped WebServiceSecurity directory.

  4. Choose StockServer and click Open Project Folder to load the StockServer project.

    After loading the project, a dialog box will open telling you to resolve a reference problem.

  5. Right click on StockServer in the left frame and choose Resolve Reference Problems... from the drop down menu.

  6. Click Resolve in the resulting window and find appserv-rt.jar in the Browse dialog box.

    appserv-rt.jar can be located in AS_HOME/lib.

  7. After the reference is resolved, close the pop-up window.

To load the StockClient project:

  1. Choose File > Open Project

  2. From the Open Project dialog, navigate to the nbprojects directory in the unzipped WebServiceSecurity directory.

  3. Choose StockClient and click Open Project Folder to load the StockClient project.

    The Projects frame now contains a StockServer and StockClient project node.

Exercise 2: Deploy and Test Unauthenticated Communications between the Stock Quote Web Service Provider and Client

The following procedures guide you in deploying the Stock Quote Service provider and client and testing unauthenticated communications. As mentioned, a delayed stock quote will be provided when the request is not authenticated.

  1. In the Projects frame, right-click the StockServer project node and choose Deploy Project from the drop down menu.

    Netbeans now does the following:

  2. In the Projects frame, right-click the StockClient project node and choose Deploy Project from the drop down menu.

    Netbeans now does the following:

  3. To test the client with an unauthenticated request, right-click the StockClient project node in the Projects frame and choose Run Project from the drop down menu.

    The Stock Quote Service client interface will open in a browser window at the following URL:

      http://localhost:8080/stockclient/

    NOTE: You might have to login to the Access Manager Console using the top-level administrator or either of the sample users mentioned above if the session has timed out.

  4. Click Submit to request the stock price for SUNW.

    The response is a delayed stock quote as the request is not authenticated. (Note the delay time is set to 20.)




Exercise 3: Enable Message-level Security for Communications between the Stock Quote Web Service Provider and Client

In this exercise, we will use the SAML-HolderOfKey profile to secure the web services communications. A default key store will be used and the response will not be signed. (The default key store is installed with Access Manager.) We will edit the SAML-HolderOfKey profile to reflect these attributes, and configure the Stock Quote Service client and provider - all using the Netbeans console.


To edit the SAML-HolderOfKey profile:

  1. Click the Runtime tab in the left frame of the Netbeans console.

  2. Expand the Sun Java System Access Managers node.

  3. Expand the Default Instance node.

  4. Expand the Profiles node.

  5. Right-click SAML-HolderOfKey and select Edit.

    The SAML-HolderOfKey editor is displayed.

  6. Clear the Sign Response checkbox.

  7. Leave the Use Default Key Store checkbox selected and click OK.

    This modifies the Application Server deployment descriptor file, sun-web.xml. You can follow this sub-procedure to see sun-web.xml and the changes made.

    1. Expand the StockServer node under the Projects tab.

    2. Expand the Configuration Files node.

    3. Right-click sun-web.xml node and choose Edit.

      sun-web.xml is displayed in the right frame of the Netbeans console. The following XML code fragment (which defines the Access Manager implementation of the WS-I BSP SAML-HolderOfKey profile) can be seen in the opened file

      <message-security-binding auth-layer="SOAP" provider-id="AMServerProvider-SAML-HolderOfKey">
        <message-security>
          <message>
          </message>
          <request-protection auth-source="content"/>
          <response-protection auth-source="content"/>
        </message-security>
      </message-security-binding>

      Note that AMServerProvider-SAML-HolderOfKey is defined as the security mechanism. (For more information on this profile, see the WS-I BSP SAML Token Profile specification.

      The following profiles can also be used as values for the message-security-binding element in the provider-id attribute:


To configure the Stock Quote Service provider:

  1. Click the Projects tab in the left frame of the Netbeans console.

  2. Expand the StockServer node.

  3. Expand the Web Services node.

  4. Right-click stockservice node and select Edit Web Service Attributes from the drop down menu.

    The Web Service Provider Security Configuration editor opens.

  5. Click the Enable Message Level Security checkbox.

  6. Select SAML-HolderOfKey from the Request drop-down menu under Security Mechanisms.

  7. Click OK.

  8. Close the StockServer node.


To configure the Stock Quote Service client:

  1. Expand the StockClient node.

  2. Expand the Web Service References node.

  3. Right-click Stockservice node and select Edit Web Service Attributes.

    The Web Service Client Security Configuration editor opens.

  4. Click the Enable Message Level Security checkbox.

  5. Select SAML-HolderOfKey from the Request drop-down menu under Security Mechanisms.

  6. Leave the Use Default Key Store checkbox selected and click OK.

  7. Close the StockServer node.

You can now re-deploy the server and client nodes and run the lab again, following the instructions in Exercise 2: Deploy and Test Unauthenticated Communications between the Stock Quote Web Service Provider and Client. When the stock symbol SUNW is submitted, the response is a real time stock quote rather than the delayed quote as the WSP code has determined that the WSC is authenticated. (Note that the stock quote is the same as above; the delay time though is set to 0.)



Exercise 4: Enable User Authentication for Access to the Stock Quote Service Client

In the previous exercises, security was enabled for communications between the WSC and WSP. This implies that the WSC authenticates any user accessing its Stock Quote Service interface and, if required, propogates said user's credentials to the WSP for processing. In this exercise, we will enable user authentication for the Stock Quote Service client using the Liberty Alliance Project Bearer Token security profile. WS-I BSP security mechanisms can also be used but a benefit of using security mechanisms defined by the Liberty Alliance Project is that configurations for user authentication are built in to the profiles. Thus, no additional configuration is needed to explicitly enable user authentication. (See below for instructions on how to enable user authentication for other security mechanisms.)


To configure the Stock Quote Service provider for authentication:

  1. In the Projects frame, expand the StockServer project node.

  2. Expand the Web Services node under StockServer.

  3. Right-click the StockService node under Web Services and choose Edit Web Service Attributes from the drop down menu.

    The Web Service Provider Security Configuration editor opens.

  4. Click the Enable Message Level Security checkbox.

  5. Select LibertyBearerToken from the Request drop-down menu under Security Mechanisms.

  6. Click OK.

  7. Close the open StockServer node in the Projects frame.


To configure the Stock Quote Service client for authentication:

  1. In the Projects frame, expand the StockClient project node.

  2. Expand the Web Services References node under StockClient.

  3. Right-click the StockService node under Web Services References and choose Edit Web Service Attributes from the drop down menu.

    The Web Service Client Security Configuration editor opens.

  4. Click the Enable Message Level Security checkbox.

  5. Select LibertyDiscoverySecurity from the Request drop-down menu under Security Mechanisms.

  6. Click the Response checkbox to verify the response.

  7. Click the Use Default Key Store checkbox under Existing Certificate Settings.

  8. Click OK.


To deploy and run the Stock Quote Service with user authentication:

  1. Right-click the StockServer project node in the Projects frame and select Deploy Project from the drop-down menu.

    Netbeans does the following:

  2. Right-click the StockClient project node in the Projects frame and select Run Project from the drop-down menu.

    Netbeans does the following:

    Click to enlarge

  3. Log in to Access Manager by typing jsmith or jdoe in the User Name and Password fields and clicking Login.

    The Stock Quote Service client request screen appears.

  4. Click Submit on the client request screen.

    When the stock symbol for SUNW is submitted, the response is a real time stock quote. However, this time, the WSP also obtains the security credentials of the user as a SAML assertion in addition to that of the WSC.




To view the changes in the WSC deployment descriptor:

The following procedure displays the Application Server deployment descriptor, sun-web.xml, pointing out the changes made in this exercise.

  1. In the Projects frame, expand the StockClient project node.

  2. Expand the Configuration Files node.

  3. Right-click sun-web.xml and choose Edit from the drop down menu.

    Line 3 defines an HTTP provider that forces users to authenticate before accessing the web service client:

    <sun-web-app error-url="" httpservlet-security-provider="AMHttpProvider">

    Line 19 forces SOAP messages to be authenticated:

    <message-security-binding auth-layer="SOAP" provider-id="AMClientProvider">
    <message-security>
        <message>
        <message/>
        <request-protection auth-source="content"/>
        <response-protection auth-source="content"/>
    </message-security>
</message-security-binding>

  4. Now, right-click web.xml and choose Edit from the drop down menu.

    The following XML code fragment is added to web.xml to restrict those who access the Stock Quote Service client to authenticated users:

    <security-constraint>
        <web-resource-collection>
                <web-resource-name>AUTHENTICATED_RESOURCE</web-resource-name>
                  <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
                <role-name>AUTHENTICATED_USERS</role-name>
        </auth-constraint>
</security-constraint>

Exercise 5: Secure a Stand-Alone Web Service Client

In the previous exercises, we were using the Java Application Platform SDK and its built-in security features to secure web service communications. In this exercise (which uses the StandAloneStockClient project in the nbprojects directory of the unzipped WebServiceSecurity directory), we build a standalone WSC that will secure its own communications with a WSP using the web service security APIs included with Access Manager, and the Java Platform SOAP APIs included with the Java Platform SDK to construct and secure the SOAP messages.

SecuringWS.java (available in the StandAloneStockClient project directory) defines the implementation for securing the web service communications. The main method in this code, main(String[] args), does the following:

NOTE:You can also view SecuringWS.java after creating the project in the Netbeans console by expanding the StandAloneStockClient project node, then the Source Packages node, and finally the com.samples node.


To create the StandAloneStockClient project in Netbeans:

  1. Choose File > Open Project from the Netbeans IDE's console.

  2. From the Open Project dialog, navigate to the nbprojects directory in the unzipped WebServiceSecurity directory.

  3. Choose StandAloneStockClient and click Open Project Folder to add the StandAloneStockClient project.

    After loading the project, a dialog box will open telling you to resolve some reference problems. Close this dialog box and proceed.

  4. Right click on StandAloneStockClient in the left frame and choose Resolve Reference Problems... from the drop down menu.

  5. Select the appropriate file, click Resolve in the resulting window and find the file in the Browse dialog box using the paths defined below.

    The following file references will need to be resolved:

  6. AS_HOME/addons/amserver

  7. AS_HOME/lib/javaee.jar

  8. AS_HOME/lib/appserv-ws.jar

  9. AS_HOME/lib/appserv-rt.jar

  10. After the references are resolved, close the dialog box.


Since the UserNameToken Profile is being used in this exercise we need to change the profile we originally defined for the previous exercises.

To change the web service security mechanism for the StockServer project in Netbeans:

  1. In the Projects frame, expand the StockServer project node.

  2. Expand the Web Services node under StockServer.

  3. Right-click the StockService node under Web Services and choose Edit Web Service Attributes from the drop-down menu.

    The Web Service Provider Security Configuration opens.

  4. Select UserNameToken from the Request drop-down menu under Security Mechanisms.

  5. Click OK.

  6. Close the open StockServer node in the Projects frame.

  7. Right-click the StockServer project node and choose Deploy Project.

    This will redeploy the Stock Service using the UserNameToken profile for authenticating web service requests.


To run the standalone Stock Client:

  1. In the Projects frame, right click the StandAloneStockClient project node and choose Build Project.

  2. Right click the StandAloneStockClient project node again and this time choose Run Project.


The screen capture below shows the output in the Netbeans Console for the secure web service communication.






Next Steps

  1. Using Authorization APIs (com.sun.identity.policy.client.PolicyEvaluator) to secure the web service using roles and groups

  2. Using Identity Management APIs (com.sun.identity.idm.AMIdentity) to customize responses

  3. Using SOAPRequestHandler to secure WSP



References

  1. OpenSSO

  2. OASIS Web Services Security

  3. Liberty Alliance Project