Message security enables a server to perform end-to-end authentication of web service invocations and responses at the message layer. Security information is inserted into messages so that it travels through the networking layers and arrives with the intact message at the message destination(s). Message security differs from transport layer security in that message security can be used to decouple message protection from message transport so that messages remain protected after transmission.
Web services deployed on GlassFish Server are secured by binding SOAP layer message security providers and message protection policies to the containers in which the applications are deployed, or to web service endpoints served by the applications. SOAP layer message security functionality is configured in the client-side containers of GlassFish Server by binding SOAP layer message security providers and message protection policies to the client containers or to the portable service references declared by client applications.
Message-level security can be configured for the entire GlassFish Server or for specific applications or methods. Configuring message security at the application level is discussed in the Oracle GlassFish Server 3.1 Application Development Guide.
The following topics are addressed here:
WS-Security is a specification that provides a communications protocol for applying security to web services. The security mechanisms implement the specification. Web Services Interoperability Technologies (WSIT) implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing transport-level security, which can still be used.
The Simple Object Access Protocol (SOAP) layer message security providers installed with GlassFish Server can be used to employ username/password and X.509 certificate security tokens to authenticate and encrypt SOAP web services messages.
Username Tokens. GlassFish Server uses username tokens in SOAP messages to authenticate the message sender. The recipient of a message containing a username token (within embedded password) validates that the message sender is authorized to act as the user (identified in the token) by confirming that the sender knows the password of the user.
When using a username token, a valid user database must be configured on GlassFish Server.
Digital Signatures. GlassFish Server uses XML digital signatures to bind an authentication identity to message content. Clients use digital signatures to establish their caller identity. Digital signatures are verified by the message receiver to authenticate the source of the message content (which might be different from the sender of the message.)
When using digital signatures, valid keystore and truststore files must be configured on GlassFish Server.
Encryption. The purpose of encryption is to modify the data so that it can only be understood by its intended audience. This is accomplished by substituting an encrypted element for the original content. When based on public key cryptography, encryption can be used to establish the identity of the parties who are authorized to read a message.
When using encryption, a Java Cryptography Extension (JCE) provider that supports encryption must be installed.
The authentication layer is the message layer on which authentication processing must be performed. GlassFish Server enforces web services message security at the SOAP layer. The types of authentication that are supported include the following:
Sender authentication, including username-password authentication
Content authentication, including XML digital signatures
GlassFish Server invokes authentication providers to process SOAP message layer security. The message security providers provide information such as the type of authentication that is required for the request and response messages. The following message security providers are included with GlassFish Server:
Client-side Provider. A client-side provider establishes (by signature or username/password) the source identity of request messages and/or protects (by encryption) request messages such that they can only be viewed by their intended recipients. A client-side provider also establishes its container as an authorized recipient of a received response (by successfully decrypting it) and validates passwords or signatures in the response to authenticate the source identity associated with the response. Client-side providers configured in GlassFish Server can be used to protect the request messages sent and the response messages received by server-side components (servlets and EJB components) acting as clients of other services.
The default client provider is used to identify the client—side provider to be invoked for any application for which a specific client provider has not been bound.
Server-side Provider. A server-side provider establishes its container as an authorized recipient of a received request (by successfully decrypting it), and validates passwords or signatures in the request to authenticate the source identity associated with the request. A server-side provider also establishes (by signature or username/password) the source identity of response messages and/or protects (by encryption) response messages such that they can only be viewed by their intended recipients. Server-side providers are only invoked by server-side containers.
The default server provider is used to identify the server—side provider to be invoked for any application for which a specific server provider has not been bound.
A request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature. The response policy defines the authentication policy requirements associated with response processing performed by the authentication provider.
Message protection policies are defined for request message processing and response message processing. The policies are expressed in terms of requirements for source and/or recipient authentication. The providers apply specific message security mechanisms to cause the message protection policies to be realized in the context of SOAP web services messages.
Source Authentication Policy. A source authentication policy represents a requirement that the identity of the entity that sent a message or that defined the content of a message be established in the message such that it can be authenticated by the message receiver.
Recipient Authentication Policy. A recipient authentication policy represents a requirement that the message be sent such that the identity of the entities that can receive the message can be established by the message sender.
Request and response message protection policies are defined when a security provider is configured into a container. Application-specific message protection policies (at the granularity of the web service port or operation) can also be configured within the GlassFish Server deployment descriptors of the application or application client. In any situation where message protection policies are defined, the request and response message protection policies of the client must be equivalent t) the request and response message protection policies of the server. For more information about defining application-specific message protection policies, see Chapter 4, Securing Applications, in Oracle GlassFish Server 3.1 Application Development Guide
Application-specific web services security functionality is configured (at application assembly) by defining the message-security-binding elements in the GlassFish Server deployment descriptors of the application. These message-security-binding elements are used to associate a specific security provider or message protection policy with a web service endpoint or service reference, and might be qualified so that they apply to a specific port or method of the corresponding endpoint or referenced service.
For information about defining application-specific message protection policies, see Chapter 4, Securing Applications, in Oracle GlassFish Server 3.1 Application Development Guide.
When GlassFish Server is installed, SOAP layer message security providers are configured in the client and server-side containers of GlassFish Server, where they are available for binding for use by the containers, or by individual applications or clients deployed in the containers. During installation, the default providers are configured with a simple message protection policy that, if bound to a container, or to an application or client in a container, would cause the source of the content in all request and response messages to be authenticated by XML digital signature.
GlassFish Server administrative interfaces can be used as follows:
To modify the message protection policies enforced by the providers
To bind the existing providers for use by the server-side containers of GlassFish Server
To create new security provider configurations with alternative message protection policies
Analogous administrative operations can be performed on the SOAP message layer security configuration of the application client container. If you want web services security to protect all web services applications deployed on GlassFish Server. See Enabling Message Security for Application Clients.
By default, message layer security is disabled on GlassFish Server. To configure message layer security for the GlassFish Server see Enabling Default Message Security Providers for Web Services.
In most cases, you must restart GlassFish Server after performing administrative tasks. This is especially true if you want the effects of the administrative change to be applied to applications that were already deployed on GlassFish Server at the time the operation was performed.
The general implementation tasks for message security include some or all of the following:
If you are using a version of the Java SDK prior to version 1.5.0, and using encryption technology, configuring a JCE provider
If you are using a username token, verifying that a user database is configured for an appropriate realm
When using a username/password token, an appropriate realm must be configured and a user database must be configured for the realm.
Managing certificates and private keys, if necessary
Enabling the GlassFish Server default providers
Configuring new message security providers
In GlassFish Server, the administrator and the application deployer are expected to take primary responsibility for configuring message security. In some situations, the application developer might also contribute.
The system administrator is responsible for the following message security tasks:
Administering server security settings and certificate databases
Administering keystore and truststore files
Configuring message security providers on GlassFish Server
Turning on message security
(If needed) Installing the samples server
The application deployer is responsible for the following message security tasks:
Specifying (at application reassembly) any required application-specific message protection policies if such policies have not already been specified by the developer/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.
The application developer/assembler is responsible for the following message security tasks:
Determining if an application-specific message protection policy is required by the application
If so, the developer ensures that the required policy is specified at application assembly time.
Specifying how web services should be set up for message security
Message security can be set up by the administrator so that all web services are secured, or by the application deployer when the security provider or protection policy bound to the application must be different from that bound to the container.
Turning on message security if authorized to do so by the administrator
GlassFish Server includes a sample application named xms. The xms application features a simple web service that is implemented by both a Java EE EJB endpoint and a Java servlet endpoint. Both endpoints share the same service endpoint interface. The service endpoint interface defines a single operation, sayHello, which takes a string argument, and returns a String composed by pre-pending Hello to the invocation argument.
The xms sample application is provided to demonstrate the use of GlassFish Server WS-Security functionality to secure an existing web services application. The instructions which accompany the sample describe how to enable the WS-Security functionality of GlassFish Server such that it is used to secure the xms application. The sample also demonstrates the binding of WS-Security functionality directly to the application as described in Application-Specific Web Services Security application.
For information about compiling, packaging, and running the xms sample application, Chapter 4, Securing Applications, in Oracle GlassFish Server 3.1 Application Development Guide.
The xms sample application is installed in the following directory: as-install/samples/webservices/security/ejb/apps/xms/