A Tutorial on Applying Web-Service Security to EJB Applications, Part 1 of 3: Overview

Print-friendly Version

[Part 1] [Part 2] [Part 3]

Open standards have gained momentum among enterprises as a mechanism for Web services to communicate with partners, customers, and suppliers. XML, Simple Object Access Protocol (SOAP), and HTTPS are among the technologies for developing interoperable Web services with open, flexible, and adaptive interfaces. That inherent openness, however, poses security risks. Without proper protections, Web services can expose vulnerabilities that could lead to dire consequences. Ensuring that those services and their communications are integral, confidential, and secure is critical for all parties.

Web applications comprise components, such as those based on Enterprise JavaBeans (EJB) technology, that can be deployed to containers. The containers offer two types of security for the components: declarative security and programmatic security. The combination of container security and Web-service security (also called message-level security) provides the best security model for protecting enterprise components hosted by Web services.

This three-part tutorial steps you through the process of securing an EJB technology-based Web service—an example of a stock-quote service (henceforth, the service)—with Sun Java System Access Manager (henceforth, Access Manager) and the Java Application Platform Software Development Kit (SDK) with Tools bundle (henceforth, the bundle). It is assumed that you are familiar with Java and Web-service technologies.

The exercises in the full tutorial will show you how to do the following:

• Configure identity repositories and users in Access Manager, which is built from Open Web Single Sign-On (OpenSSO), Sun's open Web access management project.
  
  
• Work with Access Manager security providers, also called agents.
  
  
• Secure Web services with the supported mechanisms.
  
  
• Enable user authentication for a Web-service client (WSC).
  
  
• Secure a WSC.

Part 1 describes the concepts, installation and configuration procedures, and security profiles supported by Access Manager. Part 2 explains the process flow and Exercises 1 through 3. Part 3 covers Exercises 4 and 5.

To secure communications among Web services, configure the Web-service provider (WSP) to enforce message-level security and configure the WSC to supply such security.

Figure 1 illustrates the process of creating message-level security in a sample SOAP request. Here is what takes place:

1. The WSC supplies the SOAP body with the request within the <env:Body> tag.
   
   
2. The WSC's authentication provider inserts a security header into the <wsse:Security> tag and a SAML token into the <saml:Assertion> tag, and then signs the message in the <ds:Signature> tag.
   
   
3. The WSC sends the request to the WSP.
   
   

   Figure 1: Enablement of a SOAP Request With Message-Level Security

    
   

Next follows the verification and response, as illustrated in Figure 2.

1. The WSP's authentication provider receives the request, verifies that the signature and security token are correct, and forwards the request to the WSP.
   
   
2. The Web service processes the request and responds.
   
   
3. The WSP's authentication provider inserts the appropriate security header into the <wsse:Security> tag and a signature into the <ds:Signature> tag.
   
   
4. The WSP's authentication provider responds to the WSC, optionally with a signature.
   
   
5. The WSC's authentication provider verifies that the signature is correct and returns the response to the WSC.
   
   

   Figure 2: Verification of a SOAP Response

    
   

With the bundle, you can enable message-level security by modifying the deployment descriptor of the service's Web container—without changing the application itself. The bundle includes Sun Java System Application Server (henceforth, Application Server).

First, download the bundle. Important: To ensure that Access Manager is included as part of the download, on the download page, do either of the following:

• Under Java EE 5 SDK Update 3, click Download with Tools.
  
  
• Under Java Application Platform SDK Update 3 Beta, click Download with Tools.

Next, install the bundle.

Finally, download the tutorial. Afterward, decompress the ZIP file to a location of your choice, called LAB_ROOT in the rest of this article.

Follow the procedures in this section to configure the lab environment for the tutorial.

Configuring Message-Level Security
Configure the message-level security in Application Server for Access Manager. For more details on configuring message-level security providers, see Chapter 9 in the Sun Java System Application Server Platform Edition 9 Administration Guide.

