Configuring Message Security for Web Services

In message security, security information is applied at the message layer and travels along with the web services message. Web Services Security (WSS) is the use of XML Encryption and XML Digital Signatures to secure messages. WSS profiles the use of various security tokens including X.509 certificates, Security Assertion Markup Language (SAML) assertions, and username/password tokens to achieve this.

Message layer security differs from transport layer security in that it can be used to decouple message protection from message transport so that messages remain protected after transmission, regardless of how many hops they travel.

For more information about web services, see Chapter 5, Developing Web Services.

For more information about message security, see the following:

• Chapter 39, Introduction to Security in the Java EE Platform, in The Java EE 6 Tutorial

• Oracle GlassFish Server 3.1 Security Guide

• JSR 196, Java Authentication Service Provider Interface for Containers

• The Liberty Alliance Project specifications at http://www.projectliberty.org/resources/specifications.php/?f=resources/specifications.php

• The Oasis Web Services Security (WSS) specification at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

• The Web Services Interoperability Organization (WS-I) Basic Security Profile (BSP) specification at http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html

• The XML and Web Services Security page at https://xwss.dev.java.net/

• The WSIT page at https://wsit.dev.java.net/

The following topics are addressed here:

• Message Security Providers

• Message Security Responsibilities

• Application-Specific Message Protection

• Understanding and Running the Sample Application

Message Security Providers

When you first install the GlassFish Server, the providers XWS_ClientProvider and XWS_ServerProvider are configured but disabled. You can enable them in one of the following ways:

• To enable the message security providers using the Administration Console, open the Security component under the relevant configuration, select the Message Security component, and select SOAP. Then select XWS_ServerProvider from the Default Provider list and XWS_ClientProvider from the Default Client Provider list. For details, click the Help button in the Administration Console.

• You can enable the message security providers using the following commands.

  asadmin set 
  server-config.security-service.message-security-config.SOAP.default_provider=XWS_ServerProvider
  asadmin set 
  server-config.security-service.message-security-config.SOAP.default_client_provider=XWS_ClientProvider

  For more information about the asadmin set command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

The example described in Understanding and Running the Sample Application uses the ClientProvider and ServerProvider providers, which are enabled when the Ant targets are run. You don’t need to enable these on the GlassFish Server prior to running the example.

If you install the OpenSSO, you have these additional provider choices:

• AMClientProvider and AMServerProvider – These providers secure web services and Simple Object Access Protocol (SOAP) messages using either WS-I BSP or Liberty ID-WSF tokens. These providers are used automatically if they are configured as the default providers. If you wish to override any provider settings, you can configure these providers in message-security-binding elements in the glassfish-web.xml, glassfish-ejb-jar.xml, and glassfish-application-client.xml deployment descriptor files.

• AMHttpProvider – This provider handles the initial end user authentication for securing web services using Liberty ID-WSF tokens and redirects requests to the OpenSSO for single sign-on. To use this provider, specify it in the httpservlet-security-provider attribute of the glassfish-web-app element in the glassfish-web.xml file.

Liberty specifications can be viewed at http://www.projectliberty.org/resources/specifications.php/?f=resources/specifications.php. The WS-I BSP specification can be viewed at http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html.

For more information about the GlassFish Server deployment descriptor files, see the Oracle GlassFish Server 3.1 Application Deployment Guide.

For information about configuring these providers in the GlassFish Server, see the Oracle GlassFish Server 3.1 Security Guide. For additional information about overriding provider settings, see Application-Specific Message Protection.

You can create new message security providers in one of the following ways:

• To create a message security provider using the Administration Console, open the Security component under the relevant configuration, and select the Message Security component. For details, click the Help button in the Administration Console.

• You can use the asadmin create-message-security-provider command to create a message security provider. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

In addition, you can set a few optional provider properties using the asadmin set command. For example:

asadmin set server-config.security-service.message-security-config.provider-config.property.debug=true

The following table describes these message security provider properties.

Table 4-2 Message Security Provider Properties

Message Security Responsibilities

In the GlassFish Server, the system administrator and application deployer roles are expected to take primary responsibility for configuring message security. In some situations, the application developer may also contribute, although in the typical case either of the other roles may secure an existing application without changing its implementation and without involving the developer.

The following topics are addressed here:

• Application Developer Responsibilities

• Application Deployer Responsibilities

• System Administrator Responsibilities

Application Developer Responsibilities

The application developer can turn on message security, but is not responsible for doing so. Message security can be set up by the system administrator so that all web services are secured, or set up by the application deployer when the provider or protection policy bound to the application must be different from that bound to the container.

The application developer is responsible for the following:

• Determining if an application-specific message protection policy is required by the application. If so, ensuring that the required policy is specified at application assembly which may be accomplished by communicating with the application deployer.

