Securing Web Services Using the SAML or UserNameToken Profiles

Contributed and maintained by Bob May
November 2007 [Revision number: V1-3]
This publication is applicable to the full NetBeans IDE 6.0 release

This tutorial illustrates how you can enable SAML-based and UserNameToken-based authentication between a web service client and a web service provider using the bundled Access Manager along with the integrated support for the WS-Security standard in Application Server's web services client and server-side containers.

Expected duration: 40 minutes

Contents

 

Tutorial Requirements

NetBeans IDE 6.0 comes bundled with all the necessary runtimes to enable you to start developing secure, identity-enabled web services clients and providers. These runtimes include:

Before you proceed, make sure you review the requirements in this section.

Prerequisites

This tutorial assumes that you have some basic knowledge of, or programming experience with, Java and Web Services technologies.

Software Needed for This Tutorial

Before you begin, you need to install the following software on your computer:

top

Installing the Sun Java System Access Manager

If you have already installed and configured the Access Manager in the past, please check your userdir and if it exists, delete the file

[Your_Userdir]/AccessManager/AMConfig_opt_SUNWappserver_domains)domain1_applications_j2ee-modules_amserver_

before you begin a fresh installation.

To install the Sun Java System Access Manager, you must first esnure that you have installed the full NetBeans IDE. Next,

  1. Obtain the Java Application Platform SDK Update 2 or later from http://java.sun.com/javaee/downloads/index.jsp.
  2. Run the Java SDK installer, specifying an installation directory of your choice, and accepting the default options.
  3. Choose Add-Ons that include the Sun Java System Access Manager.
  4. Continue to run the Installer, when it finishes, start the Server and select Finish.
  5. Start the IDE.
  6. In the Services tab, select the Servers node. right-click the Servers node and choose Add Server from the pop-up menu.. The Add Server Instance dialog opens.
  7. Click Next. The Platform Location Folder page opens.
  8. In the Platform Location field, use the Browse button to navigate to and select the directory containing the Java Application Platform SDK you have just installed.
  9. Click Finish.
  10. The Sun Java System Access Manager appears as a node in the Services Tab under the Application Server you have just installed. You must start the Application Server to begin working with Sun Java System Access Manager.

    top

Verifying the Configuration of the Access Manager Installation

  1. In the Services window, expand the Sun Java System Access Managers node.
  2. You are then redirected to the Login page, which is displayed immediately on successive logins. You can login into the Sun Java System Access Manager.The Log In page opens, indicating that Access Manager server is running.

You need to configure the Access Manager to run properly. It is configured by default when you first start the Glassfish Server you obtained from the SDK, but you can reconfigure it later, if needed. For further information, check the [your_SDKGlassfish_location]/addons/README.html file.

top

Configuring the Tutorial Environment

  1. Start the IDE.
  2. To verify that the Sun Java System Application Server is configured in the IDE, click the Runtime tab and expand the Servers node.
  3. If the Servers node does not contain a Sun Java System Application Server 9 node, follow the steps in Adding an Application Server.
  4. In the Runtime window, expand the Servers node, right-click the Sun Java System Application Server 9 node and choose Start from the pop-up menu.
    Wait until the following message appears in the Output window:
    Application server startup complete.
    When the server is running, the IDE displays a green arrow badge on the Sun Java System Application Server 9 node.
    Note: If the Start option is not available, your server is already running.

top

Creating the Tutorial Projects

Two tutorial projects are StockQuoteServer and StockQuoteClient.

To create the StockQuoteServer project:

  1. From the IDE's main menu, choose File > New Project.
  2. In the Categories list, expand the Samples node, then select the Identity Blueprints node.
  3. In the Projects list, select Stock Service.
  4. Click Next.
  5. Accept the default Project Name (StockQuoteServer) and optionally change the Project Location.
  6. Click Finish.

To create the StockQuoteClient project:

  1. From the IDE's main menu, choose File > New Project.
  2. In the Categories list, expand the Samples node, then select the Identity Blueprints node.
  3. In the Projects list, select Stock Client.
  4. Click Next.
  5. Accept the default values for Project Name (Stock Client) and Project Location.
  6. Click Finish.
    The Projects window now contains a Stock Client project node.

top


Securing Web Services: Using the SAML-HolderOfKey Security Mechanism

In this scenario, we are using the SAML-HolderOfKey security profile without the response being signed but using the default key store. To do this, we will first edit the token profile for the Access Manager and then configure the web service provider and client.

To edit the SAML-HolderOfKey profile:

  1. In the Runtime window, expand the Sun Java System Access Managers node, then expand the Default Instance and the Profiles nodes.
  2. Select the SAML-HolderOfKey node
  3. Right-click and choose Edit.
    The Edit SAML-HolderOfKey Profile dialog box opens.
  4. Clear the Sign Response checkbox.
  5. Locate Existing Certificate Settings, and confirm the Use Default Key Store checkbox selected.
  6. Click OK.