1. Start Application Server. Type:
   SDK_BUNDLE_HOME/bin/asadmin start-domain domain1
   
   
2. Go to the Application Server Administration Console at http://localhost:4848/.
   
   
3. Log in to the Application Server Administration Console.
   
   The default credentials are admin for user name and adminadmin for password.
   
   Note: The admin password for the Access Manager Administration Console is the same as that for the Application Server Administration Console.
   
   
4. In the left pane, expand Configuration > Security > Message Security.
   
   SOAP and HttpServlet are displayed under Message Security as the two binding components for which you can configure end-to-end security.
   
   
5. Click SOAP. In the right pane, click the Providers tab.
   
   The configured Access Manager message security providers along with other providers are displayed. See Figure 3.
   
   

   Figure 3: Configurations for Message Security Providers (Click image for larger view.)

    
   
   The providers in this tutorial are AMClientProvider for the WSC and AMServerProvider for the WSP.
   
   To view the configurations, click the respective providers for the Edit Provider Configuration pane (see Figure 4). Note that under Additional Properties is the attribute providername with a value of wsc or wsp for AMClientProvider or AMServerProvider, respectively. This property represents the identity with which Access Manager determines the security mechanisms.
   
   
6. In the left pane, click HttpServlet and then click the Providers tab in the right pane.
   
   The configured Access Manager security providers for the http bindings are displayed.
   
   
7. Click AMHttpProvider to view its configuration.
   
   
8. Similarly to what you did for the SOAP providers, verify that the attribute providername is under Additional Properties.
   
   If it is, proceed to the next subsection. Otherwise, perform step 9 to add the attribute.
   
   
9. Optional. Click Add Property and type providername in the Name text field and wsc in the Value text field. Save the configuration. See Figure 4.
   
   

   Figure 4: Configurations for AMHttpProvider (Click image for larger view.)

    
   

Verifying Installation of Access Manager
Next, verify that Access Manager has been installed appropriately:

1. Under Common Tasks on the left of the Application Server Administration Console, expand Applications > Web Applications to confirm that you have installed Access Manager and deployed it with the URI /amserver. See Figure 5.
   
   

   Figure 5: Verification of the Installation and Deployment of Access Manager

    
   
   
2. In the right pane, click Launch on the amserver row for the Access Manager login screen.
   
   The URL is http://localhost:8080/amserver/UI/Login. However, if you are redirected to a host, you must update the hosts file with the correct host name. On UNIX, that file is /etc/hosts; on Windows, it's C:\WINDOWS\system32\drivers\etc\hosts. By default, the file contains a one-line entry, as follows:
   
   

   127.0.0.1

   localhost

   hostname

   
   
3. Log in to the Access Manager Administration Console with the default credentials: amadmin as the user name and adminadmin as the password.
   
   Figure 6 shows the default home page of the Console. Displayed are the general properties that are configured for the default (root) realm, which can be either sun or sample. In this case, sun is the realm name; sample also works for the exercises in this tutorial.
   
   

   Figure 6: Default Home Page of the Access Manager Administration Console

    
   

This section explains the interfaces in the Access Manager Administration Console for configuring identities and the standard security mechanisms for authenticating Web-service requests. Access Manager also enables you to manage policies for access control, federation, and single-sign-on. Those tasks are outside the scope of this tutorial, however. For details, see the Access Manager site.

Now explore the Administration Console:

1. On the home page, click the Data Stores tab to display the realm's identity data stores. See Figure 7.
   
   

   Figure 7: Data Stores

    
   
   Here, the sun realm stores identity data in a flat files repository. You can delete or update data stores or add other types of stores, such as Sun Java System Directory Server and Microsoft Active Directory.
   
   
2. Click the Subjects tab. See Figure 8.
   
   

   Figure 8: User Screen Under Subjects

    
   
   The Subjects screens are the interface for managing identities (users), security providers (agents), and so forth. By default, the user data is displayed: John Smith (user name and password: jsmith) and Jon Doe (user name and password: jondoe). You can create, delete, or update users.
   
   
