Secure Conversations for Web Services With Metro

by Jiandong Guo

Metro is a high performance, extensible, easy-to-use web services stack. It combines the JAX-WS reference implementation with Project Tango. Project Tango, also called Web Services Interoperability Technology or WSIT, implements numerous WS-\* standards to enable interoperability with other implementations and to provide Quality of Service (QOS) features such as security, reliability, and transaction support. Metro is bundled as part of the open source application server called GlassFish v2 and the commercial offering, Sun Java System Application Server 9.1. Metro also runs in other containers such as Tomcat.

An earlier Tech Tip, Securing Web Services Using WSIT introduced Metro's support (through WSIT) for web services security. This support implements the following web services security specifications published by the Organization for the Advancement of Structured Information Standards (OASIS) consortium: WS-Security, WS-SecurityPolicy, WS-SecureConversation, and WS-Trust. The tip also showed examples of using the WS-Security support in Metro. The following tip focuses on the support in Metro for WS-SecureConversation. You will learn the basics of WS-SecureConversation and see examples of using the WS-SecureConversation support in Metro.

A sample application package accompanies the tip. The sample application demonstrates how to enable secure conversations in Metro for a web service. You can enable secure conversations for a web service manually by coding appropriate policy assertions in the Web Services Definition Language (WSDL) file for the service. However, the NetBeans IDE offers an easier, more automated way to enable secure conversations in Metro for a web service. Because of this, the sample in this tip uses NetBeans, specifically NetBeans IDE 6.0.1. The sample also uses GlassFish v2 UR1.

An Introduction to WS-SecureConversation

WS-SecureConversation is a web services specification designed to enable secure communication between web services. The specification is built on top of two other web services specifications: WS-Security and WS-Trust. WS-Security provides the basic framework for message level security in web services and WS-Trust specifies a framework for brokered trust across different security domains. WS-Security and WS-Trust were covered in the tip Securing Web Services Using WSIT.

The objective of WS-SecureConversation is to enable secure messaging between a client and a web service, especially in situations where they exchange multiple messages. WS-Security is useful for securing simple one-way messages. However, to securely exchange multiple messages, a client and a web service typically require a security context in which to exchange the messages. WS-SecureConversation provides just such a context. It adds a "handshake" process, shown in Figure 1, that allows a web service and its client to authenticate to each other and to establish a shared security context. The security context is shared by the client and web service for the lifetime of a communication session. This context contains a shared secret key that can be used to secure subsequent messages between the client and service, and can significantly improve performance by avoiding repeated key exchanges in multi-message exchange scenarios.

WS-SecureConversation Handshake Process

Figure 1. WS-SecureConversation Handshake Process

In WS-SecureConversation, a SecurityContextToken, typically obtained from a Security Token Service (STS), is used to describe the security context. An STS, introduced in the WS-Trust specification, is trusted by both the client and the web service to provide interoperable security tokens.

Here is an example of a shared security token:

   <wsc:SecurityContextToken
    xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'
    xmlns:wsc='http://schemas.xmlsoap.org/ws/2004/04/sc'>
     <wsu:Identifier>uuid:...</wsc:Identifier>
     <wsu:Created>2008-03-07T08:24:05</wsu:Created>
     <wsu:Expires>2008-03-08T09:24:06</wsu:Expires>
    <wsse:Keys>
     <xenc:EncryptedKeyId="...">...</EncryptedKeyId>
     <wsse:SecurityTokenReference>... </wsse:SecurityTokenReference>
     ...
    </wsse:Keys>
   </wsc:SecurityContextToken>

The <SecurityContextToken> element describes the security context. The <Identifier> element identifies the security context using an absolute Uniform Resource Identifier (URI). Notice too that the creation and expiration date of the shared security token are also specified. The <Keys> element specifies the shared secret key of the security context.

WS-SecureConversation also introduces key derivation mechanisms that enhance overall security. These mechanisms can use different algorithms for deriving keys. Although a shared secret can be used to sign or encrypt messages, the WS-SecureConversation specification recommends that messages be signed or encrypted using derived keys. Using a common secret, a client and a web service can define different key derivations to use. It's possible, for example, to derive four keys so that a client and a web service can sign and encrypt using separate keys. The key derivation mechanisms are not only used within the shared security context, that is, with a SecurityContextToken, but can also be used with other security tokens such as those used in WS-Security.

WS-SecureConversation in Metro

Metro supports WS-SecureConversation within the general framework of WS-Security, WS-SecurityPolicy, and WS-Trust. Each web service enabled for WS-SecureConversation has an associated STS that is used to issue and manage security contexts. Managing a security context might include tasks such as renewing or canceling the security context. An extensible SessionManager on the server can be used to persist the security contexts so that the contexts can be used in a "web farm" (a site that uses multiple servers to deliver its content) in support of failover and high availability. By default, the SessionManager stores the security contexts in memory, but you can extend the SessionManager to store the session in a database.

Metro specifies a WS-SecureConversation through a <sp:SecureConversationToken> policy assertion. Security requirements for the WS-SecureConversation messages are specified by the <sp:BootstrapPolicy> element inside the <sp:SecureConversationToken> policy assertion. No run-time API is required.