• Determining if message security is necessary at the GlassFish Server level. If so, ensuring that this need is communicated to the system administrator, or taking care of implementing message security at the GlassFish Server level.

Application Deployer Responsibilities

The application deployer is responsible for the following:

• Specifying (at application assembly) any required application-specific message protection policies if such policies have not already been specified by upstream roles (the developer or assembler)

• Modifying GlassFish Server deployment descriptors to specify application-specific message protection policies information (message-security-binding elements) to web service endpoint and service references

These security tasks are discussed in Application-Specific Message Protection. A sample application using message security is discussed in Understanding and Running the Sample Application.

System Administrator Responsibilities

The system administrator is responsible for the following:

• Configuring message security providers on the GlassFish Server.

• Managing user databases.

• Managing keystore and truststore files.

• Installing the sample. This is only done if the xms sample application is used to demonstrate the use of message layer web services security.

A system administrator uses the Administration Console to manage server security settings and uses a command line tool to manage certificate databases. Certificates and private keys are stored in key stores and are managed with keytool. If Network Security Services (NSS) is installed, certificates and private keys are stored in an NSS database, where they are managed using certutil. System administrator tasks are discussed in the Oracle GlassFish Server 3.1 Security Guide.

Application-Specific Message Protection

When the GlassFish Server provided configuration is insufficient for your security needs, and you want to override the default protection, you can apply application-specific message security to a web service.

Application-specific security is implemented by adding the message security binding to the web service endpoint, whether it is an EJB or servlet web service endpoint. Modify GlassFish Server XML files to add the message binding information.

Message security can also be specified using a WSIT security policy in the WSDL file. For details, see the WSIT page at https://wsit.dev.java.net/.

For more information about message security providers, see Message Security Providers.

For more details on message security binding for EJB web services, servlet web services, and clients, see the XML file descriptions in Appendix C, Elements of the GlassFish Server Deployment Descriptors, in Oracle GlassFish Server 3.1 Application Deployment Guide.

• For glassfish-ejb-jar.xml, see The glassfish-ejb-jar.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.

• For glassfish-web.xml, see The glassfish-web.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.

• For glassfish-application-client.xml, see The glassfish-application-client.xml file in Oracle GlassFish Server 3.1 Application Deployment Guide.

The following topics are addressed here:

• Using a Signature to Enable Message Protection for All Methods

• Configuring Message Protection for a Specific Method Based on Digital Signatures

Using a Signature to Enable Message Protection for All Methods

To enable message protection for all methods using digital signature, update the message-security-binding element for the EJB web service endpoint in the application’s glassfish-ejb-jar.xml file. In this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Oracle GlassFish Server 3.1 Security Guide. To apply the same protection mechanisms for all methods, leave the method-name element blank. Configuring Message Protection for a Specific Method Based on Digital Signatures discusses listing specific methods or using wildcard characters.

This section uses the sample application discussed in Understanding and Running the Sample Application to apply application-level message security to show only the differences necessary for protecting web services using various mechanisms.

To Enable Message Protection for All Methods Using Digital Signature

1. In a text editor, open the application’s glassfish-ejb-jar.xml file.

   For the xms example, this file is located in the directory app-dir/xms-ejb/src/conf, where app-dir is defined in To Set Up the Sample Application.

2. Modify the glassfish-ejb-jar.xml file by adding the message-security-binding element as shown:

   <glassfish-ejb-jar>
     <enterprise-beans>
       <unique-id>1</unique-id>
       <ejb>
         <ejb-name>HelloWorld</ejb-name>
         <jndi-name>HelloWorld</jndi-name>
         <webservice-endpoint>
           <port-component-name>HelloIF</port-component-name>
           <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
           <message-security-binding auth-layer="SOAP">
             <message-security>
               <request-protection auth-source="content" />
               <response-protection auth-source="content"/>
             </message-security>
           </message-security-binding>
         </webservice-endpoint>
       </ejb>
     </enterprise-beans>
   </glassfish-ejb-jar>

3. Compile, deploy, and run the application as described in To Run the Sample Application.

Configuring Message Protection for a Specific Method Based on Digital Signatures

To enable message protection for a specific method, or for a set of methods that can be identified using a wildcard value, follow these steps. As in the example discussed in Using a Signature to Enable Message Protection for All Methods, to enable message protection for a specific method, update the message-security-binding element for the EJB web service endpoint in the application’s glassfish-ejb-jar.xml file. To this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Oracle GlassFish Server 3.1 Security Guide. The administration guide includes a table listing the set and order of security operations for different request and response policy configurations.

This section uses the sample application discussed in Understanding and Running the Sample Application to apply application-level message security to show only the differences necessary for protecting web services using various mechanisms.

