by Ashutosh Shahi

Metro is a high performance, extensible, easy to use web service 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 Sun Java System Application Server 9.1. Metro also runs in other containers such as Tomcat.

The March 2007 Tech Tip, Securing Web Services Using WSIT, focused on WSIT's support for web services security and showed how to secure a web service using WSIT's features. It was followed by the October 2007 Tech Tip, Testing Interoperability Between Metro and .NET, which showed a sample that demonstrates interoperability between Metro and .NET. This Tech Tip builds on the March 2007 tip. It shows how to build secure web services and clients using the Kerberos support in Metro. Kerberos support has been added to the security support provided by WSIT for Metro 1.1. Future releases of Metro will continue to include this added support. The support for Kerberos security in WSIT is based on the WSS:Kerberos Token Profile 1.1 implementation. You request Kerberos security in Metro using WS-SecurityPolicy assertions -- these assertions are covered in the "Securing Web Services Using WSIT" tip.

A sample application package accompanies this tip. The code examples in the tip are taken from the source code of the sample (which is included in the package). The sample application is similar to the one used in the "Securing Web Services Using WSIT" tip. The major difference is that the WS-SecurityPolicy assertions in the sample application for this tip specify Kerberos tokens and consequently the messages are secured using the Kerberos V5 protocol.

Introduction to Kerberos

Kerberos is a network authentication service developed as part of Project Athena at the Massachusetts Institute of Technology. The protocol is named after Cerberus, known in Greek mythology as the three-headed monstrous dog who guards Hades.

Kerberos assumes that network connections, rather than servers, are the weak links in network security, and so interactions between hosts and clients should be encrypted. Kerberos uses a trusted third party, termed a Key Distribution Center (KDC), which consists of two separate logical parts: an Authentication Server (AS), and a Ticket Granting Server (TGS). The KDC maintains a database of secret keys. Each entity in the network, whether it's a client or a server, shares a secret key known only to itself and to the KDC. Knowledge of this key serves to prove an entity's identity.

For communication between two entities such as a client and a service, the KDC generates a session key which the entities can use to secure their interactions. Figure 1 shows the steps taken to secure a client's access to a service:

Figure 1. Securing Client Access to a Service Using Kerberos

1. A user enters a user name and password on the client. The client executes a one-way hash function on the password to generate a secret key for the user. The client sends a cleartext request to the AS to request a Ticket Granting Ticket (TGT). This TGT is later used by the client to request tickets for any specific service.
2. The AS checks to see if the client is in its database. If the client is in the database, the AS generates a reply containing the following:
   • A session key encrypted with the secret key of the user. The encrypted session key is kept in secret between the client and the TGS.
   • A TGT encrypted using the secret key of the TGS.
3. The client obtains the encrypted session key from the above message and decrypts it. This session key is used for further communication with the TGS. Note that the client cannot decrypt the TGT because the TGT is encrypted using the TGS's secret key. When the client requests access to services, it sends a message to the TGS composed of the following:
   • The TGT obtained in Step 2 and the ID of the requested service.
   • An authenticator that includes a client ID and timestamp.
   • The authenticator is encrypted using the client/TGS session key.
4. When it receives the message from the client, the TGS decrypts the TGT using its secret key. This gives the TGS the client/TGS secret key. The TGS verifies the authenticator using this secret key. If the verification is successful, the TGS sends the following to the client:
   • A client-to-server ticket that includes the client ID, validity period, client/server session key, as well as other information. The client-to-server ticket is encrypted using the service's secret key.
   • The client/server session key encrypted with the client/TGS session key.
5. The client decrypts the client/server session key, and now has enough information to authenticate itself to the service. The client sends the following to the service for authentication:
   • The encrypted client-to-server ticket.
   • A new authenticator that includes the client ID and timestamp. The new authenticator is encrypted using the client/server session key.
6. The service decrypts the ticket using its own secret key and verifies the authenticator. If mutual authentication is not enabled (this is discussed later in this tip), the server is now ready to provide the requested services to the client. Also, communication between the client and the service can be secured using this client-to-server secret key.

Setting up Kerberos

This tip assumes that you have Kerberos set up in a UNIX environment. If you need information on how to set up Kerberos in the Solaris or Ubuntu Linux environments, see the following documents:

• Solaris 10: Installing a Kerberos KDC
• Ubuntu Linux: Kerberos On Ubuntu

Note that in a Windows environment you can set up a Kerberos KDC only on Window Server editions 2000 and 2003. The KDC is bundled in these editions with its own Kerberos implementation called Active Directory. You cannot install the MIT Kerberos KDC on Windows. A Windows XP system can act as a client of the Windows Server 2003 KDC. Alternatively, you can install a client module of MIT Kerberos for Windows -- see Kerberos for Windows Release 3.2.2. You can then use the client module to authenticate against a KDC that was set up on a UNIX system.

After you set up Kerberos, make sure that the following DNS lookups to the KDC are working correctly.

   # nslookup [kdc_hostname]
   # nslookup [kdc_ip]