Security contexts and derived keys are represented in Metro by their corresponding tokens, <SecurityContextToken> and <DerivedKeyToken>, which are used in securing application messages within the general mechanisms introduced in WS-Security.

Here is part of a policy assertion in Metro that includes a WS-SecureConversation specification:

   <ns3:SecureConversationToken ns3:IncludeToken="
    http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
     <wsp:Policy>
       <wsp:ExactlyOne>
         <wsp:All
    <ns3:BootstrapPolicy>
     <wsp:Policy>
       <wsp:ExactlyOne>
       ...
       <ns3:AlgorithmSuite>
     <wsp:Policy>
       <wsp:ExactlyOne>
       ...
       </wsp:ExactlyOne>
     </wsp:Policy>
       </ns3:AlgorithmSuite
       <ns3:IncludeTimestamp/>
       ...
       <ns3:X509Token ns3:IncludeToken=
        "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
       ...
       <ns3:WssX509V3Token10/>
       ...
       <ns3:OnlySignEntireHeadersAndBody/>
       ...
       <ns3:WssX509V3Token10/
       ...
     </ns3:BootstrapPolicy>
     ...
       </wsp:Policy>
   </ns3:SecureConversationToken>

Here is an example of a SecurityContextToken and DerivedKeyToken:

   <wsc:SecurityContextToken>
     <wsc:Identifier>urn:uuid:4d651587-8443-4874-8e01-308a8b2fb8f8</wsc:Identifier>
   </wsc:SecurityContextToken>

   <wsc:DerivedKeyToken
     <wsse:SecurityTokenReference>
       <wsse:Reference
         ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct"
          URI="urn:uuid:4d651587-8443-4874-8e01-308a8b2fb8f8" />
     </wsse:SecurityTokenReference>
     <wsc:Offset>0</wsc:Offset>
     <wsc:Length>24</wsc:Length>
     <wsc:Nonce>uE/cm2f0wuq5C7e2sJTvY704</wsc:Nonce>
   </wsc:DerivedKeyToken>

Security Profiles

As mentioned earlier, the NetBeans IDE offers an easier, more automated way to enable secure conversations in Metro for a web service. One of the ways it does this is by providing a set of security profiles that specify the mechanism to be used in securing conversations. The profiles are:

  • Username Authentication with Symmetric Keys
  • Mutual Certificates Security
  • Transport Security (SSL)
  • Message Authentication over SSL
  • SAML Authorization over SSL
  • Endorsing Certificate
  • SAML Sender Vouches with Certificates
  • SAML Holder of Key
  • STS Issued Token
  • STS Issued Token with Service Certificate
  • STS Issued Endorsing Token

You specify one of these mechanisms when you configure security for a web service using the NetBeans IDE as shown in Figure 2.

Configurating Security for a Web Service in NetBeans

Figure 2. Specifying a Security Profile for a Web Service

You can enable a secure conversation with any of the security mechanisms simply by clicking the Configure button next to the security mechanism selection. This opens a secondary window for that security mechanism. Then select the "Establish Secure Session (Secure Conversation)" checkbox in the secondary window as shown in Figure 3.


Configurating Security for a Web Service in NetBeans

Figure 3. Establishing a Secure Conversation for an Web Service

When you build and run the web service, the handshake process will be used to establish a secure session between the web service and its client. In general, if you want to secure a web service for more than one message in a transaction, you should enable a secure conversation.

Running the Sample Code