To Enable Message Protection for a Particular Method or Set of Methods Using Digital Signature

1. In a text editor, open the application’s glassfish-ejb-jar.xml file.

   For the xms example, this file is located in the directory app-dir/xms-ejb/src/conf, where app-dir is defined in To Set Up the Sample Application.

2. Modify the glassfish-ejb-jar.xml file by adding the message-security-binding element as shown:

   <glassfish-ejb-jar>
     <enterprise-beans>
     <unique-id>1</unique-id>
       <ejb>
         <ejb-name>HelloWorld</ejb-name>
         <jndi-name>HelloWorld</jndi-name>
         <webservice-endpoint>
           <port-component-name>HelloIF</port-component-name>
           <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
           <message-security-binding auth-layer="SOAP">
             <message-security>
               <message>
                 <java-method>
                   <method-name>ejbCreate</method-name>
                 </java-method>
               </message>
               <message>
                 <java-method>
                   <method-name>sayHello</method-name>
                 </java-method>
               </message>
               <request-protection auth-source="content" />
               <response-protection auth-source="content"/>
             </message-security>
           </message-security-binding>
         </webservice-endpoint>
       </ejb>
     </enterprise-beans>
   </glassfish-ejb-jar>

3. Compile, deploy, and run the application as described in To Run the Sample Application.

Understanding and Running the Sample Application

This section discusses the WSS sample application. This sample application is installed on your system only if you installed the J2EE 1.4 samples. If you have not installed these samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the xms example is a simple web service implemented using a Java EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, sayHello, which takes a string then sends a response with Hello prefixed to the given string. You can view the WSDL file for the service endpoint interface at app-dir/xms-ejb/src/conf/HelloWorld.wsdl, where app-dir is defined in To Set Up the Sample Application.

In this application, the client looks up the service using the JNDI name java:comp/env/service/HelloWorld and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response Hello Duke!

This example shows how to use message security for web services at the GlassFish Server level. For information about using message security at the application level, see Application-Specific Message Protection. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.

The following topics are addressed here:

• To Set Up the Sample Application

• To Run the Sample Application

To Set Up the Sample Application

Before You Begin

To have access to this sample application, you must have previously installed the J2EE 1.4 samples. If the samples are not installed, follow the steps in the following section.

After you follow these steps, the sample application is located in the directory as-install/j2ee14-samples/samples/webservices/security/ejb/apps/xms/ or in a directory of your choice. For easy reference throughout the rest of this section, this directory is referred to as simply app-dir.

1. Go to the J2EE 1.4 download URL in your browser.
2. Click on the Download button for the Samples Bundle.
3. Click on Accept License Agreement.
4. Click on the J2EE SDK Samples link.
5. Choose a location for the j2eesdk-1_4_03-samples.zip file.

   Saving the file to as-install is recommended.

6. Unzip the file.

   Unzipping to the as-install/j2ee14–samples directory is recommended. For example, you can use the following command.

   unzip j2eesdk-1_4_03-samples.zip -d j2ee14-samples

To Run the Sample Application

1. Make sure that the GlassFish Server is running.

   Message security providers are set up when the Ant targets are run, so you do not need to configure these on the GlassFish Server prior to running this example.

2. If you are not running HTTP on the default port of 8080, change the WSDL file for the example to reflect the change, and change the common.properties file to reflect the change as well.

   The WSDL file for this example is located at app-dir/xms-ejb/src/conf/HelloWorld.wsdl. The port number is in the following section:

   <service name="HelloWorld">
     <port name="HelloIFPort" binding="tns:HelloIFBinding">
       <soap:address location="http://localhost:8080/service/HelloWorld"/>
     </port>
   </service>

   Verify that the properties in the as-install/samples/common.properties file are set properly for your installation and environment. If you need a more detailed description of this file, refer to the “Configuration” section for the web services security applications at as-install/j2ee14–samples/samples/webservices/security/docs/common.html#Logging.

3. Change to the app-dir directory.
4. Run the following Ant targets to compile, deploy, and run the example application:
   1. To compile samples:

      ant

   2. To deploy samples:

      ant deploy

   3. To run samples:

      ant run

   If the sample has compiled and deployed properly, you see the following response on your screen after the application has run:

   run:[echo] Running the xms program:[exec] Established message level security : Hello Duke!

5. To undeploy the sample, run the following Ant target:

   ant undeploy

   All of the web services security examples use the same web service name (HelloWorld) and web service ports. These examples show only the differences necessary for protecting web services using various mechanisms. Make sure to undeploy an application when you have completed running it. If you do not, you receive an Already in Use error and deployment failures when you try to deploy another web services example application.