For example, you might enter the following command:

   nslookup ashu07.india.sun.local

In response, you should see the IP address of your system, such as 129.158.229.84. Similarly, if you enter the following command:

   nslookup 129.158.229.84

You should see the hostname of your KDC such as ashu07.india.sun.local. The idea here is that the DNS server is able to resolve the hostname of your KDC correctly.

Next, add user accounts for the client and service that will be used in this tip, as follows:

• Create a user principal for your Kerberos account by entering the following command:

     # kadmin.local -q "addprinc admin/admin"
          [type password]
  

  The user principal is used to administer the Kerberos account.
• Add user accounts for the Kerberos client and service by entering the following commands:

     #kadmin.local -p admin/admin
      kadmin.local: addprinc -randkey -e
      "es128-cts-hmac-sha1-96:normal"
      [service_principal]
         (Ex of service_principal: websvc/service)
      kadmin.local: addprinc -e "aes128-cts-hmac-sha1-96:normal"
      [client_principal]
      [type password]
         (Ex of client_principal: testClient)
      kadmin.local: ktadd -e  "aes128-cts-hmac-sha1-96:normal "
      [service_principal]
      kadmin.local: quit
  

• Login to the Kerberos account that you created by entering the following command:

     #kinit [client_principal]
          [type password]
  

Kerberos Security With Metro and GlassFish

Metro 1.1 (and future releases) enables secure communication of SOAP messages between a client and a service using Kerberos V5 protocol. The Introduction to Kerberos section presented the steps in securing communication between a client and a service using Kerberos. Let's examine how those steps are performed using the Kerberos support in Metro.

• Step 1 and 2: A user (that is, the client) logs into the pertinent account, for example using the kinit command, or the client obtains a new TGT.
• Step 3: Before accessing a service, the client accesses the name of the service principal from a configuration file named wsit-client.xml used in Metro (the wsit-client.xml file is discussed later in the tip) and requests a ticket for the service principal from the KDC.
• Step 4: If the client has valid credentials, the KDC grants the client a ticket for the service and a secret key to be used with the service.
• Step 5: All the communication in the previous steps takes place outside of SOAP messages. However at this point communication is performed using SOAP messages. After the client has the ticket for the service and secret key, it sends the ticket and authenticator to the service enclosed in a BinarySecurityToken element in the SOAP Security header. The client also secures any protected information in the SOAP message using the secret key for this session.
• Step 6: The service decrypts the ticket to obtain the session key and verifies the authenticator. If the authentication is successful, the service uses the secret key to verify the integrity or confidentiality of the protected parts of the message.

Creating a Kerberos Token-Based SecurityPolicy for the Service

To enable security for a web service with WSIT, you need to create and attach a security policy to the Web Services Definition Language (WSDL) file for the service. In general, there are two types of security policies you need to create for the web service: binding level policy and operational level policy. See the Securing Web Services Using WSIT tip for an explanation of these policies. The binding level policy shown in that tip needs to be changed to specify the use of Kerberos tokens. A Kerberos token here is the ticket and authenticator enclosed in the BinarySecurityToken element in the SOAP Security header as described in Step 5 above.

   <wsp:Policy wsu:Id="IFinancialService_policy">
   <wsp:ExactlyOne>
      <wsp:All>
          <wsaws:Us"http://www.w3.org/2006/05/addressing/wsdl"/>
          <sp:SymmetricBinding>
             <wsp:Policy>
                 <sp:ProtectionToken>
                     <wsp:Policy>
                         <sp:KerberosToken sp:IncludeToken=
   "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Once">
                             <wsp:Policy>
                                <!--<sp:RequireDerivedKeys />-->
                                <sp:WssGssKerberosV5ApReqToken11/>
                             </wsp:Policy>
                         </sp:KerberosToken>
                     </wsp:Policy>
                 </sp:ProtectionToken>
                 ...
                 <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128/>
                     </wsp:Policy>
                 </sp:AlgorithmSuite>
               </wsp:Policy>
           </sp:SymmetricBinding>
           ...
           <sc:KerberosConfig xmlns:sc=
           "http://schemas.sun.com/2006/03/wss/server"
           loginModule="KerberosServer"/>
      </wsp:All>
   </wsp:ExactlyOne>
   </wsp:Policy>

Notice the <sp:KerberosToken> element. This is the Kerberos token assertion. It asserts that the Kerberos token from the client is required to authenticate the client to the service and to protect the message. The WssGssKerberosV5ApReqToken11 element specifies that GSS-wrapped Kerberos v5 tokens will be used in the messages, as specified in the The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2, RFC4121.

Also notice the <sc:KerberosConfig> element. It specifies the name of the Java Authentication and Authorization Service (JAAS) login module to use with Kerberos. This JAAS login module, which is KerberosServer in the example, is specified in the <AS_HOME>/domains/domain1/config/login.conf file as shown in the Running the Sample Code section of the tip.