To configure the web service client:

  1. In the Projects window, expand the StockQuoteClient node and the Web Service References node.
  2. Locate the Web Service References node, right-click the StockService node and choose Edit Web Service Attributes from the pop-up menu.
    The Web Service Client Security Configuration dialog box opens.
  3. Select the Enable Message Level Security checkbox.
  4. Locate Security Mechanism from the Request drop-down list, select SAML-HolderOfKey.
  5. Locate Existing Certificate Settings. Confirm that the Use Default Key Store checkbox is selected.

  6. Click OK.

You can now proceed to deploying and running the sample by following the instructions in Deploying and Running the Project.

top

Securing Web Services: Using the UserNameToken Security Mechanism

In this scenario, you use the UserNameToken security profile with signed response and use the default key store. To do this, you first edit the token profile for the Access Manager and then configure the web service provider and client.

To edit the UserNameToken profile:

  1. In the Runtime window, expand the Sun Java System Access Managers node, then expand the Default Instance and the Profiles nodes.
  2. Select the UserNameToken node, then right-click and choose Edit.
    The Edit UserNameToken Profile dialog box opens.
  3. Locate Existing Certificate Settings, and confirm that the Use Default Key Store checkbox selected.
  4. Locate Username Token Profile Info. Click the Add button to add a UserNameToken record for the web service client.
    The Add User dialog box opens.
  5. In the Username field, type sherry, in the Password field, type mypw, and click OK.

  6. Click OK to close the Edit UserNameToken Profile dialog box.

To configure the web service provider:

  1. In the Projects window, expand the StockServer node and the Web Services node.
  2. Locate the Web Services node. Right-click the stockservice node and choose Edit Web Service Attributes from the pop-up menu.
    The Web Service Provider Security Configuration dialog box opens.
  3. Select the Enable Message Level Security checkbox.
  4. Locate Security Mechanism, from the Request drop-down list, select UserNameToken.

  5. Click OK.

To configure the web service client:

  1. In the Projects window, expand the StockClient node and the Web Service References node.
  2. Locate the Web Service References node. Right-click the Stock service node and choose Edit Web Service Attributes from the pop-up menu.
    The Web Service Client Security Configuration dialog box opens.
  3. Select the Enable Message Level Security checkbox.
  4. Locate Security Mechanism from the Request drop-down list, select UserNameToken.
  5. In the Username field, type sherry and in the Password field, type mypw.
  6. Select the Verify Response checkbox.
  7. Locate Existing Certificate Settings, and confirm that the Use Default Key Store checkbox selected.

  8. Click OK.

You can now proceed to deploying and running the sample by following the instructions in Deploying and Running the Project.

top

Deploying and Running the Project

  1. In the Projects window, right-click the StockQuoteService project node and choose Deploy Project.
    The IDE does the following:
  2. In the Projects window, right-click the StockQuoteClient project node and choose Run Project.
    The IDE does the following:

  3. Click Submit.

    You can click on the "View SOAP Messages" part of the display to see SOAP messages associated with this request.

top

Exploring the Log Files

The instructions in this section are optional. Use these instructions to view the changes in the log files.

  1. Before you proceed to the next step, enable the most granular logging level.
    Follow the instructions in Changing the Security Level on the Application Server.
  2. In the Projects window, right-click the StockQuoteClient project node and choose Run Project from the pop-up menu.
  3. Open the Application Server log file (server.log) in the following directory: application-server-installation-directory\domains\domain1\logs.
    If you accepted the default values during installation, the window displays the C:\Sun\AppServer\domains\domain1\logs directory.
  4. Notice the changes in the log file.
    The log file is edited to show that the modules are is using the methods defined in the configuration panels.
    Samples of sections of the modified log file are available from the following links..

top

Additional Configuration Tasks

This section provides information about additional configuration tasks that you might want to perform.

top

 

Configuration Information for Application Server Not Installed on Port 8080

If the installation of the Sun Java System Application Server was performed on a port other than 8080, you must perform the additional configuration steps, as follows:

  1. In the Projects window, expand StockQuoteClient > Web Pages > WEB-INF and wsdl, and open the stock.wsdl file in the editor.
  2. Click the Source button to switch to the Source view of the file.
  3. Scroll to the bottom of the file and locate the following line:
    <soap:address location="http://localhost:8080/stockservice/stockservice" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"/>
  4. Replace the 8080 value with the port number where the Application Server is installed.
  5. Save your changes and close the file.

top

Changing the Security Level on the Application Server

  1. In the Runtime window, right-click the Sun Java System Application Server 9 node and choose View Admin Console.
  2. Type admin for the username and adminadmin for the password.
  3. In the left navigation frame, click the Application Server link.
  4. In the right frame, click the Logging tab and then click the Log Levels tab.

    Application Server admin console, Log Levels tab, click to enlarge

  5. Scroll to the bottom of the page and set the Security to FINEST.

    Application Server admin console, Security setting, click to enlarge

  6. Click the Save button and log out.

top

References

top

Summary

In this tutorial, we have learned how to enable SAML-based and UserNameToken-based authentication between a web service client and a web service provider. To do this, we have

top

Next Steps


Send Us Your Feedback

top