3. Under Subjects, click Group. See Figure 9.
   
   

   Figure 9: Group Screen Under Subjects

    
   
   Here, two groups have been created: Gold and Silver, which are memberships for the stock-quote Web service in the tutorial (described in Part 2 of this series). You can create, delete, or update groups. For the related procedures on managing users and groups, see Chapter 6 of the Sun Java System Access Manager 7.1 Administration Guide.
   
   
4. Click Gold and then the User tab to display the membership details. See Figure 10.
   
   

   Figure 10: Gold Membership Details

    
   
   
5. Click the Agents tab under Subjects. See Figure 11.
   
   

   Figure 11: Agents

    
   
   The Agents screen lists the security providers (agents) that secure Web services. Recall that the WSC must add security credentials to the SOAP headers in its requests. The WSP then validates those credentials before processing the requests. You must add the credentials in a standard manner to enable interoperability among multiple vendors.
   
   The agents listed in Figure 11 are those supported by Access Manager. Among them are wscWSC and wspWSP, which correspond to AMClientProvider and AMServerProvider, respectively, and which you previously configured in Application Server for message-level security. To configure its security requirements, the WSC uses wscWSC; the WSP, wspWSP.
   
   Clicking a specific agent displays its attributes (key values, trusted certificates, and so on).
   
   
6. Click wscWSC to display its security properties. See Figure 12.
   
   

   Figure 12: wscWSC Properties

    
   
   
7. Select Active for Device Status, Anonymous under Security Mechanism, and Yes for Preserve Security Headers.
   
   Preserving security headers enables you to view the SOAP messages exchanged between the WSC and the WSP.
   
   
8. Click Save and then click Back to Subjects.
   
   
9. Click wspWSP and ensure that the same properties are configured. See Figure 13.
   
   

   Figure 13: wspWSP Properties

    
   

Access Manager supports seven security profiles, as follows:

• UserNameToken — Secures the Web service with a user name and password and, optionally, a signature of the requester. With UserNameToken, a WSC identifies the requester by user name and, optionally, a password (or a shared secret or password equivalent) to authenticate the identity to the WSP.
  
  
• X509Token — Secures the Web service with a public key infrastructure (PKI), in which the WSC and the WSP trust each other's public keys or share a common, trusted certificate authority. A WSC supplies a public key to identify the requester and to authenticate itself to the WSP.
  
  
• SAML-HolderOfKey — Secures the service with the Security Assertions Markup Language (SAML). A WSC supplies a SAML assertion with the holder-of-key confirmation method to identify the requester and to authenticate itself to the WSP.
  
  SAML-HolderOfKey is derived from the Basic Security Profile (BSP) of the Web Services Interoperability Organization (WS-I).
  
  
• SAML-SenderVouches — Secures the Web service with SAML and a different confirmation method. A WSC supplies a SAML assertion with the sender-vouches confirmation method to assert that the WSC is acting on behalf of the subject of the SAML subject statement and to authenticate itself to the WSP.
  
  
• LibertyX509Token — Secures the Web service with the Web Service Security X.509 Certificate Token Profile. Though similar to X509Token (see the second bullet above), this security profile complies with the processing rules defined by the Liberty Alliance Project.
  
  
• LibertyBearerToken — Secures the Web service with the Liberty Bearer Token Profile. Essentially, both LibertyBearerToken and SAML-HolderOfKey (see the third bullet above) represent a SAML assertion, except that their assertion subjects are different. In LibertyBearerToken, the subject is the user's; in SAML-HolderOfKey, it is the WSC's.
  
  
• LibertySAMLToken — Secures the Web service with the Liberty SAML Token Profile. Though similar to SAML-SenderVouches (see the fourth bullet above), this security profile complies with the processing rules defined by the Liberty Alliance Project.

Now go to Part 2 for the process flow and Exercises 1 and 3. Then move on to Part 3: Exercises 4 and 5.