The operation level policy used in the sample is same as in the "Securing Web Services Using WSIT" tip. It specifies that the body and addressing headers should be signed and the body should be encrypted.

Deploying the Web Service

You can build and deploy a WSIT security-enabled web service in the same way as a regular JAX-WS based web service. For information on how to build a JAX-WS based web service, see the tip Developing Web Services Using JAX-WS.

Creating the Client

After you deploy the web service, you can access it from a client program. The steps for building a client that accesses a JAX-WS based web service are described in the tip Developing Web Services Using JAX-WS. However, to build a client that accesses a secured web service through WSIT, you need to configure security for the client.

Configuring Security Information For the Client

To configure security for a client you specify security-related information in a file named wsit-client.xml. This file, which contains a WSDL document, specifies the local security policies to be used by the client and the policies obtained from the service WSDL.

A standalone client, FinancialServiceClient.java, is provided in the sample application package that accompanies this tip. Here is the security configuration for the client in the wsit-client.xml file:

   <wsp:Policy wsu:Id="ClientKerberosPolicy"
     xmlns:sc="http://schemas.sun.com/2006/03/wss/client"
     xmlns:wspp="http://java.sun.com/xml/ns/wsit/policy"
     xmlns:scc="http://schemas.sun.com/ws/2006/05/sc/client">
       <wsp:ExactlyOne>
           <wsp:All>
            <sc:KerberosConfig wspp:visibility="private"
         loginModule="KerberosClient"
            servicePrincipal="websvc/service@INDIA.SUN.COM"
               credentialDelegation="true" />
           </wsp:All>
       </wsp:ExactlyOne>
   </wsp:Policy>

This sample local policy has an element which specifies the name of the JAAS login module to be used with Kerberos on the client. The name is specified in the loginModule attribute. This JAAS login module, KerberosClient in the example, is specified in the <AS_HOME>/domains/domain1/config/login.conf file as shown in the Running the Sample Code section of this tip. The servicePrincipal attribute specifies the name of the service principal for which the client should request a ticket from the KDC. The credentialDelegation element indicates whether the client credentials should be delegated to the service -- in this example, it should. Credential delegation is useful if the server wants to initiate other security contexts on behalf of the client, something that's important for single sign-on in a multi-tier environment.

Running the Sample Code

A sample package accompanies this tip. To install and run the sample:

1. If you haven't already done so, download JDK 6 from the Java SE Downloads page and install it. The Kerberos support in Metro works only with JDK 6 and later releases.
2. If you haven't already done so, download the Java EE 5 SDK Update 4 from the Java EE Downloads page and install it.
3. Download Metro 1.1 from the Metro Project site and follow the installation instructions on the WSIT Documentation page.
4. Set the WSIT_HOME system property as follows:
   • Open the file <AS_HOME>/domains/domain1/config/domain.xml in a text editor, where <AS_HOME> is the installation directory in which you installed Java EE 5 SDK Update 4.
   • Add the following JVM options to the file:

        <jvm-options>-DWSIT_HOME=${com.sun.aas.installRoot}
        </jvm-options>
        <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>
     

5. Specify the JAAS login modules to be used for Kerberos in the <AS_HOME>/domains/domain1/config/login.conf file, as follows:

      KerberosClient {
        com.sun.security.auth.module.Krb5LoginModule required
        useTicketCache=true;
      };
   
      KerberosServer {
        com.sun.security.auth.module.Krb5LoginModule required
        useKeyTab=true keyTab="/etc/krb5.keytab"
        doNotPrompt=true storeKey=true
        principal="websvc/service@INDIA.SUN.LOCAL";
                };
   

   You can give any names to the login modules, that is, instead of KerberosClient and KerberosServer. You need to refer to these names in the <sc:KerberosConfig> assertion in the WSDL file and in the wsit-client.xml file.

   Also edit the principal in KerberosServer to the service_principal that you created.

6. Download the sample package for the tip and extract its contents. You should now see the newly extracted directory as <sample_install_dir>/wssec-kerb, where <sample_install_dir> is the directory in where you installed the sample package.
7. Change to the wssec-kerb/src/fs directory. In the build.properties file set java.home. to the location of the JDK on your system. Set glassfish.home to the installation directory of Java EE 5 SDK Update 4.
8. Run the sample by entering the following command:

      ant run-sample
   

   You should see the following response:

      balance=1,000,000
      Acknowledgement : successfully deposited.
   

   You can view the message flows by examining the log file for the application server in the <AS_HOME>/domains/domain1/logs directory.

About the Author

Ashutosh Shahi is a member of the Web Services Security group at Sun Microsystems. He currently works on implementation of WS-* technologies related to security in the Metro web services stack from Sun. Before joining Sun, Ashutosh worked on the development of Apache Axis, an open source SOAP engine from Apache.

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

Connect and Participate With GlassFish
Try GlassFish for a chance to win an iPhone. This sweepstakes ends on March 23, 2008. Submit your entry today.