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.
Message security (JSR 196) is supported only in the full GlassFish Server, not in the Web Profile.
In this release of the GlassFish Server, message layer annotations are not supported.
For more information about web services, see Chapter 6, Developing Web Services.
For more information about message security, see the following:
Chapter 29, Introduction to Security in the Java EE Platform, in The Java EE 6 Tutorial
Chapter 13, Administering Message Security, in Oracle GlassFish Server 3.0.1 Administration Guide
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 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.0.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 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 OpenSSO 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 GlassFish Server deployment descriptor files, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.
For information about configuring these providers in the GlassFish Server, see Chapter 13, Administering Message Security, in Oracle GlassFish Server 3.0.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 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.0.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 5–2 Message Security Provider Properties
Property |
Default |
Description |
---|---|---|
domain-dir/config/wss-server-config-1.0.xml |
Specifies the location of the message security configuration file. To point to a configuration file in the domain-dir/config directory, use the system property ${com.sun.aas.instanceRoot}/config/, for example: ${com.sun.aas.instanceRoot}/config/wss-server-config-1.0.xml See System Properties. |
|
false |
If true, enables dumping of server provider debug messages to the server log. |
|
false |
If true, signals the provider runtime to collect the user name and password from the CallbackHandler for each request. If false, the user name and password for wsse:UsernameToken(s) is collected once, during module initialization. This property is only applicable for a ClientAuthModule. |
|
s1as |
Specifies the encryption key used by the provider. The key is identified by its keystore alias. |
|
s1as |
Specifies the signature key used by the provider. The key is identified by its keystore alias. |
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 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 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.
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.
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. System administrator tasks are discussed in Chapter 13, Administering Message Security, in Oracle GlassFish Server 3.0.1 Administration Guide.
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.0.1 Application Deployment Guide.
For sun-ejb-jar.xml, see The sun-ejb-jar.xml File in Oracle GlassFish Server 3.0.1 Application Deployment Guide.
For sun-web.xml, see The sun-web.xml File in Oracle GlassFish Server 3.0.1 Application Deployment Guide.
For sun-application-client.xml, see The sun-application-client.xml file in Oracle GlassFish Server 3.0.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 13, Administering Message Security, in Oracle GlassFish Server 3.0.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 13, Administering Message Security, in Oracle GlassFish Server 3.0.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 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.
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 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.
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 Ant 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 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.