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.
In this release of the Enterprise Server, message layer annotations are not supported.
For more information about message security, see the following:
The Java EE 5 Tutorial chapter titled “Chapter 29: Introduction to Security in Java EE”
JSR 196, Java Authentication Service Provider Interface for Containers
The Liberty Alliance Project specifications at http://www.projectliberty.org/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 web services security topics are discussed in this section:
When you first install the Enterprise 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 Admin 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 Admin Console.
You can enable the message security providers using the following commands.
asadmin set --user adminuser server-config.security-service.message-security-config.SOAP.default_provider=XWS_ServerProvider asadmin set --user adminuser server-config.security-service.message-security-config.SOAP.default_client_provider=XWS_ClientProvider |
For more information about the asadmin set command, see the Sun GlassFish Enterprise Server v2.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 asant targets are run. You don’t need to enable these on the Enterprise Server prior to running the example.
If you install the Access Manager, 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 sun-web.xml, sun-ejb-jar.xml, and sun-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 Access Manager for single sign-on. To use this provider, specify it in the httpservlet-security-provider attribute of the sun-web-app element in the sun-web.xml file.
Liberty specifications can be viewed at http://www.projectliberty.org/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 Sun-specific deployment descriptor files, see the Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.
For information about configuring these providers in the Enterprise Server, see Chapter 10, Configuring Message Security, in Sun GlassFish Enterprise Server v2.1.1 Administration 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 Admin Console, open the Security component under the relevant configuration, and select the Message Security component. For details, click the Help button in the Admin Console.
You can use the asadmin create-message-security-provider command to create a message security provider. For details, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.
In addition, you can set a few optional provider properties. For more information, see the property descriptions under provider-config in Sun GlassFish Enterprise Server v2.1.1 Administration Reference.
In the Enterprise 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 responsibilities of the various roles are defined in the following sections:
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 Enterprise Server level. If so, ensuring that this need is communicated to the system administrator, or taking care of implementing message security at the Enterprise Server level.
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 Sun-specific 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.
The system administrator is responsible for the following:
Configuring message security providers on the Enterprise 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 Admin 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 and you have selected the enterprise profile, certificates and private keys are stored in an NSS database, where they are managed using certutil. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide. System administrator tasks are discussed in Chapter 10, Configuring Message Security, in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.
When the Enterprise 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 Sun-specific 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 A, Deployment Descriptor Files, in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.
For sun-ejb-jar.xml, see The sun-ejb-jar.xml File in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.
For sun-web.xml, see The sun-web.xml File in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.
For sun-application-client.xml, see The sun-application-client.xml file in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.
This section contains the following topics:
Using a Signature to Enable Message Protection for All Methods
Configuring Message Protection for a Specific Method Based on Digital Signatures
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 sun-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 Chapter 10, Configuring Message Security, in Sun GlassFish Enterprise Server v2.1.1 Administration 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.
In a text editor, open the application’s sun-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.
Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:
<sun-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> </sun-ejb-jar>
Compile, deploy, and run the application as described in To Run the Sample Application.
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 sun-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 Chapter 10, Configuring Message Security, in Sun GlassFish Enterprise Server v2.1.1 Administration 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.
In a text editor, open the application’s sun-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.
Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:
<sun-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> </sun-ejb-jar>
Compile, deploy, and run the application as described in To Run 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 Enterprise 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.
This section includes the following topics:
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.
Go to the J2EE 1.4 download URL in your browser.
Click on the Download button for the Samples Bundle.
Click on Accept License Agreement.
Click on the J2EE SDK Samples link.
Choose a location for the j2eesdk-1_4_03-samples.zip file.
Saving the file to as-install is recommended.
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 |
Make sure that the Enterprise Server is running.
Message security providers are set up when the asant targets are run, so you do not need to configure these on the Enterprise Server prior to running this example.
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.
Change to the app-dir directory.
Run the following asant targets to compile, deploy, and run the example application:
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!
To undeploy the sample, run the following asant target:
asant 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.