A sample application package accompanies the tip. To install and run the sample do the following:

  1. If you haven't already done so, download NetBeans IDE 6.0.1 and GlassFish v2 UR1.
  2. Start the NetBeans IDE.
  3. If GlassFish v2 is not one of the NetBeans application servers, add it as follows:
    • Right-click the Servers node in the Services window.
    • Select Add Server.
    • Select GlassFish v2.
    • Click the Next button.
    • Click the Browse button and browse to the location that you installed GlassFish v2.
    • Click the Choose button.
    • Click the Next button.
    • Set the Admin Password to the default, adminadmin, unless you chose a different password for GlassFish.
    • Click the Finish button.
  4. Add testing certificates to GlassFish as follows:
    • Download the copyv3.zip file from the xwss : Document & files page and unzip the file. You should see a newly extracted directory copyv3.
    • Change to the copyv3 directory.
    • Open the build.xml file and set the AS_HOME variable to the location where you installed GlassFish v2.
    • Run the ant command. This copies the sample certificates to the GlassFish v2 application server keystores for use with the sample. You can find ant in the <GF_install_dir>\\lib\\ant\\bin directory, where <GF_install_dir> is the directory where you installed GlassFish v2.
  5. Download the sample package and extract its contents. You should now see a newly extracted directory sc_samples.
  6. Change to the sc_samples\\lib directory. Copy the hook.jar file to the GF_install_dir\\lib directory.
  7. Open the CalculatorServiceSC project in theNetBeans IDE as follows:
    • Select Open Project from the File menu.
    • Browse to the sc_samples directory from the sample application download.
    • Select CalculatorServiceSC in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorServiceSC is a simple calculator service that was created using the NetBeans IDE. It uses the Mutual Certificates Security profile and is enabled for secure conversation. You can see the security configuration for CalculatorServiceSC by expanding its Web Services node in the Projects window. Then right-click on CalculatorSC in the Web Services node and select Edit Web Services Attributes as shown in Figure 4.

    Viewing Web Service Attributes

    Figure 4. Viewing Web Service Attributes

  8. Run the CalculatorServiceSC project as follows:
    • Right-click the CalculatorServiceSC node in the Projects window.
    • Select Run.

    In response, the CalculatorServiceSC service is deployed to the GlassFish v2 application server and the WSDL file for the web service is published to http://localhost:8080/CaculatorServiceSC/CaculatorSCService?wsdl.

    If you examine the WSDL file, you'll notice that it includes a <sp:SecureConversationToken> policy assertion and a <sp:BootstrapPolicy> element inside the policy assertion.

       <ns3:SecureConversationToken ns3:IncludeToken=
        "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
         <wsp:Policy>
          <wsp:ExactlyOne>
           <wsp:All>
            <ns3:BootstrapPolicy>
             <wsp:Policy>
              <wsp:ExactlyOne>
               <wsp:All>
       ...
    

    In other words, the NetBeans IDE generates the appropriate WSDL specifications for a secure conversation based on the security profile and secure conversation selection that were made when the web service was created. You do not have to specify the WSSecureConversation-related specifications in the WSDL file manually.

  9. Open the CalculatorClientSC project with the NetBeans IDE as follows:
    • Select Open Project from the File menu.
    • Browse to the sc_samples directory from the sample application download.
    • Select CalculatorClientSC in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorClientSC is the client for the CalculatorServiceSC service.

  10. Run the CalculatorClientSC project as follows:
    • Right-click the CalculatorClientSC node in the Projects window.
    • Select Run.

    You should see the results similar to those shown in Figure 5.

    Viewing Web Service Attributes

    Figure 5. CalculatorClientSC Result

  11. Open the CalculatorService project with the NetBeans IDE as follows:

    • Select Open Project from the File menu.
    • Browse to the sc_samples directory from the sample application download.
    • Select CalculatorService in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorService is a simple calculator service that was created using the NetBeans IDE. It uses the Mutual Certificates Security profile, but is not enabled for secure conversation. You can see the security configuration for CalculatorService in the same way as you did for CalculatorServiceSC.

  12. Run the CalculatorService project as follows:
    • Right-click the CalculatorService node in the Projects window.
    • Select Run.

    In response, the CalculatorService service is deployed to the GlassFish v2 application server and the WSDL file for the web service is published to http://localhost:8080/CaculatorService/CaculatorService?wsdl.

    If you examine the WSDL file, you'll notice that it does not include any WSSecureConversation-related specifications. In particular, there is no <sp:SecureConversationToken> policy assertion or <sp:BootstrapPolicy> element in the WSDL file.

  13. Open the CalculatorClient project with the NetBeans IDE as follows:
    • Select Open Project from the File menu.
    • Browse to the sc_samples directory from the sample application download.
    • Select CalculatorClient in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorClient is the client for the CalculatorService service.

  14. Run the CalculatorClient project as follows:
    • Right-click the CalculatorClient node in the Projects window.
    • Select Run.

    You should see the results similar to those shown in Figure 6.

    Viewing Web Service Attributes

    Figure 6. CalculatorClient Result

    Compare the running times for each project in the displayed Time value. Notice that it takes much less time to run the calculator service with secure conversation enabled.

    Currently the client accesses the calculator service five times. You can adjust the number of times that the client calls the calculator service and see how it impacts the running times for each project.

About the Author

Jiandong Guo is a staff engineer and a senior member of the Application Server Web Services Security Group. He has lead the development of implementations and solutions based on WS-SecureConversation and WS-Trust in the Tango project.

-----------------------------------------------------------------------------------------------------------------------------

Java EE SDKs Refreshed
Update 4 versions of the Java EE 5 SDKs and Java Application Platform SDKs now offer multilingual support. The "+ JDK" bundles also include the latest Java SE 6 (JDK) Update 5. Download the SDKs now.


--------------------------------------------------------------------------------------

GlassFish With MySQL Cobundle Released
Sun Java System Application Server 9.1 Update 1 (GlassFish v2 UR1) is now available bundled with the MySQL Community Server open-source database. Read the Release Notes and this blog for details. Download it now.


Comments:

I run java client and all works fine, but when I run .Net client I get "Policy is null" in glassfish server.

Does any one knows what is wrong?

How need to be configured .Net client policy?

Thanks
Fredy

Posted by Fredy Estepa on May 30, 2008 at 02:08 AM PDT #

See http://forums.java.net/jive/thread.jspa?messageID=278115&#278115

for discussion on this. Very likely an old version of .Net used which only support old ws-addressing version.

Posted by Jiandong Guo on June 03, 2008 at 06:11 AM PDT #

Post a Comment:
Comments are closed for this entry.
About

edort

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today